constants

Constants are string values that can be defined once in a model file and referenced throughout your model using @{constant_name} syntax. Constants are resolved before other template processing (Mustache and field references) when a query executes or a link renders, making them ideal for values that need to be centrally managed and consistently applied across your model. For example:

Database schema names that may differ between environments
Common URL patterns for data links
Repeated string values that you want to maintain in a single location
Configuration values that can be dynamically referenced
Reusable AI context blocks that can be referenced in ai_context fields

Constants are also inherited by shared extension models.

Syntax

constants:
  <constant_name>:
    value: <string_value>

Properties

constants

object

A map of constant definitions where each key is the constant name. Names must be unique within the model.

Hide constant_name properties

value

string

required

The string value for the constant. Can contain fully-scoped field references using ${} syntax, which will be resolved when the constant is used during query execution or link rendering. For example, ${users.country}

Examples

Dynamic schema reference

Use constants to reference schema names that may vary across environments. Define the constants in the model file:

Model file

constants:
  base_schema:
    value: analytics_prod
  staging_schema:
    value: analytics_staging

And then reference the constants, such as in the following view file:

View file

sql: |
  SELECT *
  FROM @{base_schema}.users

Dynamic links with field references

Create link patterns that include field references. Define the constants in the model file:

Model file

constants:
  google_search:
    value: "https://www.google.com/search?q=${users.country}"
  user_profile:
    value: "https://example.com/profile/${users.user_id}"

And then reference the constants in fields, such as the following dimensions:

Dimensions in a view

dimensions:
  country:
    sql: country
    link: "@{google_search}"
  user_id:
    sql: user_id
    link: "@{user_profile}"

Reusable format patterns

Constants are often used with the format parameter on dimensions and measures. Reference a constant with @{constant_name} inside the format string (including inside conditional format branches).

For standard currency and number display, use a named format like usdcurrency_2 or percent_1 directly. Constants are most valuable for custom Excel-style patterns that appear in several fields.

Model file

constants:
  compact_time:
    value: 'm:ss "min"'
  margin_display:
    value: '#,##0.00 "bps"'

View file

measures:
  avg_duration:
    sql: '"duration_secs"'
    aggregate_type: avg
    format: "@{compact_time}"
  margin:
    sql: '"margin_bps"'
    aggregate_type: avg
    format: "@{margin_display}"

See Model constants in format strings on the formatting page for more detail.

Reusable AI context

Constants can be referenced in ai_context fields at the model, topic, view, and sample query levels. This allows you to maintain shared instruction blocks in a single location instead of duplicating them across multiple ai_context fields.

Model file

constants:
  tone:
    value: "Keep responses concise and professional."
  privacy_high:
    value: "Never show individual customer names or emails without explicit permission."
  domain_finance:
    value: "This is a financial analytics model. Focus on accuracy and precision when handling monetary values."

Topic file

ai_context: |
  @{tone} @{privacy_high}
  @{domain_finance}
  This topic covers invoices. One row is an invoice.

Unknown constant references (e.g., @{undefined_constant}) render as-is rather than failing. Model validation will display warnings when an ai_context field contains unknown constant references.

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Syntax

Properties

Examples

Dynamic schema reference

Dynamic links with field references

Reusable format patterns

Reusable AI context

​Syntax

​Properties

​Examples

​Dynamic schema reference

​Dynamic links with field references

​Reusable format patterns

​Reusable AI context

Syntax

Properties

Examples

Dynamic schema reference

Dynamic links with field references

Reusable format patterns

Reusable AI context