Text parameter

Text parameters are replaced by an array of strings in your query. They are a good choice if you need to filter by an existing category in your data or a text identifier.

Text Parameter Settings

When creating a text parameter, there are a few settings to be defined:


In this section we can define the list of values that will be available for selection in the control UI.

  • Add manually: Directly add values into the list.

  • Add from Source: Select a column from your source to automatically add up to the most frequent distinct values to the list. Please note there is a cap of 1,000 values when retrieving using this method.

The above methods can be used in combination.You can start by manually adding values, then use the 'Add from Source' option to extend your existing list with additional values, and adjust it as necessary.


  • Display name: The name that will appear in the control UI.

  • SQL name: The name that needs to be used in your SQL query. It always has to be enclosed between double curly brackets, like: {{type_of_place}}.

Using Text Parameters in your SQL Query

Once the parameter is created, we should manually add it (using its SQL name) to one or more of your SQL Query data sources, like:

SELECT * FROM `carto-demo-data`.demo_tables.populated_places
WHERE featurecla IN {{type_of_place}}

After adding the parameter to your SQL query data sources, the control UI will appear in the right-side panel, allowing search, custom text input and multi-selection of values:

Text parameters in your queries are replaced by an array of strings with all the values selected using the control UI.

Make sure to use a SQL syntax that works well with arrays, like the IN operator

Last updated