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 will appear in the parameters bar above the map, allowing users to:

• Search values

• Add custom values

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

Adding custom values

Users can filter by values that aren't in the parameter's list. Open the parameter, click the + button next to the search field, and type one or more values separated by commas in the Add custom values dialog.

Added values appear selected under Added values, above the default list. With Single value selection, only the first added value is selected.

Custom values are temporary. They stay available after resetting the parameter, and they are removed when you reload or close the page. They are never saved to the map.

The Add custom values dialog

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