Skip to main content
Definitions are saved SQL queries attached to a data source. Use them to define important metrics, models, and reusable logic once, then reference them from charts, dashboards, chat, insights, automations, and other queries in Basedash. Each definition has a name, reference name, description, and SQL query. Basedash expands the definition inline when a query runs, and the AI can see available definitions so it can use the same calculations your team has already approved.

​
When to use definitions

Use definitions for SQL that should stay consistent across your workspace:
  • Business metrics: Monthly recurring revenue, activation rate, churn, retention, pipeline coverage
  • Reusable models: Cleaned accounts, eligible users, active subscriptions, qualified pipeline
  • Shared filters: Exclude test accounts, internal domains, trials, deleted records, or sandbox data
  • Complex joins: Package multi-table logic that many charts or agents need to reuse
Definitions are more deterministic than prose-only AI guidance because they contain the exact SQL Basedash should run. They work well alongside AI context: use AI context or skills to explain business meaning, and use definitions when the calculation itself should be reusable SQL.

​
Where to find definitions

  1. Go to the Data page.
  2. Select a data source.
  3. Open the Definitions section above the table list.
  4. Click Create definition to start a new definition.
Definitions are scoped to the selected data source. A definition can only be referenced by queries that run against the same data source.

​
Create a definition

When you create or edit a definition, add:
  • Name: A human-readable label, such as “Monthly recurring revenue”
  • Reference name: A SQL-safe name, such as mrr
  • Description: A short explanation of what the definition represents
  • SQL query: The read-only SQL Basedash should expand wherever the definition is referenced
Reference names must be unique within the data source and use lowercase letters, numbers, and underscores.

​
Use definitions in SQL

Reference a definition with Liquid syntax: 
WITH mrr AS (
  {{ definition("mrr") }}
)

SELECT month, SUM(amount) AS total_mrr
FROM mrr
GROUP BY month
ORDER BY month;
We recommend referencing definitions inside CTEs. This keeps the final query readable and makes it clear where each reusable piece of logic enters the query. Definitions can reference other definitions on the same data source: 
WITH active_customers AS (
  {{ definition("active_customers") }}
),
mrr AS (
  {{ definition("mrr") }}
)

SELECT active_customers.segment, SUM(mrr.amount) AS total_mrr
FROM active_customers
JOIN mrr ON active_customers.customer_id = mrr.customer_id
GROUP BY active_customers.segment;

​
AI and definitions

Basedash gives AI agents a catalog of available definitions for the data sources they are using. The AI can:
  • Reference definitions when writing SQL for charts, dashboards, chat, insights, and automations
  • Inspect a definition’s SQL before using or editing it
  • Create new definitions when you ask for a reusable metric, model, or SQL definition
  • Update existing definitions when you ask to change the underlying logic
For example, you can ask chat: 
Create a definition for activation rate using users who completed onboarding within 7 days.
After the definition exists, future questions like “show activation rate by signup month” can reuse the same SQL instead of recalculating the metric from scratch.

​
Version history

Every SQL or description change creates a new definition version. Open Query history from a definition to review earlier versions and restore a previous one. Version history is useful when a metric changes, a query needs to be audited, or you want to understand why a dashboard’s calculation changed over time.

​
Permissions

Organization admins can create, edit, delete, and restore definitions. Members with data source access can view and run definitions, but cannot change them. Deleting a definition can break charts, dashboards, or queries that reference it. Before deleting a definition, check where it is used and update dependent queries.

​
Best practices

  • Keep each definition focused on one metric, model, or reusable concept.
  • Write stable reference names because queries use them directly.
  • Add descriptions that explain the business meaning, not just the SQL mechanics.
  • Use CTEs when referencing definitions from larger queries.
  • Prefer definitions for deterministic calculations and AI context or skills for prose guidance.
  • Avoid cross-source assumptions: definitions only work within their own data source.