Optimize models for Omni AI

Requirements

To follow this guide, you’ll need:

An understanding of Omni modeling concepts
Familiarity with Omni’s model IDE
Familiarity with basic AI terminology such as tokens, agents, etc.

Common questions

What is AI context?

Context is information such as:

Descriptions of topics and fields
Possible field values
How a field might be used

In Omni, this is provided to the AI using a context window. A context window is the amount of text an AI can read and consider at one time when answering a question or completing a task.

Why provide context to AI?

Using context windows allows AI models to understand and incorporate relevant information. Specifically, providing context to the LLM makes it more effective, enabling it to interpret your request accurately and generate meaningful responses.

What does Omni AI use for context?

Omni uses the following for context, in priority order:

Context and tuning pre-built by the Omni Engineering team

The ai_context parameters in the model, topics and views, if provided

Topic's description, if provided

Topic's name and base_view

Prioritized field properties

These properties are never removed from the context window, even when space runs out:

name - The field’s fully qualified name (view_name.field_name). For example, order_items.total_sale_price
ai_context - Context you write for the AI. When Omni assembles context for a specific topic, ai_context is never pruned, whether it’s defined on the model, topic, view, or field. The exception is when the AI is choosing a topic; see What limitations does context have?

Pruned field properties

If a topic’s metadata exceeds the space Omni allots for it (see What limitations does context have?), Omni prunes the following properties, starting with the lowest priority. Each property is removed from every field before the next is considered:

all_values - The field’s possible values. Pruned first because the AI can retrieve a field’s values on demand when it needs them.
sql - The field’s SQL definition, when included
sample_values - Example values for the field
description
group_label - The categorization of the field
label - The field’s display name. If not defined, Omni generates one by title-casing the field name and removing underscores. For example, Total Sale Price
aggregate_type - A measure’s aggregation type, such as sum, count, etc. This value is evaluated based on the field definition and can’t be directly modified.
data_type - The field’s data type, such as number, string, etc. To save space, this property is automatically omitted when the type can be inferred, such as for string fields.
synonyms - Other terms used to refer to the field. Pruned last because synonyms help the AI match the language in a user’s question to the right field.

If removing all of these properties still isn’t enough, Omni may exclude entire views from the results the Omni Agent sees when it searches the model. If the remaining context still exceeds what the AI model can accept (for example, because a topic carries a large amount of ai_context, which Omni never trims), the request fails with an error.

Where does context apply?

Context applies to:

Omni Agent and embedded chat instances, including topic selection and model search
Workbook Agent, including query and SQL generation
Dashboard Agent summaries
AI visualization generation and summary visualizations
AI filter generation
Modeling Agent and modeling workflows, such as topic metadata generation and learn-from-conversation

What limitations does context have?

The AI model’s context window is shared by everything in a request, including:

Omni’s built-in instructions, which ensure queries are generated properly
Context from your semantic model, such as topic and field metadata, ai_context, and sample queries
The conversation history and query results

To keep requests fast and leave room for the rest of the conversation, Omni caps how much of the window your model’s metadata can use. These caps - not the full context window - are what determine when pruning begins:

A topic’s field definitions are capped at roughly 75K characters. When a topic’s metadata exceeds the cap, Omni prunes field properties in the order described in What does Omni AI use for context?.
When choosing a topic, the AI reads a summary of every topic, capped at roughly 100K characters. If the summary exceeds the cap, Omni trims view metadata (including view-level ai_context), then sample queries, and trims topic metadata only as a last resort. The AI recovers trimmed details when it selects a specific topic.
Searches outside of a topic return up to 100 fields. When query_all_views_and_fields is enabled, the AI finds fields for views that aren’t in a topic by searching the model. Instead of pruning properties, each search returns at most 100 fields and the AI runs narrower searches to find the rest.

How many fields fit under the cap varies widely with how much metadata each field carries: a lightly annotated field uses around 100 characters, while a field with a rich description, sample values, and ai_context can use several times that. Instead of targeting a field count, use the workbook inspector to see the context the AI actually received, and curate with ai_fields to focus each topic on the fields users actually ask about. A smaller, well-described set of fields gives the AI fewer chances to pick the wrong one.Conversation history is managed separately - refer to the conversation_prune_length reference for more information.

How is context to the AI processed?

Context provided to Omni’s AI is shared with AWS Bedrock. Refer to the AI data security guide for more information.

Context and agent behavior

As the previous section explained, Omni assembles ai_context from multiple levels — model, topic, view, and field — and passes it to the Omni Agent as part of the query generation prompt. The LLM that powers the Omni Agent makes its own decisions about which context to follow, how to weight it, and how to resolve apparent contradictions. This means:

Model-level ai_context is not guaranteed to override topic-level ai_context. All context is passed together; the LLM decides what to prioritize.
Context is guidance, not strict instruction. The LLM may partially follow, fully follow, or in some cases not follow a given instruction, especially when instructions are complex or contradictory.
Behavior can be non-deterministic. Running the same query twice may result in different context being applied, particularly when context is large or contains conflicting signals.

Use the workbook inspector to view and debug the context for a given AI session.

Curate AI outputs across the model

You can use the model parameter ai_context to pass context shared across topics. This parameter may also be useful for topic selection in the Omni Agent.

Personalize context with user attributes

The ai_context parameter at the model, topic, and view levels supports user attributes through {{omni_attributes.<attribute_name>}} syntax. At query time, Omni substitutes each placeholder with the current user’s attribute value, allowing you to tailor AI behavior per user or group.

Topic ai_context using user attributes

ai_context: |
  You are a sales analyst. When someone asks about their team or pipeline, always filter by account.segment = {{omni_attributes.segment}} and account.region = {{omni_attributes.region}}.

User attribute references are supported in ai_context at the model, topic, and view levels only. Dimension and measure ai_context does not support this syntax — the value is used as-is. Field references and filter conditions are also not supported and will produce a validation warning.

Optimize context for different AI models

The ai_context parameter at the model, topic, and view levels supports model-specific customization through the omni_llm namespace. This ensures optimal performance across AI model options by allowing you to tailor AI instructions to the capabilities of different AI model tiers:

smartest - Most capable models suited for complex reasoning
standard - Balanced models for typical queries
fastest - Optimized for speed and simple requests

For example, you can provide different chain-of-thought instructions based on model tier. In the following example, the first block ({{# omni_llm.smartest }}) would apply when the model tier is smartest, and the second ({{^ omni_llm.smartest }}) would apply when the model tier is standard or fastest:

Model-level ai_context with omni_llm

ai_context: |
  {{# omni_llm.smartest }}
  Before calling 'GenerateQuery', explain your reasoning for field selection in detail (9-10 sentences) under "Reasoning for field selection", then provide 3-4 sentences on alternative approaches under "Alternative approaches considered".
  {{/ omni_llm.smartest }}

  {{^ omni_llm.smartest }}
  Proceed directly to generating the query without intermediate explanation steps.
  {{/ omni_llm.smartest }}

You can also adjust analysis depth based on model capabilities:

Topic-level ai_context with omni_llm

ai_context: |
  This topic focuses on financial transactions.

  {{# omni_llm.smartest }}
  For complex multi-table queries, consider indirect relationships and provide rationale for join path selection.
  {{/ omni_llm.smartest }}

  {{# omni_llm.standard }}
  Use straightforward joins between related tables.
  {{/ omni_llm.standard }}

  {{# omni_llm.fastest }}
  Prefer single-table queries when possible.
  {{/ omni_llm.fastest }}

See the ai_context references for models, topics, and views for more information and examples.

Optimize context for different AI agents

The ai_context parameter at the model, topic, and view levels also supports agent-specific customization through the omni_agent namespace. This lets you scope portions of your context to the AI agent that will read it, preventing bulky agent-specific content from inflating context windows for other agents. The three agent types correspond to existing AI settings configuration categories:

analyze - Used for search-model tool and query generation
build - Used for topic metadata generation and learn-from-conversation
simple_summarize - Used for tile/visualization summaries and query metadata

For example, you might want to provide detailed modeling conventions to the build agent while keeping the analyze agent’s context concise:

Model-level ai_context with omni_agent

ai_context: |
  {{# omni_agent.build }}
  Modeling conventions: Always define primary keys. Use snake_case for field names. Prefer measures over dimensions for aggregations.
  {{/ omni_agent.build }}

  {{^ omni_agent.build }}
  Keep queries focused and efficient.
  {{/ omni_agent.build }}

  This context is read by the {{ omni_agent.name }} agent.

You can also provide agent-specific query optimization tips at the topic level:

Topic-level ai_context with omni_agent

ai_context: |
  This topic focuses on user activity data.

  {{# omni_agent.analyze }}
  For performance, prefer filtering by date ranges before joining to user details.
  {{/ omni_agent.analyze }}

  {{# omni_agent.build }}
  When generating field relationships, consider that user_id is the primary key linking activity to users.
  {{/ omni_agent.build }}

See the ai_context references for models, topics, and views for more information and examples.

Use constants for reusable AI context

You can define reusable AI instruction blocks as constants and reference them across multiple ai_context fields using @{constant_name} syntax. This approach helps you maintain shared context (tone, privacy guidance, domain context) in a single location instead of duplicating it across models, topics, views, and sample queries.

Model file with reusable AI context constants

constants:
  tone:
    value: "Keep responses concise and professional."
  privacy_high:
    value: "Never show individual customer names or emails."
  domain_finance:
    value: "This is a financial analytics model. Use monetary values with precision."

ai_context: |
  @{tone} @{privacy_high}
  @{domain_finance}

You can then reference these same constants in topic-level, view-level, and sample query ai_context fields, ensuring consistent instruction blocks across your model while keeping maintenance centralized. See the constants reference for more details and examples.

Implement chain-of-thought reasoning

If you want the Omni Agent to give a more thorough explanation of what is being generated (topic selection, field selection, etc.), you can include the following context within the model’s ai_context. This can be altered and tweaked if needed, but the reference to GenerateQuery is required for proper behavior.

ai_context: |
  Before calling the 'GenerateQuery' tool, please do the following steps:
  
  1. Explain your reasoning of how you picked the fields in detail (9-10 sentences), under the header "Reasoning for field selection"
  2. Another 3-4 sentences on alternative queries or fields you could have chosen under the header "Alternative approaches considered"
  3. Finally add 4 markdown links as follow up questions under the header "Follow-up questions"

If you don’t want to implement chain-of-thought reasoning for all model tiers, you can provide model tier-specific instructions instead.

Output summaries in multiple languages

If you’d like the Omni Agent to summarize outputs in multiple languages, you can include the following context:

ai_context: |
  When generating a summary, always output the summary in both English and Spanish.

Curate topics

Topics have an ai_context parameter, which is useful for providing behavioral prompts and guidance for handling certain questions specific to the topic. For example:

ai_context for e-commerce orders topic

ai_context: |-
  This topic focuses on e-commerce orders. The main concepts are orders
  at the line item level in the order items table, users in our user table,
  inventory in our inventory items table, and products in the products table.

  Only respond with accurate answers based on the data that you're aware of.
  Don't pivot unless there is more than one dimension included in the query.

  Typical questions will be focused on order performance over time, breakdowns across users, and more. 
  - if asked about sales or performance, always use the order_items.total_sale_price field
  - if asked about which users or who, use the users.full_name and users.email fields. Never return an ID unless explicitly asked.
  - if asked about top n without a specific metric or dimension, assume it involves the order_items.total_sale_price and products.name fields

You can use the ai_chat_topics model parameter to curate the list of topics that the Omni Agent or embedded chat instances have access to.

Limit fields included in the context window

When querying within a topic, the AI uses only that topic’s fields. When querying outside of a topic, it can use fields from any view in the model. Fields with hidden: true are excluded from the context window. To control which fields are included, use the ai_fields parameter in a topic. For included fields, you can also provide additional context at the field level. We recommend periodically checking the Analytics > AI usage dashboard to see what questions your users are asking. This helps you identify opportunities to promote commonly used calculations and aggregations to the shared model, improving the self-serve experience over time.

Reuse logic and limit the context window with topic extensions

Topics that you’re already leveraging in Omni can be extended to further curate them for AI. Using the extends parameter, you can reuse the definition of an existing topic without needing to repeat the code. Consider the following Order Transactions topic, which you want to extend to create a curated version dedicated to AI usage:

Order Transactions topic

label: Order Transactions

default_filters:
  order_items.status:
    not: [ Returned, Cancelled ]

joins:
  users: {}
  user_order_facts: {}
  inventory_items:
    products:
      distribution_centers: {}

In a new topic, use extends: [ order_items ] to extend the Order Transactions topic. You can then specify what to include in the AI-specific topic, such as limiting fields, filtering the data for specific use cases, adding more AI context, and so on:

Orders for AI querying topic, extended from Order Transactions

extends: [ order_items ]

base_view_label: Order Items
label: Orders for AI Querying

# limit fields included in the context window
ai_fields: [ tag:use_for_ai ]

Add example queries as context

Along with providing context about the topic itself, you can use the topic’s sample_queries to provide example questions. This approach is useful if you anticipate specific, recurring questions or you find that the Omni Agent struggles with date filters. To do this, you’ll want to:

Create a query in a workbook that contains the correct answer to the question.
In the workbook, click Model > Save as sample query to topic.
When prompted, fill in the following:
- Label - A user-friendly name for the query
- Description - An optional description
- Display on topic overview - If checked, the query will display as a sample query when the topic is selected in a new query tab
- Include in AI context - If checked, the query will be included in the AI context for the topic
  - Prompt - An optional example prompt that could be used to generate this query
  - AI context - Optional, additional context for the AI
When finished, click Save.

You can also use the model-level sample_queries parameter to define example queries that could be performed using the topics contained in the model.

Curate views and fields

Views also have an ai_context parameter which can be useful for passing context to AI that is specific to the view. Keeping fields organized and labeled can not only help you create a top-notch self-service experience, it can also make Omni’s AI more efficient. The following parameters can be used to add metadata to fields for the purposes of AI:

ai_context - Adds context useful for AI responses
all_values - All possible values for the field
- Note: when the dbt integration is enabled, accepted_values tests will be ingested as all_values
sample_values - Example values for the field
synonyms - Other terms used to refer to the field

You can use the workbook or the IDE to add the parameters.

In the workbook

In the field browser, click the (three dots icon) next to the field.
Click Modeling > Edit to open the Edit field side panel.

In the IDE

In the IDE, navigate to the view containing the field to add the parameters. For example:

products.view

dimensions:
  brand:
    sql: '"BRAND"'
    description: Brand name of product
    sample_values:
      [
        Calvin Klein,
        Carhartt,
        Hanes,
        Volcom,
        Levi's,
        Diesel,
        Lucky Brand,
        Quicksilver,
        Nautica,
        American Apparel,
        Columbia,
        Hurley,
        Dockers,
        Arc'teryx,
        C-IN2,
        DKNY,
        HOBO,
        NOM,
        ANS
      ]
    synonyms: [ logo ]
    ai_context: To filter this field, use contains with the brand name.

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Optimize models for Omni AI

Requirements

Common questions

Context and agent behavior

Curate AI outputs across the model

Personalize context with user attributes

Optimize context for different AI models

Optimize context for different AI agents

Use constants for reusable AI context

Implement chain-of-thought reasoning

Output summaries in multiple languages

Curate topics

Limit fields included in the context window

Reuse logic and limit the context window with topic extensions

Add example queries as context

Curate views and fields

​Requirements

​Common questions

​Context and agent behavior

​Curate AI outputs across the model

​Personalize context with user attributes

​Optimize context for different AI models

​Optimize context for different AI agents

​Use constants for reusable AI context

​Implement chain-of-thought reasoning

​Output summaries in multiple languages

​Curate topics

​Limit fields included in the context window

​Reuse logic and limit the context window with topic extensions

​Add example queries as context

​Curate views and fields

Requirements

Common questions

Context and agent behavior

Curate AI outputs across the model

Personalize context with user attributes

Optimize context for different AI models

Optimize context for different AI agents

Use constants for reusable AI context

Implement chain-of-thought reasoning

Output summaries in multiple languages

Curate topics

Limit fields included in the context window

Reuse logic and limit the context window with topic extensions

Add example queries as context

Curate views and fields