How to use additional scope (additionalScope) in your queries

[victoria]

Why use additionalScope

When writing queries you'd like to reuse with different input value(s), Retool's additionalScope might be helpful! See our docs here and some more in depth examples below.

How to use additionalScope

1. The additionalScope option allows you to pass variables to the query that aren't already defined in the global scope (e.g. text1.value). In order to use additionalScope, you must first trigger a query in an event handler or using the .trigger() method in a JS query.
   

   

2. You can now pass the additionalScope argument to the .trigger() method
   

   

3. The additionalScope argument takes an object as its value. Within this object, you can add key:value pairs where the key is the name you'd like to give the variable and the value is the value of the variable.
   

   

4. You can now use the additionalScope data within the query editor.
   

   

Common Use Cases

The most common use case I've seen for additionalScope is triggering the same query for each item in an array (e.g. a list of selected IDs), and then returning all results together. Here is a community post that walks through it.

Another use case! You might want to execute the same query with a different filter. You can have 2 separate buttons that pass in a different value to filter by to the query using additionalScope.

1. Here, we have a query with a WHERE clause checking if the isChecked column is True or False based on the additionalScope.
   

   

2. Then we create a Table to display the data and 2 buttons. One to filter by Checked and the other to filter by Unchecked.
   

   

3. We then add a click event handler to each button to run a script that triggers the query with the additionalScope variable, where isChecked is set to either true or false.
   

   

4. You can now run the same query with different filters by clicking the buttons!
   

   

Updates

• 12/23/24: As of stable version 3.33, the Retool UI provides the option to specify the subset of variables in the query definition that will be provided via additionalScope upon query execution.
  
  
  
  This allows you to utilize additionalScope when triggering queries via event handlers!
  
  

Keep in mind

• The editor will highlight the additionalScope variable in red because the variable does not exist until the JS query runs, triggers the query and passes in the variable. This is expected and will still execute correctly.

• Multiple variables can be used within the additionalScope argument
  

  

• "additionalScope" won't work, additionalScope will