A parameterized query utilizes user-defined variables to filter data. A query template is a graphical user interface for interacting with a pre-defined parameterized query without writing any SQL or SPARQL. Together, the two allow for a relationship between a data analyst and a business user to thrive. The analyst can build a parameterized query, and the business user can interact with it using the template. This allows for greater accessibility of your data across your organization, regardless of technical barriers.
It begins with the analyst, or the Query Creator...
When a Query Creator is in the query editor, they will see a green link above the editor reading “Create query template.”
Clicking this link displays the following dialog, illustrating how parameterized queries are used to generate query templates.
This popover is primarily for educational purposes, and does not portray an actual parameterized query or query template. Clicking the “Add sample statement” button will insert an example of a parameterized query into the query editor, along with some instructional comments.
The Query Creator can choose to modify this sample statement to fit their query’s needs, or add additional DECLARE statements using their own chosen variable names, types, and default values. These variable declarations are used to store values for use throughout the query, and will also be used to generate a query template. For example, imagine there is a table of facts about countries and a user would like to filter down to a specific country. The Query Creator could format their query as follows:
Running this query will use the value “US” as the country name and filter the results appropriately.
Upon constructing a DECLARE statement, the Query Creator will notice a link that reads “Preview query template” replace the “Create query template” link above the query editor.
Clicking on “Preview query template” will generate a query template reflecting the given DECLARE statements and their default values and display it inside the query editor.
The Query Creator is now only able to interact with the query via this template, and cannot edit the query directly from this view. Filling in alternate values as parameters in the text box will not modify the underlying query. It will simply replace the variable in the query with the given input, allowing the Query Creator to look at different slices of the data in a more user-friendly manner.
The Query Creator can include comments immediately alongside, above, or beneath their DECLARE statements and they will be parsed and rendered inline with the template. For example:
will render as:
Comments can be useful for helping the Query Reader better understand how they can effectively work with the template to understand the data.
To navigate back to the query editor view from the query template view, the Query Creator can click on the “Edit query” link above the query template.
This link will then be back to reading as “Preview query template.” Removing all DECLARE statements from the editor will result in “Create query template” being shown again here.
… and continues with the business user, or Query Reader
The work put in by the Query Creator to build the parameterized query is truly leveraged when they share the query with another user, the Query Reader. When the Query Reader opens the query in the workspace, they will be presented with a view of the query template and an uneditable query editor. They can either enter new values in the template, or run the query with the default values. Again, doing this will not alter the actual query content. If they would like to alter the query content themselves, they must save a copy of the query to do so.
Queries that are executed with a new parameter value may be shared with others by simply copying the URL and sending it to another user. If parameters have been filled in, then these parameters will be encoded into the URL for sharing.
In addition to the affordances included in the workspace user interface, users can also make use of parameterized queries using the public API. There is a new endpoint which has been introduced which allows for parameters to be passed through a POST request.
curl -X POST \
Example curl command
See our API docs for more information.