Skip to main content

​
Parameters

Published pipes support Jinja2 syntax for parameter templating. Parameters help you write dynamic queries and provide more control over the results your queries return. In dashboards, you can prompt users for filter values and use those filters to query the data, returning only the relevant results. Example of a parameterized endpoint:
parameter three dots

​
Data Types

Airfold allows the following data types for the value of the parameters. Supported data types:
  • String
  • Int
  • Float
  • Boolean
  • Date
  • Datetime
To use the parameters in you SQL, just add the parameter name inside two curly braces like this {{ params }} Example: SELECT * FROM t LIMIT {{ limit }} The internal Jinja engine handles parameter substitution automatically. No need to escape parameters - WHERE name = {{ name }} works correctly for string values.

​
Endpoint calls

All parameters are passed as query strings in the HTTP API. 
https://api.us.airfold.co/v1/pipes/endpoint1?param1=10&param2=foo&param3=c1,c2
For additional syntax options, refer to the Jinja2 documentation.

​
More Examples

{% if param is defined %}
	SELECT {{ param }}
{% else %}
	SELECT 1
{% endif %}
For additional statement options, refer to the Jinja2 documentation.

​
UI

​
Create the Draft Pipe

Follow normal steps you would follow to create a draft pipe (refer Draft Pipes), make sure the query has the parameters enclosed in two curly braces like this: {{ params }}
draft pipe

​
Add parameters

Go to the three dots on top right corner and select “Add Parameter” and then select the Parameter Name, Data Type and and Default value.
params creation
params page

​
Run the query

Once all the parameters are defined, you can just run the command and the query runs with the default values.
params assign
 You can set the values for parameters just by assigning the value to the params.

​
CLI

​
Edit YAML file

Once the query is ready simply add {{ params }} where required and set the publish property
top_referrers.yaml
nodes:
  - node1:
      sql: |
        SELECT
          referrer,
          COUNT() AS num_referrers
        FROM web_events
        WHERE timestamp BETWEEN {{ start_date }} AND {{ end_date }}
        GROUP BY referrer
        ORDER BY num_referrers DESC
        LIMIT 3
publish: top_referrers

​
Add Params

To define the parameters in the SQL query, we need to add the params property and define parameter name, type and default value.
top_referrers_with_parameters.yaml
nodes:
  - node1:
      sql: |
        SELECT
          referrer,
          COUNT() AS num_referrers
        FROM web_events
        WHERE timestamp BETWEEN {{ start_date }} AND {{ end_date }}
        GROUP BY referrer
        ORDER BY num_referrers DESC
        LIMIT 3
publish: top_referrers
params:
  - name: start_date
    type: string
    default: 2025-01-01
  - name: end_date
    type: string
    default: 2025-12-31

​
Push

Once the config file is ready, you can use the push command to push the changes to your workspace. Push this update by running: 
af push top_referrers.yaml
Params can be used in endpoints and draft pipes. Params cannot be used in materialized pipes.