Text parameter

Text parameters are replaced by an array of strings in your query. They are ideal for filtering data by category names or text-based identifiers—such as product types or admin regions.

Text Parameter Settings

When creating a text parameter, you'll configure:

Values

Define the list of selectable values shown in the control UI.

• Add manually: Enter values directly.

• Add from Source: Select a column from your data source to auto-populate the list with up to 1,000 distinct values.

  • You can sort the values by frequency or alphabetically, in ascending or descending order.

Naming

• 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: {{day_night}}.

Behavior

Under Selection mode, choose how many values a viewer can pick:

• Multiple values (default): Viewers can select any number of values. Existing maps keep this behavior, so nothing changes unless you switch it.

• Single value: Viewers pick exactly one value from a radio list. When you choose this mode, set the Default value that is selected when the map loads and that the control resets to. Use it when selecting more than one value would make the analysis wrong, not just busier.

In both modes the parameter is still replaced by an array of strings in your query, so your SQL does not change between modes. In single-value mode the array simply always contains one value.

Using Text Parameters in your SQL Query

Once the parameter is created, add the parameer to your SQL query using the SQL name:

SELECT * FROM `carto-demo-data`.demo_tables.fires_worldwide
WHERE daynight IN {{day_night}}

After adding the parameter, the control UI will appear in the right-side panel, allowing users to:

• Search values

• Enter custom text

• Select one or multiple categories, depending on the Selection mode you chose

Text parameters are replaced by an array of strings. Use SQL syntax that supports arrays—like IN—for proper evaluation.