Skip to main content

Query Library

Learn more about creating and sharing queries with the Query Library.

The Query Library lets you create, run, and share queries across your organization and between Retool apps. Queries in the library are similar to functions in JavaScript—you can define variables in them and they return a result. You can then “call” this query inside and across multiple Retool apps, so that you’re not copy pasting the same query everywhere.

Features and use cases​

Query Library supports:

  • Writing a query for any resource (SQL, Firebase, REST, etc.)
  • Sharing your queries with the rest of your organization
  • Defining variables for your query that you can use when importing it in apps
  • Maintaining and rolling back to a previous version of your query
  • Running queries in different environments
  • Downloading the results of a query as JSON or CSV

Example use cases:

  • Writing a SQL statement and sharing the link with your coworker
  • Writing a query that’s used across multiple Retool apps
  • Checking out an older version of a complicated SQL query
  • Storing a SQL snippet for later reference

Permissions​

Retool admins can configure who has access to the Query Library using permission groups. Note that currently, anyone given access to the Query Library has read and write access. Navigate to the permission group in Retool and select the Additional tab to set these permissions.

Setting Query library permissions

All queries are private when created. While private, they can only be read and updated by the creator. Users can choose to Share a query, which makes it accessible to the entire organization. You can only delete private queries, and after sharing a query, you can't make it private again.

Users only have access to queries if they have access to the resource used in the query. This holds true for shared queries as well.

Version history and source control​

Every time you save a query, Retool stores a snapshot, similar to a commit. You can click the Saved on text in the bottom right corner to view the history, see the differences between saves, and revert to a specific version. Both SQL-based and non-SQL resources have version history, but only SQL resources show a line by line diff of the changes.

When you select a specific version of an imported query in your Retool apps, you can use this history view to verify the differences.

If you use Source Control, you can also protect queries to track changes and share queries across Retool instances.

Reusable queries​

You can import shared queries from the Query Library into your Retool apps. This lets you avoid repetition and maintains a single source of truth for your organization. For example, instead of copy pasting the same query on monthly revenue into each app, you can maintain one in the Library.

By default, when you import a shared query into an app, it syncs with the latest version. You also have the option to choose a specific version instead.

For more details on reusing queries, check out this guide.

Variables​

Variables let you avoid hardcoding pieces of your queries, the same way you can inside a Retool app. In your app you might use select * from users where id = {{ textinput1.value }}, but in the Library, there are no other objects to reference. So, the Query library extracts unknown words inside {{ }}. In this case, you might write select * from users where id = {{ user_id }}, and the Library would pick out user_id and display it on the right.

Note that like in the regular Retool app, you can use JavaScript inside {{ }}. For example, you can:

  • Write expressions like {{ parseInt(user_id) }}
  • Write queries like select * from users where status = {{ age > 65 ? 'retired' : 'working' }}
  • Use libraries like moment or numbro inside {{ }}

For details on how variables work with Reusable queries, check out this guide on reusing queries.