Skip to main content

Custom Variables

Custom variables let you create flexible, reusable queries that you can adjust on the fly without rewriting the question every time. Think of them as fill-in-the-blank placeholders. You set up the query once, and then just change the values whenever you need to.

What Are Custom Variables?​

A custom variable is a placeholder in a saved query that you can change each time you run it. Instead of asking the same question over and over with small tweaks ("Show me sales for January," "Show me sales for February," "Show me sales for March..."), you create one query with a variable for the month and swap it out whenever you like.

When to Use Variables​

Custom variables are especially useful when you:

  • Run the same query regularly with different date ranges (weekly check-ins, monthly reports)
  • Share queries with your team and everyone needs to customize the filters for their own use
  • Create DataClips that need to stay flexible over time
  • Filter by different values depending on the situation (different regions, statuses, product lines)

How to Create and Use Variables​

Setting up a custom variable is straightforward:

  1. Write your query as you normally would in Teela
  2. Save it as a DataClip (this is where variables really shine)
  3. Define your variables by marking parts of the query as customizable
  4. Set default values so the query works right away, even before anyone changes anything
  5. Run it: you'll be prompted to fill in your variable values each time

When you or a teammate opens the DataClip, the variable fields appear as simple inputs. Just type in the value you want and run the query.

Common Variable Patterns​

Here are some of the most popular ways people use custom variables:

Date Ranges​

Perfect for reports you run on different time windows:

  • Start date / End date: "Show me all orders between {start_date} and {end_date}"
  • Month or quarter: "What was revenue for {time_period}?"
  • Year comparison: "Compare performance in {year_1} vs {year_2}"

Status Filters​

Great when you need to check on different segments:

  • "Show me all tickets where status is {status}"
  • "List customers in the {tier} plan"

Region or Team Selectors​

Helpful for queries that different team members use for their own area:

  • "What are the top products in {region}?"
  • "Show me the pipeline for {sales_team}"

Entity Selectors​

When you want to look up information about a specific item:

  • "Show me the order history for customer {customer_name}"
  • "What's the status of project {project_id}?"

Using Variables in DataClips​

Custom variables and DataClips are a natural pair. When you save a query with variables as a DataClip, anyone on your team can open it, fill in their own values, and get a personalized result. They don't even need to understand how the query works.

This is especially powerful for:

  • Team dashboards where each person filters to their own region or territory
  • Weekly reports where only the date range changes
  • Lookup tools where you type in a customer name or order number to pull up details

Tips for Naming Variables​

Good variable names make your queries easy for everyone to use. Here are some guidelines:

  • Be descriptive. Use start_date instead of d1. Use region instead of r.
  • Use plain language. Someone who didn't create the query should be able to understand what to fill in.
  • Be consistent. If you use start_date and end_date in one query, use the same names in others.
  • Keep it short but clear. customer_name is better than the_name_of_the_customer_you_want_to_look_up.

Next Steps​

  • DataClips: Learn more about saving and sharing your queries
  • Querying: Master the basics of asking questions in Teela