Specify a placeholder in the query editor by typing {{ <placeholder text> }}.

Alter the value of the placeholder in the query panel to change your query without editing any SQL code.

By default, a query parameter requires the user to input text. This text will be passed through to the data connector, which will run the SQL code with the input.

Once a query parameter is added, it is visible from right side panel.

Query Parameters: Dropdown

Instead of allowing users to enter any text for a query parameter, you can create a dropdown list for users to select from. Click Settings ⚙ above the query parameter, then select Dropdown.

Dropdown menus help users select parameters from columns they would otherwise not know to type. For example, while your dataset can contain foot traffic for a franchise located and grouped by several cities, a user may not know each city name offhand. A dropdown menu could contain a list of all cities, providing full visibility to the dataset.

Static Dropdown

This option can be useful for limiting user input. For example, if you only want users to see data from several days of the week (e.g. the first Monday of every month), your dropdown menu could contain just those dates rather than forcing the user to manually enter the date each time.

Dynamic Dropdown

Use the dynamic dropdown feature to select a specific column to use as a source for unique values. Studio will we store the result of the of the select distinct query, loading it on each subsequent dataset load. This option streamlines populating a dropdown list for a query parameter

Multi-Selection

When configuring a dropdown, toggle the Allow Multi-Selection checkbox to allow users to select multiple values for a single parameter. This can be useful when wanting to visualize multiple columns of data on a single layer.

By default, the concat delimiter is set to ",". You may change this to a delimiter that suits your team's standard workflow.

Edit Query Parameters in Studio

You can also quickly edit query parameters within Studio, without opening the data connector settings.

1. Navigate to the dataset in Studio then click Show SQL query parameters.

2. Click ⚙ Settings, make any changes to the query parameter settings, then click save.

The map will be updated with data derived from your new query.

Built-In Keyword Parameters

Data connectors can be supplied with built-in Keyword Parameters. These keywords are reserved parameter names that are replaced at query time with values representing the current state of the Studio map.

{{viewport}}

Retrieves the boundaries of the viewport as WKT polygons. Can be passed to select only items that fall within the user's current view. This query updates as the user pans the map, unloading any data outside of the viewport and loading the new data that falls within the bounds of the viewport.

Example SQL:

SELECT *
FROM PUBLIC.CENSUS_HEX_6
WHERE ST_WITHIN(
    ST_POINT(CENTER_LNG, CENTER_LAT),
    ST_GEOGRAPHYFROMWKT('{{viewport}}')
)

Example WKT output:

POLYGON ((-123.53713989257812 37.235248651837395, -121.15585327148438 37.235248651837395, -121.15585327148438 38.26136726838286, -123.53713989257812 38.26136726838286, -123.53713989257812 37.235248651837395))