# AI Hub
Source: https://docs.omni.co/administration/ai-hub

Monitor how your organization uses Omni AI — adoption, answer quality, and credit usage — from a single admin space.

The AI Hub is an admin space for managing and monitoring how your organization uses Omni's AI. It brings your AI settings together with adoption, answer quality, and credit usage in one place. From here you can configure AI features and see what people are asking, whether the AI is answering well, and where activity is concentrated.

## Requirements

* **Organization Admin** permissions are required to access the AI Hub
* Your organization must have Omni AI enabled.

## Accessing the AI Hub

Select **AI Hub** in the [sidebar](/administration/settings/sidebar) of your Omni instance.

## Configure AI settings

Omni's AI features are enabled by default. Use these settings to selectively enable or disable features, customize the AI chat interface, or connect a different model provider.

<CardGroup>
  <Card title="Features" icon="sliders" href="/ai/settings/features">
    Enable or disable individual AI features.
  </Card>

  <Card title="MCP" icon="database" href="/ai/settings/mcp">
    Enable or disable individual [MCP Server](/ai/mcp) settings.
  </Card>

  <Card title="Branding" icon="palette" href="/ai/settings/branding">
    Customize the appearance of the AI chat interface.
  </Card>

  <Card title="Model providers" icon="microchip" href="/ai/settings/model-providers">
    Configure an alternative AI model provider.
  </Card>
</CardGroup>

## Dashboards

The dashboards in the AI Hub allow you to see how your users are using AI. Use the model selector dropdown in the sidebar to filter the dashboards to a specific shared model.

To be included in the dashboards, a model must have at least 50 AI prompts across at least 5 sessions in the last 30 days.

Data refreshes once per day. This means that the current day's activity will be available on the following day.

| Dashboard                                                | What it shows                                                                                                                                                                                |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**                                             | Start here to gauge overall adoption and health at a glance.                                                                                                                                 |
| **Quality**                                              | How well the AI is answering questions: analysis of user feedback. Read the questions users asked and spot where the AI struggles or where your model needs more context.                    |
| **Usage**                                                | Activity broken down by user and surface, so you can see who is using AI the most and where activity is concentrated. Useful for understanding adoption and attributing usage.               |
| [**Credit tracking**](/ai/settings/usage#detailed-usage) | How AI credits are being consumed across your organization, broken down by feature and user. This reflects activity across all models; using the model selector will not change the results. |

## Improve answer quality

Once you've reviewed the Quality dashboard, use these tools to act on what you've learned.

<CardGroup>
  <Card title="Suggestions" icon="wand-magic-sparkles" href="/ai/suggestions">
    Apply prioritized recommendations to improve your model's AI context, based on user feedback.
  </Card>

  <Card title="Evals" icon="clipboard-check" href="/ai/evals">
    Run prompt sets through your model to score AI accuracy and catch regressions before they reach users.
  </Card>
</CardGroup>

## Next steps

* [AI credit tracking](/ai/settings/usage) — Monitor AI credit usage across your organization
* [Optimize your models for AI](/modeling/develop/ai-optimization) — Improve answer quality by adding context to your model
* [AI data privacy](/ai/security) — Learn how Omni's AI features process data


# Usage analytics
Source: https://docs.omni.co/administration/analytics

Gain insight into how Omni is being used in your organization.

The **Analytics** dashboard, accessed by clicking the **Analytics** option in the [sidebar](/administration/settings/sidebar) of your Omni organization, is an embedded instance of Omni, in Omni. Along with giving admins information about how their users are using Omni, this section of the app also contains product updates and details about experimental and beta features.

## Requirements

**Organization Admin** permissions are required to access the Analytics dashboard and use production topics in analyses.

## Pre-built dashboards

Analytics comes with several ready-to-use dashboards, built on curated production topics modeled from system activity. These dashboards are continuously updated as new data becomes available.

| **Dashboard**                             | **Description**                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Overview**                              | High-level summary of user activity                                                                 |
| **Users**                                 | User logins, frequency of activity, and engagement across Omni.                                     |
| **Content**                               | Workbook and dashboard usage                                                                        |
| **Model**                                 | Model-level performance metrics such as query execution times, join complexity, and usage frequency |
| **Schedules**                             | Scheduled deliveries, success/failure rates, and destination types.                                 |
| **AI**                                    | Logs of AI interactions, including prompts, responses, and linked sessions                          |
| **[Credit Tracking](/ai/settings/usage)** | AI token consumption across features, users, and groups                                             |
| **Changelog**                             | Weekly updates of Omni releases, including new features and fixes                                   |
| **Features**                              | Available experimental and beta features, including whether they're enabled in your instance        |

## Data freshness

The data in the Analytics dashboard and the underlying production topics may be on a slight delay, compared to live usage.

## Building your own analyses

Beyond the pre-built dashboards, Organization Admins can explore or build their own analyses using the same production topics the Analytics dashboard is built on.

The content built from these topics will remain separate from the other content in your instance unless you choose to share it.

### Sharing and deliveries

<Note>
  URL sharing is not currently supported in Analytics.
</Note>

While you can share and schedule content built from production topics, there are a few things to keep in mind:

* **Content can be directly shared only with other Admin users**. Non-admin users can't log in to the Analytics workspace, so they won't be able to view the content.
* **Deliveries and alerts are supported for content built on production topics**. When creating an Analytics-based delivery, note that:
  * You can add email-only recipients
  * Other Admin users must open the Analytics dashboard at least once to appear as a selectable recipient
  * Slack destinations are not supported


# Using Amazon S3 for Omni audit logs
Source: https://docs.omni.co/administration/audit-logs/amazon-s3

Track Omni user activity in your instance with structured logs, accessible in an Amazon S3 bucket.

<Note>
  Reach out to Omni support to have audit logs enabled for your instance.
</Note>

Audit logs are detailed records of the activity your users are taking in Omni, which can be useful for security and performance analysis. Events included in logs are structured as JSON payloads and sent in batches to an Omni-owned cloud storage bucket a few minutes after they're written.

## Requirements

To follow the steps in this guide, you'll need:

* To have audit logs enabled in your Omni instance
* Permissions in AWS that allow you to manage IAM roles

## Setup

After audit logs are enabled in your instance, complete the following:

<Steps>
  <Step title="Provide Omni support with your AWS IAM role">
    Reach out to Omni support with the name of the AWS IAM role you want to use.
  </Step>

  <Step title="Complete setup with Omni support">
    Omni support completes the configuration on the Omni side.
  </Step>
</Steps>

## Next steps

* Learn about the [event types](/administration/audit-logs/event-types) supported for audit logs
* Check out your instance's [Analytics section](/administration/analytics)


# Using Azure Blob Storage for Omni audit logs
Source: https://docs.omni.co/administration/audit-logs/azure-blob-storage

Track Omni user activity in your instance with structured logs, accessible in an Azure Blob Storage container via a Microsoft Entra application or a SAS token.

<Note>
  Reach out to Omni support to have audit logs enabled for your instance.
</Note>

Audit logs are detailed records of the activity your users are taking in Omni, which can be useful for security and performance analysis. Events included in logs are structured as JSON payloads and sent in batches to your cloud storage a few minutes after they're written.

For Azure, Omni hosts the storage: Omni creates a dedicated storage account and blob container for your instance. You can read your logs using either of two access methods:

|                       | **Microsoft Entra application** (recommended)                         | **SAS token**                              |
| --------------------- | --------------------------------------------------------------------- | ------------------------------------------ |
| Credentials exchanged | None — you authenticate with your own application's credential        | Omni shares a read-only SAS token with you |
| Best for              | Custom tooling, Azure SDKs, anything that can authenticate with Entra | Tools that only support SAS authentication |

## Option 1: Microsoft Entra application (recommended)

Omni grants a Microsoft Entra application that you own read access to your container. You read your logs by authenticating with your own application's credential — there are no storage account keys or SAS tokens to manage, and no credentials are exchanged between you and Omni.

### Requirements

To follow the steps in this guide, you'll need:

* To have audit logs enabled in your Omni instance
* A **multitenant** Microsoft Entra application registered in your tenant, with a client secret or certificate
* Permissions to register an application in your tenant and read its application (client) ID

### Setup

After audit logs are enabled in your instance, complete the following:

<Steps>
  <Step title="Register a multitenant Entra application">
    In the [Microsoft Entra admin center](https://entra.microsoft.com), navigate to **App registrations > New registration**.

    * Set **Supported account types** to **Accounts in any organizational directory (multitenant)**. This is required so Omni can create a service principal for your application in Omni's tenant and grant it access.
    * Under **Certificates & secrets**, add a client secret or certificate. This credential stays in your tenant and is never shared with Omni.
    * Copy the **Application (client) ID**.

    No API permissions are required — you can ignore (or remove) the default `User.Read` permission.
  </Step>

  <Step title="Provide Omni support with your application details">
    Reach out to Omni support with the following:

    * **Application (client) ID** — the UUID of your multitenant application
    * **Tenant ID** — your Entra tenant ID (the application's home tenant)
  </Step>

  <Step title="Complete setup with Omni support">
    Omni provisions a service principal for your application in Omni's tenant, creates your blob container, grants that service principal the `Storage Blob Data Reader` role on it, and starts delivering audit logs.

    Omni support will share:

    * **Omni's tenant ID** — you authenticate against this tenant (see below)
    * The **storage account name** and **container name** for your logs
  </Step>
</Steps>

### Reading the logs

Once configured, audit logs are automatically delivered to your container. Authenticate as your application using the client secret or certificate from Step 1.

<Warning>
  Authenticate against **Omni's tenant ID** (the tenant that hosts the storage), not your own home tenant. Your application's service principal — and the read-access grant — live in Omni's tenant, so a token issued by your own tenant is rejected with a `403` even though access is configured correctly.
</Warning>

With the Azure CLI:

```bash theme={null}
# Sign in as your application, pointed at Omni's tenant.
az login --service-principal \
  --username <APPLICATION_CLIENT_ID> \
  --password <CLIENT_SECRET> \
  --tenant <OMNI_TENANT_ID> \
  --allow-no-subscriptions

# List your audit log blobs. --auth-mode login uses your signed-in identity.
az storage blob list \
  --account-name <STORAGE_ACCOUNT_NAME> \
  --container-name <CONTAINER_NAME> \
  --auth-mode login \
  --output table
```

You can also use a tool like [Azure Storage Explorer](https://azure.microsoft.com/products/storage/storage-explorer) or the Azure SDKs — in each case, set the tenant/authority to Omni's tenant ID and the token scope to `https://storage.azure.com/.default`.

### Hardening

Your application only needs to read your audit logs. To keep its footprint minimal:

* **Least privilege is enforced on Omni's side.** Your application's service principal is granted only the `Storage Blob Data Reader` role, scoped to your single audit-log container — no write access and no access to any other container or account.
* **Prefer a certificate over a client secret** for the application credential, and rotate it regularly.
* **Restrict which tenants can use your application.** In the app registration's **Authentication (Preview)** blade, set **Supported account types** to multiple tenants and choose **Allow only certain tenants (Preview)**, then add Omni's tenant ID (and your own). This pins your multitenant application so it can only be used in your tenant and Omni's, rather than any tenant that discovers it. This setting is in preview at the time of writing.

## Option 2: SAS token

If your tooling can't authenticate with Entra, Omni can instead share a read-only [shared access signature (SAS) token](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview) for your dedicated storage account.

### Setup

<Steps>
  <Step title="Request SAS access from Omni support">
    Reach out to Omni support and request SAS-based audit log access.
  </Step>

  <Step title="Receive your access details">
    Omni provisions your dedicated storage account and container, and shares:

    * The **storage account name** and **container name** for your logs
    * The **SAS token** (read and list permissions only, HTTPS only)
  </Step>
</Steps>

### Reading the logs

With the Azure CLI:

```bash theme={null}
az storage blob list \
  --account-name <STORAGE_ACCOUNT_NAME> \
  --container-name <CONTAINER_NAME> \
  --sas-token "<SAS_TOKEN>" \
  --output table
```

### Considerations

* **Treat the token like a password.** Anyone holding it can read your audit logs until it is revoked.
* **Revocation**: if the token is exposed, contact Omni support — Omni rotates the storage account key, which immediately invalidates all outstanding tokens.

## Next steps

* Learn about the [event types](/administration/audit-logs/event-types) supported for audit logs
* Check out your instance's [Analytics section](/administration/analytics)


# Audit log event types
Source: https://docs.omni.co/administration/audit-logs/event-types

Reference for all audit log event types and their payload fields.

This page describes the fields included in each audit log event type. Payloads can contain Omni metadata, which can be safely ignored.

## API request events

Occurs on every API request made to Omni. Event type: `API_REQUEST`

<ParamField type="string">
  The API path that was called (e.g., `/api/v1/query/run`).
</ParamField>

<ParamField type="string">
  The type of the event. This will be `API_REQUEST`.
</ParamField>

<ParamField type="string">
  Audit log marker. This will be `AUDIT`.
</ParamField>

<ParamField type="string">
  The HTTP method used (e.g., `GET`, `POST`).
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The HTTP response status code as a string (e.g., `"200"`, `"403"`).
</ParamField>

<ParamField type="string">
  Whether the request succeeded, as a string. Either `"true"` or `"false"`.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

## Query context events

Occurs when a user loads a document (workbook or dashboard). Event type: `QUERY_CONTEXT`

<ParamField type="string">
  The unique ID of the workbook or dashboard within Omni, found within the URL for the document.
</ParamField>

<ParamField type="string">
  If applicable, the value will be the value of the entity field in an embed URL generated for a user.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `QUERY_CONTEXT`.
</ParamField>

<ParamField type="string">
  Additional detail passed from the log.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni user associated with the event.
</ParamField>

<ParamField type="number">
  The maximum number of query execution events that a query context event can trigger. Can be used to calculate cache hit rate as the denominator.
</ParamField>

<ParamField type="string">
  The URL of the page where the event was issued.
</ParamField>

<ParamField type="string">
  The source of the query context event. Possible values:

  * `DASHBOARD`
  * `WORKBOOK`
  * `QUERY_DOWNLOAD`
  * `SUGGESTIONS`
  * `SUMMARY_VALUES`
  * `AI_FETCH_FIELD_VALUES`
</ParamField>

<ParamField type="string">
  <Warning>
    **Deprecated**. Use `query_source` instead.
  </Warning>

  The first 6 characters of this field are overwritten with `stdout` in delivered audit logs (e.g., `DASHBOARD` becomes `stdoutARD`). The `query_source` field contains the correct uncorrupted value. This field is retained for backwards compatibility only.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries. For example, from a query context or dashboard download event to the query execution events that were subsequently run.
</ParamField>

<ParamField type="string">
  The URL of the page where the event occurred.
</ParamField>

## Query execution events

Occurs when a user runs a query, which may be sent back to the warehouse. Event type: `QUERY_EXECUTE`

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  The ID of the connection or connection environment used to execute the query.
</ParamField>

<ParamField type="number">
  The total length of query execution within the warehouse.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `QUERY_EXECUTE`.
</ParamField>

<ParamField type="string">
  The ID of the corresponding job in the warehouse where the query was executed.
</ParamField>

<ParamField type="string">
  Detail passed from the infrastructure back to the user, if applicable.
</ParamField>

<ParamField type="string">
  A uuid for the query being executed within Omni. Used for query killing purposes.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The query that was executed.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries. For example, from a query context or dashboard download event to the query execution events that were subsequently run.
</ParamField>

<ParamField type="boolean">
  Indicates if the query executed successfully. **Note**: This doesn't indicate the success of the job, only the individual query.
</ParamField>

## Dashboard download events

Occurs when a user downloads a full dashboard. Event type: `DASHBOARD_DOWNLOAD`

<ParamField type="string">
  The unique ID of the workbook or dashboard within Omni, found within the URL for the document.
</ParamField>

<ParamField type="string">
  If applicable, the value will be the value of the entity field in an embed URL generated for a user.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `DASHBOARD_DOWNLOAD`.
</ParamField>

<ParamField type="string">
  Additional detail passed from the log.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries. For example, from a query context or dashboard download event to the query execution events that were subsequently run.
</ParamField>

<ParamField type="string">
  The URL of the page where the event occurred.
</ParamField>

## User invite events

Occurs when a new user is invited to the organization. Event type: `USER_INVITE`

<ParamField type="string">
  The type of the event. This will be `USER_INVITE`.
</ParamField>

<ParamField type="string">
  The ID of the invited user.
</ParamField>

<ParamField type="string">
  Additional detail passed from the log.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

## Connection events

### Connection created

Occurs when a new data connection is created. Event type: `CREATE_CONNECTION`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the connection that was created.
</ParamField>

<ParamField type="string">
  The warehouse dialect for the connection (e.g., `BIGQUERY`, `SNOWFLAKE`, `POSTGRES`).
</ParamField>

<ParamField type="string">
  The type of the event. This will be `CREATE_CONNECTION`.
</ParamField>

<ParamField type="string">
  A JSON object of the connection's non-sensitive field values at creation time. Sensitive fields (credentials, keys, secrets) are redacted.
</ParamField>

<ParamField type="string">
  The name of the connection.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Connection updated

Occurs when a data connection's settings are modified. Event type: `UPDATE_CONNECTION`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  A comma-separated list of field names that were changed.
</ParamField>

<ParamField type="string">
  A JSON object mapping each changed field name to a `from` and `to` value. Sensitive fields (credentials, keys, secrets) are redacted on both sides.
</ParamField>

<ParamField type="string">
  The ID of the connection that was updated.
</ParamField>

<ParamField type="string">
  The warehouse dialect for the connection.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_CONNECTION`.
</ParamField>

<ParamField type="string">
  The name of the connection.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Connection deleted

Occurs when a data connection is deleted (archived). Event type: `DELETE_CONNECTION`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the connection that was deleted.
</ParamField>

<ParamField type="string">
  The warehouse dialect for the connection.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `DELETE_CONNECTION`.
</ParamField>

<ParamField type="string">
  The name of the connection.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Connection restored

Occurs when a previously deleted connection is restored. Event type: `RESTORE_CONNECTION`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the connection that was restored.
</ParamField>

<ParamField type="string">
  The warehouse dialect for the connection.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `RESTORE_CONNECTION`.
</ParamField>

<ParamField type="string">
  The name of the connection.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Connection base role updated

Occurs when the base role for a connection changes. Event type: `UPDATE_CONNECTION_BASE_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the connection associated with the role change.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_CONNECTION_BASE_ROLE`.
</ParamField>

<ParamField type="string">
  Additional detail passed from the log.
</ParamField>

<ParamField type="string">
  The name of the updated base connection role.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Connection credentials updated

Occurs when credentials (password, private key) are rotated on a connection. Event type: `UPDATE_CONNECTION_CREDENTIALS`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the connection whose credentials were updated.
</ParamField>

<ParamField type="string">
  A comma-separated list of credential types that were updated. Possible values include `password` and `privateKey`. Credential values are never included in the audit log.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_CONNECTION_CREDENTIALS`.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

## Organization action events

### Delivery personalization updated

Occurs when the organization's [**Delivery personalization** setting](/administration/content-permissions#delivery-personalization) is changed. Event type: `UPDATE_DELIVERY_PERSONALIZATION_MODE`

<ParamField type="string">
  The type of the event. This will be `UPDATE_DELIVERY_PERSONALIZATION_MODE`.
</ParamField>

<ParamField type="string">
  The updated value of the setting. This will be one of `configurable`, `always`, or `never`.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The number of deliveries updated as a result of the change.
</ParamField>

## Role events

### Organization role updated

Occurs when a user's organization-level role changes. Event type: `UPDATE_ORGANIZATION_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_ORGANIZATION_ROLE`.
</ParamField>

<ParamField type="string">
  The ID of the organization membership record for the user whose role changed.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The name of the new organization role.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### User model role updated

Occurs when a user's model-level role changes. Event type: `UPDATE_USER_MODEL_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_USER_MODEL_ROLE`.
</ParamField>

<ParamField type="string">
  The ID of the model associated with the role change.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The name of the new model role.
</ParamField>

<ParamField type="string">
  The membership ID of the user whose role was updated.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### User group model role updated

Occurs when a user group's model-level role changes. Event type: `UPDATE_GROUP_MODEL_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the connection associated with the role change.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_GROUP_MODEL_ROLE`.
</ParamField>

<ParamField type="string">
  The ID of the model associated with the role change.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The name of the new model role.
</ParamField>

<ParamField type="string">
  The ID of the user group whose role was updated.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Custom role created

Occurs when a custom role is created. Event type: `CREATE_CUSTOM_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The built-in role the custom role is based on.
</ParamField>

<ParamField type="string">
  The display name of the custom role.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `CREATE_CUSTOM_ROLE`.
</ParamField>

<ParamField type="string">
  The internal name of the custom role.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The ID of the newly created custom role.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Custom role updated

Occurs when a custom role's definition is modified. Event type: `UPDATE_CUSTOM_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The built-in role the custom role is based on. Present when the base role has not changed.
</ParamField>

<ParamField type="string">
  The previous base role. Present only when the base role changed.
</ParamField>

<ParamField type="string">
  The new base role. Present only when the base role changed.
</ParamField>

<ParamField type="string">
  The display name of the custom role.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `UPDATE_CUSTOM_ROLE`.
</ParamField>

<ParamField type="string">
  The internal name of the custom role.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The ID of the custom role.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Custom role deleted

Occurs when a custom role is deleted. Event type: `DELETE_CUSTOM_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The built-in role the custom role was based on.
</ParamField>

<ParamField type="string">
  The display name of the custom role.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `DELETE_CUSTOM_ROLE`.
</ParamField>

<ParamField type="string">
  The internal name of the custom role.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The ID of the deleted custom role.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

### Custom role reordered

Occurs when a custom role's priority order is changed relative to another role. Event type: `REORDER_CUSTOM_ROLE`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The built-in role the custom role is based on.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `REORDER_CUSTOM_ROLE`.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The internal name of the role being reordered.
</ParamField>

<ParamField type="string">
  The internal name of the role that `roleName` is being positioned relative to.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

## Content permission events

### Content permission granted

Occurs when a user or group is granted access to a document or folder. Event type: `GRANT_CONTENT_PERMIT`

<ParamField type="string">
  The permission action granted (e.g., `view`, `edit`).
</ParamField>

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the document the permission was granted on, if applicable.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `GRANT_CONTENT_PERMIT`.
</ParamField>

<ParamField type="string">
  The ID of the folder the permission was granted on, if applicable.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The role granted.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

<ParamField type="string">
  A comma-separated list of user group IDs the permission was granted to, if applicable.
</ParamField>

<ParamField type="string">
  A comma-separated list of user IDs the permission was granted to, if applicable.
</ParamField>

<ParamField type="string">
  The ID of the workbook the permission was granted on, if applicable.
</ParamField>

### Content permission revoked

Occurs when a user's or group's access to a document or folder is removed. Event type: `REVOKE_CONTENT_PERMIT`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the document the permission was revoked on, if applicable.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `REVOKE_CONTENT_PERMIT`.
</ParamField>

<ParamField type="string">
  The ID of the folder the permission was revoked on, if applicable.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

<ParamField type="string">
  A comma-separated list of user group IDs whose permission was revoked, if applicable.
</ParamField>

<ParamField type="string">
  A comma-separated list of user IDs whose permission was revoked, if applicable.
</ParamField>

<ParamField type="string">
  The ID of the workbook the permission was revoked on, if applicable.
</ParamField>

### Content ownership transferred

Occurs when ownership of a document or folder is transferred from one user to another. Event type: `TRANSFER_CONTENT_OWNERSHIP`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The ID of the document whose ownership was transferred, if applicable.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `TRANSFER_CONTENT_OWNERSHIP`.
</ParamField>

<ParamField type="string">
  The ID of the folder whose ownership was transferred, if applicable.
</ParamField>

<ParamField type="string">
  The user ID of the new owner.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The user ID of the previous owner.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

<ParamField type="string">
  The ID of the workbook whose ownership was transferred, if applicable.
</ParamField>

## Embed membership events

### Embed membership created

Occurs when an embedded user's membership is created. Event type: `CREATE_EMBED_MEMBERSHIP`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `CREATE_EMBED_MEMBERSHIP`.
</ParamField>

<ParamField type="string">
  The ID of the newly created embed membership.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

<ParamField type="string">
  The ID of the embedded user.
</ParamField>

### Embed membership deleted

Occurs when an embedded user's membership is deleted. Event type: `DELETE_EMBED_MEMBERSHIP`

<ParamField type="object">
  Details about the Omni user associated with the event.
</ParamField>

<ParamField type="string">
  The type of the event. This will be `DELETE_EMBED_MEMBERSHIP`.
</ParamField>

<ParamField type="string">
  The ID of the deleted embed membership.
</ParamField>

<ParamField type="string">
  The unique identifier for the Omni organization.
</ParamField>

<ParamField type="string">
  The time the event occurred.
</ParamField>

<ParamField type="string">
  A uuid that can be used to trace the event across other log entries.
</ParamField>

<ParamField type="string">
  The ID of the embedded user.
</ParamField>


# Using Google Cloud Storage for Omni audit logs
Source: https://docs.omni.co/administration/audit-logs/google-cloud-storage

Configure Google Cloud Storage as the destination for your Omni audit logs to track user activity with structured event data.

<Note>
  Reach out to Omni support to have audit logs enabled for your instance.
</Note>

Audit logs are detailed records of the activity your users are taking in Omni, which can be useful for security and performance analysis. Events included in logs are structured as JSON payloads and sent in batches to your cloud storage bucket a few minutes after they're written.

## Supported authentication methods

Audit logs can be delivered to a Google Cloud Storage (GCS) bucket using one of two authentication methods:

* **Workload Identity Federation** - Workload Identity Federation allows Omni's audit log delivery service to authenticate to your GCS bucket using AWS IAM credentials through GCP Workload Identity Federation.
  <Note>
    This is the recommended authentication method for GCS as it eliminates the need to manage long-lived service account keys.
  </Note>
* **Service account key** - This method uses a service account JSON key file for authentication. While straightforward, it requires managing long-lived credentials.

## Option 1: Workload Identity Federation

This approach provides enhanced security by:

* Eliminating the need to share or rotate service account keys
* Using temporary, automatically rotating credentials
* Leveraging your existing AWS and GCP IAM policies

### Requirements

* An existing GCS bucket where audit logs will be delivered
* Permissions to create and configure a Workload Identity Pool in your GCP project
* Permissions to create and configure a service account with write access to your GCS bucket

### Setup

Work with Omni support to configure Workload Identity Federation. The setup involves:

<Steps>
  <Step title="Get credentials from Omni support">
    Omni support will provide you with the AWS Account ID and AWS IAM role ARN that will authenticate to your GCS bucket.
  </Step>

  <Step title="Create a Workload Identity Pool">
    Create a [Workload Identity Pool and AWS provider](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#gcloud_1) in your GCP project.
  </Step>

  <Step title="Create a GCP service account">
    Create a [GCP service account](https://docs.cloud.google.com/iam/docs/service-accounts-create) with write permissions (`objectCreator` role) to your GCS bucket.
  </Step>

  <Step title="Configure the Workload Identity Pool">
    Configure the Workload Identity Pool to allow the Omni AWS IAM role you received in step 1 to impersonate your GCP service account.
  </Step>

  <Step title="Provide Omni with the connection details">
    Provide Omni support with the following:

    * Project number
    * Pool ID
    * Provider ID
    * Service account email
  </Step>

  <Step title="Complete setup with Omni support">
    Omni support completes the configuration on the Omni side.
  </Step>
</Steps>

Once configured, audit logs will be automatically delivered to your GCS bucket without requiring any credential management.

## Option 2: Service account key

This approach uses a service account JSON key file to authenticate to the GCS bucket.

<Note>
  The [Workplace Identity Federation approach](#option-1-workload-identity-federation) is recommended over using a service account key.
</Note>

### Requirements

* An existing GCS bucket where audit logs will be delivered
* Permissions in GCS that allow you to create a service account key

### Setup

<Steps>
  <Step title="Create a service account key">
    Create a [service account key](https://docs.cloud.google.com/iam/docs/keys-create-delete) in GCS.
  </Step>

  <Step title="Provide Omni support with your bucket details">
    Provide Omni support with the name of your GCS bucket and the service account key you created in the previous step.
  </Step>

  <Step title="Complete setup with Omni support">
    Omni support completes the configuration on the Omni side.
  </Step>
</Steps>

Once configured, audit logs will be automatically delivered to your GCS bucket.

## Next steps

* Learn about the [event types](/administration/audit-logs/event-types) supported for audit logs
* Check out your instance's [Analytics section](/administration/analytics)


# Audit logs
Source: https://docs.omni.co/administration/audit-logs/index

Set up audit logging in Omni to track user activity with structured event logs delivered to Amazon S3, Google Cloud Storage, or Azure Blob Storage.

Audit logs are detailed records of the activity your users are taking in Omni, which can be useful for security and performance analysis. Events included in logs are structured as JSON payloads and sent in batches to cloud storage a few minutes after they're written.

## Delivery destinations

Audit logs can be delivered to Amazon S3, Google Cloud Storage, or Azure Blob Storage.

<Columns>
  <Card title="Amazon S3" icon="aws" href="/administration/audit-logs/amazon-s3">
    Send event logs to an Amazon S3 bucket, either Omni-hosted or customer-hosted
  </Card>

  <Card title="Google Cloud Storage" icon="google" href="/administration/audit-logs/google-cloud-storage">
    Send event logs to a Google Cloud Storage bucket
  </Card>

  <Card title="Azure Blob Storage" icon="microsoft" href="/administration/audit-logs/azure-blob-storage">
    Read event logs from an Omni-hosted Azure Blob Storage container
  </Card>
</Columns>

## Data retention

By default, logs are retained for at least one year. Contact Omni support if you need a shorter retention period.

## Event types

Each audit log entry includes an event type that identifies the user action that triggered it. See the [event types reference](/administration/audit-logs/event-types) for a full list of supported events and their payload fields.


# Microsoft Entra authentication
Source: https://docs.omni.co/administration/authentication/entra/index

Connect Omni to Microsoft Entra for secure SAML single sign-on and automated user provisioning.

You can connect Omni to Microsoft Entra to manage authentication and user access through your organization’s existing identity provider.

Entra supports **SAML** for single sign-on and **SCIM** for automated user provisioning. You can also sync additional **user attributes** like name, title, or department to keep Omni profiles up to date.

## Integration overview

Connecting Entra to Omni allows you to:

1. **Authenticate users** through Entra using SAML.
2. **Control when and how users are provisioned** in Omni.
3. **Sync user profile data** such as display name and department through attribute mappings.

### User provisioning options

Omni supports two approaches for provisioning users:

| Option                       | How it works                                                      | When to use                                                                                      |
| ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **SCIM provisioning**        | Users are created in Omni when assigned to the Omni app in Entra. | You want users provisioned immediately upon assignment, regardless of whether they've logged in. |
| **First-login provisioning** | Users are created in Omni only when they first log in via SAML.   | You want to control seat usage by provisioning users only when they actually access Omni.        |

You can use first-login provisioning with or without SCIM. Refer to the [SAML setup guide](/administration/authentication/entra/saml) for more details.

## Getting started

Follow these steps to get set up.

You can complete SAML only, or add SCIM and attribute sync for a fully automated experience.

| Step | Description                                                                                 | Link                                                                      |
| ---- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| 1    | **Set up SAML SSO** to let users sign in to Omni with their Entra credentials.              | [SAML setup →](/administration/authentication/entra/saml)                 |
| 2    | **Enable SCIM provisioning** to automatically create, update, and deactivate users in Omni. | [SCIM setup →](/administration/authentication/entra/scim)                 |
| 3    | **Sync user attributes** like name, title, and department between Entra and Omni.           | [Sync attributes →](/administration/authentication/entra/user-attributes) |

## Notes and troubleshooting

* **Admin access required:** You’ll need Entra admin permissions to configure SAML and SCIM.
* **Test before rollout:** Try SSO with a test user before enabling it organization-wide.
* **Sync frequency:** SCIM updates usually occur within a few minutes of changes in Entra.

If you run into issues, check your Entra app configuration or see [Omni's troubleshooting SSO guide](/administration/authentication/troubleshooting).

## Related

* [Omni SAML configuration overview](/administration/authentication)
* [Managing users and groups in Omni](/administration/users)
* [Entra documentation](https://\[idp-docs-link]/)


# Microsoft Entra SAML authentication
Source: https://docs.omni.co/administration/authentication/entra/saml

Configure service provider (SP)-initiated SAML authentication between Microsoft Entra and Omni.

When enabled, users in your organization can log into Omni using their Microsoft Entra credentials.

## Requirements

To follow the steps in this guide, you'll need:

* **Omni Organization Admin permissions**

* **Permissions in Microsoft Entra that allow you to:**

  * Access the admin panel
  * Add & configure Microsoft Entra applications
  * Assign users to applications

## Setup

<Steps>
  <Step title="Open the Omni authentication settings">
    In your Omni instance, navigate to **Settings > Authentication** and locate the **SAML** section.

    Leave this page open - you'll need it to complete the setup.
  </Step>

  <Step title="Create an Omni application in Entra">
    1. Log in to the Microsoft Entra admin panel.
    2. Navigate to **Applications > Enterprise Applications**.
    3. Click **New application**, then **Create your own application**.
    4. Name the application `Omni`.
    5. Select the **Integrate any other application you don't find in the gallery (Non-gallery)** option.
    6. Click **Create**.
  </Step>

  <Step title="Configure the Entra Omni application">
    1. Click the Entra Omni application you created in the previous step.

    2. Navigate to the **Manage > Single sign-on configuration** section.

    3. Select **SAML sign-on** as the method.

    4. In the **Basic SAML configuration** section, click **Edit** and modify these settings:

       * **Identifier (Entity ID)** - Enter the full hostname of your Omni instance, e.g. `blobsrus.omniapp.co`. Do not include `https://`.
       * **Reply URL (Assertion Consumer Service URL)** - Copy and paste the value of the **Single sign-on URL** field from the Omni Authentication settings you opened in step 1.

    5. Save the changes to the settings.

    Next, edit the application's **Attributes & Claims**. This requires **three claims**, outlined as follows:

    |                      | **Claim 1**                                                                                    | **Claim 2**       | **Claim 3**      |
    | -------------------- | ---------------------------------------------------------------------------------------------- | ----------------- | ---------------- |
    | **Description**      | User's email address                                                                           | User's first name | User's last name |
    | **Name**             | `email_address`                                                                                | `first_name`      | `last_name`      |
    | **Namespace**        | Leave blank                                                                                    | Leave blank       | Leave blank      |
    | **Source**           | Attribute                                                                                      | Attribute         | Attribute        |
    | **Source attribute** | The attribute you use to identify a user's email address. Usually `user.email` or `user.mail`. | `user.first_name` | `user.surname`   |

    <Note>
      The name for a claim must **match exactly** the value in the **Name** row in the above table. For example, `first_name` is valid but `firstName` is not.
    </Note>

    Create and configure the claims for the application until you have one for each of the claims outlined in the previous table.
  </Step>

  <Step title="Assign yourself to the Entra Omni application">
    In this step, you'll assign the Entra Omni application to yourself. This will allow you to test the setup in Omni before rolling everything out to your organization.

    Follow the steps in the [Entra documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-assign-users#assign-a-user-account-to-an-enterprise-application) to assign yourself to the Omni application.
  </Step>

  <Step title="Download the signing certificate">
    1. In the Entra Omni application's settings, locate the **SAML Certificates** section.
    2. Click the **Base64** download link to [download the certificate](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/tutorial-manage-certificates-for-federated-single-sign-on#autogenerated-certificate-for-gallery-and-non-gallery-applications).
    3. Locate the certificate file on your computer and change the extension to `.txt`. This will allow you to open it.
    4. Keep the file open - you'll need it to complete the next step.
  </Step>

  <Step title="Configure Omni authentication settings">
    Navigate back to the Omni authentication settings (**Settings > Authentication**) to complete the setup:

    * **Display Name** - Enter a name to customize the login button, for example `Microsoft Entra`. Leave blank to show the default **Log in with SAML** button.

    * **Entity ID / Issuer** - Copy and paste the **Microsoft Entra ID Identifier** value from Entra

    * **SSO (Sign on) URL** - Copy and paste the **Login URL** value from Entra

    * **Certificate** - Copy and paste the contents of the certificate you downloaded in step 4.

      <Warning>
        The certificate must include `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, for example:

        ```txt wrap theme={null}
        -----BEGIN CERTIFICATE-----[Your certificate contents]-----END CERTIFICATE-----
        ```

        If the certificate you paste into Omni doesn't have these values, add them in the **Certificate** field so that it looks like the above example.
      </Warning>

    * **Automatically provision new users on first login from this SAML provider** - Toggle this setting to **on** if:

      * You want to provision users only when they first access Omni **and**
      * You don't plan to set up SCIM provisioning

    * **Enable SAML login** - Toggle this setting to **on** to enable SAML authentication

    When finished, click **Save SAML changes**.
  </Step>

  <Step title="Test the setup">
    Test your SAML setup by logging out of Omni. On the Omni login page, you should see a login button. Click the button to log in using SAML.

    <Tip>
      By default, the login button will read **Log in with SAML**. Set a **Display Name** in the [Omni authentication settings](#omni-auth-settings) to customize this text.
    </Tip>
  </Step>

  <Step title="Assign users to the Omni application">
    <Note>
      User groups can be pushed from Microsoft Entra to Omni using SCIM. Check out the [Entra-Omni SCIM guide](/administration/authentication/entra/scim) for more information.
    </Note>

    Once you confirm everything is working as expected, you can assign the Omni application to other people and groups in your organization.

    Follow the steps in the [Entra documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-assign-users#assign-a-user-account-to-an-enterprise-application) to assign users to the Omni application.
  </Step>
</Steps>

## What's next?

Setting up SAML allows your users to authenticate to Omni using their Microsoft Entra credentials. With this setup completed, you can also:

* [Configure SCIM to auto-provision users & user groups in Omni](/administration/authentication/entra/scim)
* [Use SCIM to sync user attributes from Microsoft Entra to Omni](/administration/authentication/entra/user-attributes)


# Auto-provisioning Omni users with Microsoft Entra SCIM
Source: https://docs.omni.co/administration/authentication/entra/scim

Automatically manage Omni accounts for your users with Microsoft Entra SCIM provisioning.

When SCIM (System for Cross-domain Identity Management) is enabled, you can automatically provision and de-provision Omni accounts for your users and synchronize Omni user groups with groups in Microsoft Entra (formerly Active Directory / Azure AD).

## Requirements

To follow the steps in this guide, you'll need:

* **To have Microsoft Entra SAML authentication set up**. If you don't, refer to the [Microsoft Entra SAML authentication setup guide](/administration/authentication/entra/saml) before proceeding.
* **Omni Organization Admin permissions**
* **Permissions in Microsoft Entra that allow you to:**
  * Access the Entra admin panel
  * Modify Entra applications

## Limitations

Omni [system user attributes](/administration/users/attributes#default-system-user-attributes) are read-only and cannot be assigned via SCIM.

## Steps

<Note>
  Omni users created via SCIM will have **Organization Member** permissions. Organization Admins must be created in **Settings > Users** or have their permissions [manually upgraded](/administration/users/permissions).
</Note>

<Steps>
  <Step title="Create an Omni API key">
    1. Follow [these steps](/api/authentication) to create a new API key named **Entra SCIM**.
    2. Copy the key somewhere handy - you'll need it to complete the setup.
  </Step>

  <Step title="Configure the Omni Entra application">
    This guide assumes that you have an existing Omni application in Microsoft Entra. Refer to the [SAML setup guide](/administration/authentication/entra/saml) if you have not yet created an Omni application.

    1. Log in to the Microsoft Entra admin panel.
    2. Navigate to **Applications > Enterprise Applications**.
    3. Locate and open the Omni application.
    4. In the Omni application, navigate to **Manage > Provisioning**.
    5. For the **provisioning mode**, select **Automatic Provisioning Mode**.
    6. Configure the **Admin credentials section** as follows:
       * **Tenant URL** - Enter the URL you use to log into Omni, appended with `/api/scim/v2`.

         For example, if your Omni login URL is `https://blobsrus.omniapp.co`, you would enter `https://blobsrus.omniapp.co/api/scim/v2`.
       * **Secret Token** - Paste the Omni API key you created in step 1
    7. Click **Test connection** and proceed if successful.
  </Step>

  <Step title="Configure mappings">
    In this step, you'll configure the user and user group mappings to provision in Omni.

    1. In the **Mappings** section, click the type of object you want to map - users or user groups.
    2. Remove all default attribute mappings **except the following**:
       * **For users** - Remove all mappings except `userName`, `active`, and `displayName`
       * **For user groups** - Remove all mappings except `displayName` and `members`
    3. Click **Save**.

    <Warning>
      Map **only** the attributes listed above. Microsoft Entra includes every mapped attribute in each sync request, and Omni's SCIM validation will reject any provisioning or de-provisioning request that contains attributes beyond those it supports. Leaving Entra's default mappings in place (for example `name.givenName`, `emails`, or `externalId`) will cause both user provisioning and de-provisioning to fail.

      The only supported user attributes are `userName`, `active`, and `displayName`, and for groups `displayName` and `members`. To sync additional user attributes, map them under the Omni user attribute namespace as described in the [Syncing Entra user attributes guide](/administration/authentication/entra/user-attributes).
    </Warning>
  </Step>

  <Step title="Configure Omni login settings">
    1. In Omni, navigate to **Settings > Authentication**.
    2. Enable **Automatically provision new users on first login from this SAML provider**. This ensures that users assigned to the Omni app in Entra are automatically created in Omni when they first log in via SAML.
    3. Click **Save SAML changes**.
  </Step>
</Steps>

**Note**: when users are removed from Entra they will be de-provisioned and revoked in Omni which has implications for the schedules and content they own. See the [Revoke Membership](/administration/users/delete) page for more details.

## What's next?

After you finish setting up SCIM, you can go a step further and sync your custom user attributes from Entra to Omni.

Refer to the [Syncing Entra user attributes guide](/administration/authentication/entra/user-attributes) for more information.


# Syncing Microsoft Entra user attributes to Omni with SCIM
Source: https://docs.omni.co/administration/authentication/entra/user-attributes

Sync user attributes from Microsoft Entra to Omni via SCIM.

Custom user attributes can be synced from Microsoft Entra (formerly Active Directory / Azure AD) to Omni, allowing you to fully centralize your user management in Microsoft Entra.

In this guide, we'll demonstrate how to sync a user attribute named `blob_entity` from Microsoft Entra to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **To set up SCIM provisioning with Entra**. Refer to the [Omni Entra SCIM guide](/administration/authentication/entra/scim) for more information.
* **Organization Admin** permissions in Omni
* **Permissions in Microsoft Entra** that allow you to:
  * Access the admin panel
  * Create user profile attributes
  * Modify applications

## Limitations

Omni [system user attributes](/administration/users/attributes#default-system-user-attributes) are read-only and cannot be assigned via SCIM.

## Setup

<Steps>
  <Step title="Create an Omni user attribute">
    In Omni, navigate to **Settings > Attributes** and [create a new attribute](/administration/users/attributes).

    Our example attribute, `blob_entity`, has the following settings:

    * **Name** - `Blob Entity`
    * **Reference** - `blob_entity`
    * **Type** - `string`

      <img alt="" />
  </Step>

  <Step title="Create an Entra user attribute">
    1. Log in to your Entra admin panel.
    2. Navigate to **Entra ID > Enterprise apps**.
    3. Click the Omni application.
    4. In the sidebar, click **Provisioning** under the **Manage** heading.
    5. Open the **Mappings** section.
    6. In this section, select the user you want to add an attribute to.
    7. At the bottom of the page, select **Show advanced options**.
    8. Select **Edit attribute list for customappsso**.
    9. Enter the following for the attribute:
       * **Name** - Enter the **reference** of the attribute you created in Omni in step 1, prefixed with the following:
         ```txt theme={null}
         urn:omni:params:1.0:UserAttribute:
         ```
         For example, for the `blob_entity` attribute, you'd enter `urn:omni:params:1.0:UserAttribute:blob_entity`.
       * **Type** - Select the **type** of the attribute you created in Omni: `string` or `integer`
       * **Multi-value?** - Select this option if the Omni attribute is configured to support multiple values.
    10. Configure the remaining fields as needed.
    11. Save the changes.
  </Step>

  <Step title="Create attribute mapping">
    1. A message should display after you click **Save** - click **Yes**.
    2. In the **Attribute Mapping** page that opens, click **Add New Mapping**.
    3. In the **Target attribute** dropdown, select the attribute you created in step 2.
    4. Configure the remaining fields to map the appropriate value to the attribute.
    5. Click **OK**, then **Save**.
  </Step>
</Steps>

## What's next?

The Omni application should be set to automatically provision users and groups - see the [Entra SCIM guide](/administration/authentication/entra/scim) - meaning that the next time the app syncs, the attributes should be created as [user attributes in Omni](/administration/users/attributes).


# Managing users with Google Workspace SAML
Source: https://docs.omni.co/administration/authentication/google-workspace

Integrate Omni with Google Workspace for user authentication via the SAML protocol.

## Limitations

* User and user group provisioning via SCIM is not currently supported for Google Workspace
* User sessions expire after 24 hours, after which users will then need to reauthenticate

## Requirements

To follow the steps in this guide, you'll need:

* Omni [Organization Admin permissions](/administration/users/permissions)
* Google Workspace [Super Administrator permissions](https://support.google.com/a/answer/2405986?sjid=8929730596146089385-NA)

## Setup

<Steps>
  <Step title="Open the Omni authentication settings">
    In your Omni instance, navigate to **Settings > Authentication** and locate the **SAML** section.

    Leave this page open - you'll need it to complete the setup.
  </Step>

  <Step title="Create an Omni Google Workspace app">
    1. Log in to your Google Workspace Admin console.
    2. In the navigation bar, click **Apps > Web and mobile apps**.
    3. Click the **Add app** dropdown, then **Add custom SAML app**.
    4. Name the app `Omni Analytics`. You can also add a description and logo.
    5. Click **Continue**.
    6. On the **Google Identity Provider details** page, copy the following information somewhere handy - you'll need it to complete the setup in Omni:

       * SSO URL
       * Entity ID
       * Certificate - **Note**: You will need to download the certificate.
    7. Click **Continue**.
    8. In the **Service Provider Details window**, fill in the following:
       * **ACS URL** - Copy and paste the **Single sign-on URL** value from the Omni Authentication settings (step 1)
       * **Entity ID** - Enter the full hostname of your Omni instance, e.g. `blobsrus.omniapp.co`. Do not include `https://`.
       * **Name ID format** - Set to `Email`
       * **Name ID** - Set to `Basic Information > Primary email`
    9. Click **Continue**.
    10. Click **Add mappings** and add the following mappings:
        * `First name` to `first_name`
        * `Last name` to `last_name`
    11. Click **Finish**.
  </Step>

  <Step title="Configure Omni authentication settings">
    Navigate back to the Omni Authentication settings (**Settings > Authentication**) to complete the setup:

    * **Display Name** - Enter a name to customize the login button, for example `Google Workspace`. Leave blank to show the default **Log in with SAML** button.

    * **Entity ID / Issuer** - Copy and paste the **Entity ID** value from Google Workspace

    * **SSO (Sign on) URL** - Copy and paste the **SSO URL** value from Google Workspace

    * **Certificate** - Copy and paste the contents of the certificate you downloaded in step 2. The certificate must include `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` values, for example:

      ```txt wrap theme={null}
      -----BEGIN CERTIFICATE-----
      [certificate contents]
      -----END CERTIFICATE-----
      ```

    * **Enable SAML for users** - Toggle this setting to **on**

    When finished, click **Save SAML changes**.
  </Step>

  <Step title="Assign users & groups">
    In the Google Workspace Admin console, use the **User access section** in the Omni app to grant users access. Refer to [Google's documentation](https://support.google.com/a/answer/6087519?hl=en#zippy=%2Cstep-turn-on-your-saml-app) for more information.

    <Warning>
      The email addresses your users use to sign in to Omni must match the email addresses they use to sign in to your Google domain.
    </Warning>
  </Step>

  <Step title="Test the setup">
    Test your SAML setup by logging out of Omni. On the Omni login page, you should see a login button. Click the button to log in using SAML.

    <Tip>
      By default, the login button will read **Log in with SAML**. Set a **Display Name** in the [Omni authentication settings](#omni-auth-settings) to customize this text.
    </Tip>

    If the setup is successful, finish the setup by rolling out SAML authentication to the rest of your organization.
  </Step>
</Steps>


# Set up Identity Providers (IdP) for authentication
Source: https://docs.omni.co/administration/authentication/index

Configure SSO, SAML, or OIDC for your Omni organization

Omni supports authentication with identity providers through SAML and OIDC. This allows your users to sign in using your organization's existing identity management system.

Select your identity provider below to get started.

## Identity providers

<Columns>
  <Card icon="google" href="/administration/authentication/google-workspace" title="Google Workspace">
    Set up SSO with Google Workspace
  </Card>

  <Card icon="microsoft" href="/administration/authentication/entra" title="Microsoft Entra (Azure AD)">
    Set up SSO with Microsoft Entra ID horizontal
  </Card>

  <Card icon="key" href="/administration/authentication/okta" title="Okta">
    Set up SSO with Okta
  </Card>

  <Card icon="key" href="/administration/authentication/rippling" title="Rippling">
    Set up SSO with Rippling
  </Card>

  <Card icon="key" href="/administration/authentication/oidc" title="OpenID Connect">
    Configure OAuth using OIDC
  </Card>
</Columns>

## SAML and SCIM

For Microsoft Entra, Okta, and Rippling, Omni supports both SAML and SCIM:

* **SAML** - Enables single sign-on authentication
* **SCIM** - Enables automatic user provisioning and de-provisioning. **Note**: While custom user attributes can be synced using SCIM, Omni's [default system user attributes](/administration/users/attributes#default-system-user-attributes) are read-only and cannot be assigned via SCIM.

## Need help?

If you run into issues during setup, check the [SSO troubleshooting guide](/administration/authentication/troubleshooting) for common problems and solutions.


# Configuring OIDC authentication
Source: https://docs.omni.co/administration/authentication/oidc

Configure OpenID Connect (OIDC) authentication for your Omni organization.

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0. When enabled, users in your organization can log into Omni using credentials from any OIDC-compliant identity provider.

## Requirements

To follow the steps in this guide, you'll need:

* **Omni Organization Admin permissions**
* **Access to your OIDC identity provider** with permissions to:
  * Create or configure applications
  * Access client credentials and discovery endpoints

## Limitations

**User sessions will expire after 24 hours**. This is not currently configurable.

## Setup

<Steps>
  <Step title="Retrieve OIDC provider details">
    In your OIDC identity provider, obtain the following information:

    * **Issuer URL** - The issuer URL of your OIDC server
    * **Client ID** - The unique identifier for your Omni application
    * **Client Secret** - The secret key for authenticating your application

    Keep this information handy - you'll need it to complete the setup in Omni.

    <Note>
      The exact steps to obtain these values will vary depending on your identity provider. Consult your provider's documentation for specific instructions on creating an OIDC application.
    </Note>
  </Step>

  <Step title="Configure redirect URI in your identity provider">
    In your OIDC identity provider's application settings, you'll need to configure the **Redirect URI** (also called **Callback URL**).

    The redirect URI should be in the following format:

    ```html wrap theme={null}
    https://[your-omni-subdomain].omniapp.co/auth/oidc/callback
    ```

    For example, if you log in to `https://blobsrus.omniapp.co`, your redirect URI would be:

    ```html wrap theme={null}
    https://blobsrus.omniapp.co/auth/oidc/callback
    ```
  </Step>

  <Step title="Configure Omni authentication settings">
    In Omni, navigate to **Settings > Authentication > OIDC Configuration** to complete the setup:

    * **Display name** - Enter a name, for example `Blobs R Us auth`
    * **Issuer URL** - Paste the issuer URL from your OIDC provider.
    * **Client ID** - Copy and paste the Client ID from your OIDC provider
    * **Client Secret** - Copy and paste the Client Secret from your OIDC provider
    * **Automatically provision new users on first login from this OIDC provider** - Toggle this setting to **on** if you want to provision users only when they first access Omni
    * **Enable OIDC for users** - Toggle this setting to **on** to enable OIDC authentication

    When finished, click **Save OIDC changes**.
  </Step>

  <Step title="Test the setup">
    Test your OIDC setup by logging out of Omni. On the Omni login page, you should see a **Log in with OIDC** button. Click the button to log in using OIDC.

    If the setup is successful, you can proceed to assign the application to other users in your organization through your identity provider.
  </Step>
</Steps>

**Note**: when users are removed from your OIDC system they will be de-provisioned and revoked in Omni which has implications for the schedules and content they own. See the [Revoke Membership](/administration/users/delete) page for more details.


# Okta authentication
Source: https://docs.omni.co/administration/authentication/okta/index

Connect Omni to Okta for secure SAML single sign-on and automated user provisioning.

You can connect Omni to Okta to manage authentication and user access through your organization’s existing identity provider.

Okta supports **SAML** for single sign-on and **SCIM** for automated user provisioning. You can also sync additional **user attributes** like name, title, or department to keep Omni profiles up to date.

## Integration overview

Connecting Okta to Omni allows you to:

1. **Authenticate users** through Okta using SAML.
2. **Control when and how users are provisioned** in Omni.
3. **Sync user profile data** such as display name and department through attribute mappings.

### Supported features

Omni supports the following Okta provisioning features:

* **Push users** - Users in Okta that are assigned to the Omni application in Okta are automatically added as users in Omni.
* **Update user attributes** - When user attributes are updated in Okta, they will be updated in Omni.
* **Remove/deactivate users** - When users are removed or deactivated in Okta, their membership to your Omni organization will be revoked.
* **Reactivate users** - Reactivating a user will create a new user in Omni with a new external ID.
* **Push groups** - Groups and their members in Okta can be pushed to Omni as Omni groups and group members.

### User provisioning options

Omni supports two approaches for provisioning users:

| Option                       | How it works                                                     | When to use                                                                                      |
| ---------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **SCIM provisioning**        | Users are created in Omni when assigned to the Omni app in Okta. | You want users provisioned immediately upon assignment, regardless of whether they've logged in. |
| **First-login provisioning** | Users are created in Omni only when they first log in via SAML.  | You want to control seat usage by provisioning users only when they actually access Omni.        |

You can use first-login provisioning with or without SCIM. Refer to the [SAML setup guide](/administration/authentication/okta/saml) for more details.

### Limitations

Omni does not currently support the following Okta provisioning features:

* Sync password
* Enhanced group push

Additionally, note that user sessions will expire after 24 hours. This is not currently configurable.

## Getting started

Follow these steps to get set up.

You can complete SAML only, or add SCIM and attribute sync for a fully automated experience.

| Step | Description                                                                                 | Link                                                                     |
| ---- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 1    | **Set up SAML SSO** to let users sign in to Omni with their Okta credentials.               | [SAML setup →](/administration/authentication/okta/saml)                 |
| 2    | **Enable SCIM provisioning** to automatically create, update, and deactivate users in Omni. | [SCIM setup →](/administration/authentication/okta/scim)                 |
| 3    | **Sync user attributes** like name, title, and department between Okta and Omni.            | [Sync attributes →](/administration/authentication/okta/user-attributes) |

## Notes and troubleshooting

* **Admin access required:** You’ll need Okta admin permissions to configure SAML and SCIM.
* **Test before rollout:** Try SSO with a test user before enabling it organization-wide.
* **Sync frequency:** SCIM updates usually occur within a few minutes of changes in Okta.

If you run into issues, check your Okta app configuration or see [Omni's troubleshooting SSO guide](/administration/authentication/troubleshooting).

## Related

* [Omni SAML configuration overview](/administration/authentication)
* [Managing users and groups in Omni](/administration/users)
* [Okta documentation](https://\[idp-docs-link]/)


# Configuring Okta SAML authentication
Source: https://docs.omni.co/administration/authentication/okta/saml

Configure service provider (SP)-initiated SAML authentication between Okta and Omni.

When enabled, users in your organization can log into Omni using their Okta credentials.

## Requirements

To follow the steps in this guide, you'll need:

* **Omni Organization Admin permissions**
* **Permissions in Okta that allow you to:**
  * Access the Admin console
  * Add & configure Okta applications

## Limitations

* **User sessions will expire after 24 hours**. This is not currently configurable.
* **Users will not be able to click the Omni tile in Okta to log in**. This is because Omni's current integration with Okta is not Identity service provider (IdP) initiated, but SP-initiated.

## Setup

<Steps>
  <Step title="Add the Omni application in Okta">
    1. Log in to your Okta Admin console.
    2. Navigate to **Applications > Applications > Browser App Catalog**.
    3. Search for the `Omni Analytics` application.
    4. Click **Add integration**.
    5. On the page that displays, enter your Omni **subdomain**. For example, if you log in to `https://blobsrus.omniapp.co`, you would enter `blobsrus`.
    6. Click **Save**.
  </Step>

  <Step title="Retrieve Okta Omni application details">
    Navigate to the Okta Omni application and then complete the following:

    1. In the Okta Omni application, open the **Sign on** tab.
    2. In the **SAML 2.0** section, click **More details**:
       <img alt="" />
    3. Keep this section open - you'll need the **Sign on URL**, **Issuer**, and **Signing certificate** handy to complete the next step.
       <img alt="" />
  </Step>

  <Step title="Assign yourself to the Omni application">
    In this step, you'll assign the Okta Omni application to yourself. This will allow you to test the setup in Omni before rolling everything out to your organization.

    1. In the Okta Omni application, open the **Assignments** tab.
    2. Click the **Assign** button, then **Assign to people**.
    3. In the dialog that displays, click the **Assign** link next to your user.
    4. You'll be directed to confirm details about the user, including the email address and display name. Modify these settings as needed.
    5. When finished, click **Save and Go back**.
    6. Click **Done**.
  </Step>

  <Step title="Configure Omni authentication settings">
    In Omni, navigate to **Settings > Authentication** to complete the setup:

    * **Display Name** - Enter a name to customize the login button, for example `Okta`. Leave blank to show the default **Log in with SAML** button.

    * **Entity ID / Issuer** - Copy and paste the **Issuer** value from Okta

    * **SSO (Sign on) URL** - Copy and paste the **Sign on URL** value from Okta

    * **Certificate** - Use the **Copy** button next to the **Certificate** field in Okta, then paste the contents in Omni.

      <Warning>
        The certificate must include `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, for example:

        ```txt wrap theme={null}
        -----BEGIN CERTIFICATE-----
        [Your Okta certificate contents]
        -----END CERTIFICATE-----
        ```

        After you paste the certificate into Omni, add these values above and below the certificate so that it looks like the above example.
      </Warning>

    * **Automatically provision new users on first login from this SAML provider** - Toggle this setting to **on** if:

      * You want to provision users only when they first access Omni **and**
      * You don't plan to set up SCIM provisioning

    * **Enable SAML login** - Toggle this setting to **on** to enable SAML authentication

    When finished, click **Save SAML changes**.
  </Step>

  <Step title="Test the setup">
    Test your SAML setup by logging out of Omni. On the Omni login page, you should see a login button. Click the button to log in using SAML.

    <Tip>
      By default, the login button will read **Log in with SAML**. Set a **Display Name** in the [Omni authentication settings](#omni-auth-settings) to customize this text.
    </Tip>
  </Step>

  <Step title="Assign users to the Okta Omni application">
    <Tip>
      User groups can be pushed from Okta to Omni using SCIM. Check out the [Okta-Omni SCIM guide](/administration/authentication/okta/scim) for more information.
    </Tip>

    Once you confirm everything is working as expected, you can assign the Okta Omni application to other people and groups in your organization. **Not sure what permissions to use?** Refer to the [Connection permissions guide](/administration/users/permissions) for more information.

    In Okta:

    1. In the Okta Omni application, open the **Assignments** tab.
    2. Click the **Assign** button, then **Assign to people**.
    3. In the dialog that displays, click the **Assign** link next to the user.
    4. You'll be directed to confirm details about the user, including the email address and display name. Modify these settings as needed.
    5. When finished, click **Save and Go back**.
    6. Click **Done**.

    Users will now be able to navigate to Omni in their browser and use SAML to log in.
  </Step>
</Steps>

## What's next?

Setting up SAML allows your users to authenticate to Omni using their Okta credentials. With this setup completed, you can also:

* [Configure SCIM to auto-provision users & user groups in Omni](/administration/authentication/okta/scim)
* [Use SCIM to sync user attributes from Okta to Omni](/administration/authentication/okta/user-attributes)


# Auto-provisioning Omni users with Okta SCIM
Source: https://docs.omni.co/administration/authentication/okta/scim

Automatically manage Omni accounts for your users with Okta SCIM provisioning.

When SCIM (System for Cross-domain Identity Management) is enabled, you can automatically provision and de-provision Omni accounts for your users and synchronize Omni user groups with groups in Okta.

## Requirements

To follow the steps in this guide, you'll need:

* **To have Okta SAML authentication set up**. If you don't, refer to the [Okta SAML authentication setup guide](/administration/authentication/okta/saml) before proceeding.
* **Omni Organization Admin permissions**
* **Permissions in Okta that allow you to:**
  * Access the Admin console
  * Modify Okta applications

## Limitations

* Omni [system user attributes](/administration/users/attributes#default-system-user-attributes) are read-only and cannot be assigned via SCIM
* Omni does not currently support the following Okta provisioning features:

  * Sync password
  * Enhanced group push

  Additionally, pushing an Okta group to Omni will **not** automatically provision accounts for users who are group members. You'll need to use the **Assignments** tab to assign the group to the users. Refer to the [Okta SAML setup guide](/administration/authentication/okta/saml) for more information.

## Steps

<Note>
  Omni users created via SCIM will have **Organization Member** permissions. Organization Admins must be created in **Settings > Users** or have their permissions [manually upgraded](/administration/users/permissions).
</Note>

<Steps>
  <Step title="Create an Omni API key">
    1. Follow [these steps](/api/authentication) to create a new API key named **Okta SCIM**.
    2. Copy the key somewhere handy - you'll need it to complete the setup.
  </Step>

  <Step title="Configure the Omni Okta application">
    <Note>
      This guide assumes that you have an existing Omni application in Okta. If you don't, make sure you've finished setting up [Okta SAML authentication](/administration/authentication/okta/saml) before continuing.
    </Note>

    1. Log in to the Okta Admin console.
    2. Navigate to the Omni application.
    3. Click the **Provisioning** tab.
    4. In the **Integration** tab, click the **Configure API Integration** button.
    5. Check the **Enable API Integration** box.
    6. In the **API Token** field, paste your Omni API key: <img />
    7. Click **Test credentials** to verify the setup.
  </Step>

  <Step title="Set up provisioning and user attribute updates">
    If the API credential test is successful, additional options will display in the application's **Provisioning** tab.

    1. In the **Provisioning** tab, click the **To app** option. Then:
    2. Click the **Edit** link to the right of the **Provisioning to app** heading.
    3. Check the **Enable** boxes for **Create users**, **Deactivate users**, and **Update user attributes**.
    4. Click **Save**.
    5. Navigate to the **Sign on** tab. Then:
    6. Locate the **Credentials details** section.
    7. Set the **Application username format** to **Email**. To change this setting, click the **Edit** link near the top of the tab: <img />
    8. Click **Save** when finished.

    After provisioning is set up, [users that have the Omni application assigned to them in Okta](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm) will be provisioned in Omni. This process may take a few minutes to complete.
  </Step>

  <Step title="Configure Omni provisioning settings">
    In Omni:

    1. Navigate to **Settings > Authentication**.
    2. Enable **Automatically provision new users on first login from this SAML provider**.
    3. Click **Save SAML changes**.

    This setting ensures that users assigned to the Omni app in Okta are automatically created in Omni when they first log in via SAML.
  </Step>

  <Step title="Enable user group provisioning in Okta">
    <Note>
      Pushing an Okta group to Omni will **not** automatically provision accounts for users who are group members. You'll need to use the **Assignments** tab to assign the group to the users. Refer to the [Okta SAML setup guide](/administration/authentication/okta/saml) for more information.
    </Note>

    This step enables Okta's **Push groups** functionality, which allows you to push your Okta user groups to Omni.

    1. In the Omni application, navigate to the **Push Groups** tab.
    2. Click the **Push Groups** button, then select **Find groups by name**: <img />
    3. Use the search field to find and select an Okta group to push to Omni.
    4. Click **Save**.

    Once pushed, Omni will begin provisioning the user group. This process may take a few minutes to complete.
  </Step>
</Steps>

**Note**: when users are removed from Okta they will be automatically de-provisioned and revoked in Omni which has implications for the schedules and content they own. See the [Revoke Membership](/administration/users/delete) page for more details.

## What's next?

After you finish setting up SCIM, you can go a step further and sync your custom user attributes from Okta to Omni.

Refer to the [Syncing Okta user attributes guide](/administration/authentication/okta/user-attributes) for more information.


# Syncing Okta user attributes to Omni with SCIM
Source: https://docs.omni.co/administration/authentication/okta/user-attributes

Sync user attributes from Okta to Omni via SCIM.

Custom user attributes can be synced from Okta to Omni, allowing you to fully centralize your user management in Okta.

In this guide, we'll demonstrate how to sync a user attribute named `blob_entity` from Okta to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **To set up SCIM provisioning with Okta**. Refer to the [Omni Okta SCIM guide](/administration/authentication/okta/scim) for more information.
* **Organization Admin** permissions in Omni
* **Permissions in Okta** that allow you to:
  * Access the Admin console
  * Create user profile attributes
  * Define user profile attribute values
  * Modify applications

## Limitations

Omni [system user attributes](/administration/users/attributes#default-system-user-attributes) are read-only and cannot be assigned via SCIM.

## Setup

<Steps>
  <Step title="Create an Omni user attribute">
    In Omni, navigate to **Settings > Attributes** and [create a new attribute](/administration/users/attributes).

    Our example attribute, `blob_entity`, has the following settings:

    * **Name** - `Blob Entity`
    * **Reference** - `blob_entity`
    * **Type** - `string`

      <img alt="" />
  </Step>

  <Step title="Create & define an Okta user profile attribute">
    Click the dropdowns to display instructions for each step.

    <Accordion title="2.1. Create the attribute">
      <Tip>
        **Passing a default Okta attribute?**

        Creating an attribute is required **only** if the attribute you want to pass to Omni doesn't exist in [Okta's default user attributes](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/createUser!path=profile\&t=request), such as `name` or `city`.
      </Tip>

      1. Log in to your Okta Admin console.

      2. Navigate to **Directory > Profile Editor**.

      3. Click the **User (default)** option.

      4. Click the **Add Attribute** button.

      5. Fill in the attribute fields as follows:

         * **Data type** - Select the **Type** the attribute has in Omni. For example, if the attribute has a **Type** of `string` in Omni, you'd select `string`.
         * **Display name** - Enter a name for the attribute.
         * **Variable name** - Enter the **Reference** for the attribute in Omni. In our example, this would be `blob_entity`.
         * **Enum** - If the Omni attribute can have multiple values, check this box and use the fields that display to add the possible values.

      6. Omni doesn't require a specific configuration for the remaining fields; feel free to define them as needed.

      7. When finished, click **Save**.

         <img alt="" />
    </Accordion>

    <Accordion title="2.2. Define attribute values">
      After you create the attribute, **open the profile of each user assigned to the Omni application** and define a value for the attribute. Refer to the [Okta documentation](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-edit-user-attributes.htm) if you need a refresher on how to do this.

      <img alt="" />
    </Accordion>
  </Step>

  <Step title="Create an Omni application attribute">
    1. In Okta, navigate to **Directory > Profile Editor**.

    2. Click the **Omni application**.

    3. Click **Add Attribute**.

    4. Fill in the attribute fields as follows:

       * **Data type** - Select the **Type** the attribute has in Omni. For example, if the attribute has a **Type** of `string` in Omni, you'd select `string`.
       * **Display name** - Enter a name for the attribute.
       * **Variable name** - Enter the **Reference** for the attribute in Omni. In our example, this would be `blob_entity`.
       * **External name** - This will auto-populate based on the **Variable name**
       * **External namespace** - Copy and paste the following into this field:
         ```txt theme={null}
         urn:omni:params:1.0:UserAttribute
         ```
         **This value must be this exact string - don't change the `UserAttribute`.**
       * **Enum** - If the Omni attribute can have multiple values, check this box and use the fields that display to add the possible values.

    5. Click **Save**.

       <img alt="" />
  </Step>

  <Step title="Map the user & application attributes">
    The last step is to map the Okta profile attribute to the Omni application attribute.

    1. In the profile editor for the Omni application, click the **Mappings** button:

       <img alt="" />

    2. In the dialog that displays, toggle the view to **Okta User to Omni Analytics**:

       <img alt="" />

    3. Use the dropdowns to map the attributes to each other. In our example, the `user.blobEntity` attribute on the **Omni user profile** side is mapped to the `blobEntity` attribute on the **Omni Analytics User Profile** side.

    4. Use the **arrows** in the middle of the dialog to set the attribute to **Apply mapping on user create and update**:

       <img alt="" />

    5. When finished, click **Save Mappings**.
  </Step>
</Steps>

## What's next?

At this point, there are two things left:

* **Syncing the attributes to Omni**. You can do this by:

  * **Waiting for Okta to perform the next automatic sync**, or
  * **Forcing a manual sync**. Open the Okta Omni application, click the **Provisioning** tab, and scroll down to the **Attributes** section. Click the **Force Sync** button to trigger a sync.

* **Defining attribute values**. When you do this, use the **user profile attribute** you created in Okta in step 2. The mapping between this attribute and the one in the Okta Omni application will allow the value to flow through to your Omni instance.

  If you need a refresher on how to do this, refer to the [Okta documentation](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-edit-user-attributes.htm).


# Rippling authentication
Source: https://docs.omni.co/administration/authentication/rippling/index

Connect Omni to Rippling for secure SAML single sign-on and automated user provisioning.

You can connect Omni to Rippling to manage authentication and user access through your organization’s existing identity provider.

Rippling supports **SAML** for single sign-on and **SCIM** for automated user provisioning.

## Integration overview

Connecting Rippling to Omni allows you to:

1. **Authenticate users** through Rippling using SAML.
2. **Control when and how users are provisioned** in Omni.

### User provisioning options

Omni supports two approaches for provisioning users:

| Option                       | How it works                                                         | When to use                                                                                      |
| ---------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **SCIM provisioning**        | Users are created in Omni when assigned to the Omni app in Rippling. | You want users provisioned immediately upon assignment, regardless of whether they've logged in. |
| **First-login provisioning** | Users are created in Omni only when they first log in via SAML.      | You want to control seat usage by provisioning users only when they actually access Omni.        |

You can use first-login provisioning with or without SCIM. Refer to the [SAML setup guide](/administration/authentication/rippling/saml) for more details.

## Getting started

Follow these steps to get set up.

You can complete SAML only, or add SCIM and attribute sync for a fully automated experience.

| Step | Description                                                                                 | Link                                                         |
| ---- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 1    | **Set up SAML SSO** to let users sign in to Omni with their Rippling credentials.           | [SAML setup →](/administration/authentication/rippling/saml) |
| 2    | **Enable SCIM provisioning** to automatically create, update, and deactivate users in Omni. | [SCIM setup →](/administration/authentication/rippling/scim) |

## Notes and troubleshooting

* **Admin access required:** You’ll need Rippling admin permissions to configure SAML and SCIM.
* **Test before rollout:** Try SSO with a test user before enabling it organization-wide.

If you run into issues, check your Rippling app configuration or see [Omni's troubleshooting SSO guide](/administration/authentication/troubleshooting).

## Related

* [Omni SAML configuration overview](/administration/authentication)
* [Managing users and groups in Omni](/administration/users)
* [Rippling documentation](https://\[idp-docs-link]/)


# Configuring Rippling SAML SSO
Source: https://docs.omni.co/administration/authentication/rippling/saml

Integrate Omni with Rippling for user authentication via the SAML protocol.

## Requirements

To follow the steps in this guide, you'll need:

* Omni [Organization Admin permissions](/administration/users/permissions)
* Permissions in Rippling that allow you to:
  * Create custom apps
  * Assign users & groups to apps

## Setup

<Tip>
  Open Omni's SAML settings and Rippling in separate browser tabs, as you will need to copy and paste values between the two applications to complete the setup.
</Tip>

<Steps>
  <Step title="Open the Omni authentication settings">
    In your Omni instance, navigate to **Settings > Authentication** and locate the **SAML** section.
  </Step>

  <Step title="Create an Omni Rippling app">
    1. Sign into Rippling.
    2. Search for `Custom app` in the search bar.
    3. Select **Create new Custom app**.
    4. Complete the app form:
       * **Name** - `Omni`
       * **Categories** - `Analytics & BI`
       * Upload the following logo:

         <Frame>
           <img alt="Omni logo" />
         </Frame>
    5. Select **Single Sign-on (SAML)**, or **SAML and SCIM app** if you intend to also configure SCIM.
    6. Complete the single sign-on setup form:
       * Leave the **Metadata URL** and **Metadata** fields empty.
       * **ACS URL (Assertion Consumer Service URL)** - Copy and paste the **Single sign-on URL** value from the Omni Authentication settings (step 1)
       * **Service Provider Entity ID** - Enter the full hostname of your Omni instance, e.g. `blobsrus.omniapp.co`. Do not include `https://`.
    7. Leave this form open, but note the following - you'll need it in the next step:
       * **Single Sign-on URL**
       * **Issuer**
       * **X509 Certificate**
  </Step>

  <Step title="Configure Omni authentication settings">
    Navigate back to the Omni Authentication settings (**Settings > Authentication**) to complete the setup:

    * **Display Name** - Enter a name to customize the login button, for example `Rippling`. Leave blank to show the default **Log in with SAML** button.

    * **Entity ID / Issuer** - Copy and paste the **Issuer** value from Rippling

    * **Single Sign-on URL** - Copy and paste the **Single Sign-on URL** value from Rippling

    * **Certificate** - Copy and paste the contents of the **X509 Certificate** certificate. You may need to download it from Rippling.

      The certificate must include `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` values, for example:

      ```txt wrap theme={null}
      -----BEGIN CERTIFICATE-----
      [certificate contents]
      -----END CERTIFICATE-----
      ```

    * **Automatically provision new users on first login from this SAML provider** - Toggle this setting to **on** if:

      * You want to provision users only when they first access Omni **and**
      * You don't plan to set up SCIM provisioning

    * **Enable SAML for users** - Toggle this setting to **on**

    When finished, click **Save SAML changes**.
  </Step>

  <Step title="Complete the SSO configuration in Rippling">
    Navigate back to Rippling to finish configuring the custom Omni app:

    1. On the setup form, click **Continue**.
    2. Select **Do not allow admins to sign in to the admin account**.
    3. Skip creating any group attributes.
    4. In the app's **Settings** tab, navigate to the **SAML Attributes** section.
    5. Create the following **global attributes**:

       | Name         | Value                       |
       | ------------ | --------------------------- |
       | `first_name` | User's preferred first name |
       | `last_name`  | User's preferred last name  |

    <Note>
      Clicking the **Test now** button at this point will yield an error, as Rippling initially sets the SAML SSO as IdP-initiated. You will change this to SP-initiated in the next step.
    </Note>
  </Step>

  <Step title="Configure service provider (SP) initiated flow">
    1. In the Custom app's **Settings > Advanced SAML Settings**, enable **Application only supports login initiated from the application, also referred to as SP initiated flow**.
    2. In **URL to trigger SP-initiated flow**, enter the URL of your Omni instance, e.g. `https://blobsrus.omniapp.co/`.
  </Step>

  <Step title="Assign users and groups">
    In Rippling, assign users and user groups to the custom Omni application.
  </Step>

  <Step title="Test the setup">
    Test your SAML setup by logging out of Omni. On the Omni login page, you should see a login button. Click the button to log in using SAML.

    <Tip>
      By default, the login button will read **Log in with SAML**. Set a **Display Name** in the [Omni authentication settings](#omni-auth-settings) to customize this text.
    </Tip>

    If the setup is successful, finish the setup by rolling out SAML authentication to the rest of your organization.
  </Step>
</Steps>

## What's next?

Setting up SAML allows your users to authenticate to Omni using their Rippling credentials. With this setup completed, you can also [configure SCIM to auto-provision users & user groups in Omni](/administration/authentication/rippling/scim).


# Auto-provisioning Omni users with Rippling SCIM
Source: https://docs.omni.co/administration/authentication/rippling/scim

Automatically manage Omni accounts for your users with Rippling SCIM provisioning.

When SCIM (System for Cross-domain Identity Management) is enabled, you can automatically provision and de-provision Omni accounts for your users and synchronize Omni user groups with groups in Rippling.

You can integrate Rippling's provisioning capability with Omni to create accounts for your users and synchronize Omni groups with attributes in Rippling. All users created via SCIM will be organization Members, organization Admins can only be created or converted from Member level in the UI.

## Requirements

To follow the steps in this guide, you'll need:

* **To have Rippling SAML authentication set up**. If you don't, refer to the [Rippling SAML authentication setup guide](/administration/authentication/rippling/saml) before proceeding.
* **Omni Organization Admin permissions**
* **Permissions in Rippling that allow you to** modify applications

## Limitations

Only Rippling's `displayName` user attribute can be synced to Omni.

## Setup

<Note>
  Omni users created via SCIM will have **Organization Member** permissions. Organization Admins must be created in **Settings > Users** or have their permissions [manually upgraded](/administration/users/permissions).
</Note>

<Steps>
  <Step title="Create an Omni API key">
    1. Follow [these steps](/api/authentication) to create a new API key named **Rippling SCIM**.
    2. Copy the key somewhere handy - you'll need it to complete the setup.
  </Step>

  <Step title="Configure the Omni Rippling application">
    1. In a new browser tab, log into Rippling.
    2. Navigate to the Omni application. **Note**: If you don't have SAML set up already, complete the steps in the [Omni-Rippling SAML guide](/administration/authentication/rippling/saml) before proceeding.
    3. Navigate to the **SCIM configuration form** and fill in the following:
       * **SCIM version** - Set to `2.0`
       * Leave **Does not support One Way Sync** disabled
       * **SCIM base url** - Enter the URL you use to log into Omni, appended with `/api/scim/v2`.

         For example, if your Omni login URL is `https://blobsrus.omniapp.co`, you would enter `https://blobsrus.omniapp.co/api/scim/v2`.
       * **SCIM authorization method** - Set to `Bearer Token`
       * Enable **Supports groups**
       * **Supports Mutually Exclusive Groups** - Set to **Not Mutually Exclusive Groups**
       * Enable **Supports pagination** and **Create & Delete Groups**
       * Leave **Use PATCH to edit Groups** and **Generate temporary password** disabled
       * Select **Use email address as username**
       * **Supported SCIM attributes** - Set to `displayName`
    4. Click **Continue**.
  </Step>

  <Step title="Install the custom SCIM application">
    1. If prompted, select **I'm the Omni admin, I'll install it**.
    2. Ensure that **Offboarding** is enabled.
    3. In the **Bearer Token** field, paste the Omni API key you created in step 1.

       <Note>
         If Rippling doesn't prompt you to provide a Bearer token, you may need to re-install the custom app. Follow the **Modify App** link in the app's **Settings** tab to do this.
       </Note>
    4. Configure provisioning rules and match up existing user accounts and groups.
  </Step>

  <Step title="Configure Omni login settings">
    1. In Omni, navigate to **Settings > Authentication**.
    2. Enable **Automatically provision new users on first login from this SAML provider**. This ensures that users assigned to the Omni app in Rippling are automatically created in Omni when they first log in via SAML.
    3. Click **Save SAML changes**.
  </Step>
</Steps>

**Note**: when users are removed from your Rippling system they will be de-provisioned and revoked in Omni which has implications for the schedules and content they own. See the [Revoke Membership](/administration/users/delete) page for more details.


# SAML and SCIM troubleshooting
Source: https://docs.omni.co/administration/authentication/troubleshooting

Common issues and solutions for SAML and SCIM authentication in Omni.

<AccordionGroup>
  <Accordion title="Unable to process request due to missing initial state.">
    Omni does not support identity provider (IdP)-initiated SSO login for SAML, which means users can't log in by clicking a link in the IdP's dashboard. If they do attempt to log in this way, they'll receive an error similar to the following:

    ```txt wrap theme={null}
    Unable to process request due to missing initial state. This may happen if browser sessionStorage is inaccessible or accidentally cleared. Some specific scenarios are - 1) Using IDP-Initiated SAML SSO. 2) Using signInWithRedirect in a storage-partitioned browser environment.
    ```

    To resolve this, users must log into Omni by navigating to the Omni login page and clicking the **Log in with SAML button**.

    If your users are accustomed to logging in to applications directly from the IdP, most allow you to provide a link to the Omni login page as an app tile.
  </Accordion>
</AccordionGroup>


# Managing billing & invoices
Source: https://docs.omni.co/administration/billing

View your organization's Omni billing information & invoices.

The **Settings > General > Billing** tab allows you to view billing-related information for your organization, including past invoices and Omni's W9.

## Requirements

**Organization Admin** permissions are required to access the Billing page.

## Viewing invoices

The **Invoices** section of the **Billing** page lists the past invoices for your organization, beginning with the most recent:

<img alt="" />

## Billing contacts

In the event that Omni needs to contact you about billing or payment-related issues, we'll reach out to the person(s) specified in the **Billing** setting located in [**Settings > General > Contacts**](/administration/settings#contacts).


# Managing custom chart palettes
Source: https://docs.omni.co/administration/chart-palettes/custom

Create custom palettes with your company colors, ensuring your workbooks, charts, and dashboards are always consistent and on-brand.

## Requirements

**Organization Admin** permissions are required to create and modify custom color palettes.

## Creating custom chart palettes

1. Navigate to **Settings > Chart palettes.**

2. Click **Add**.

3. Customize by adding, editing and removing colors. Use the color picker control or select **Open hex code editor** and paste in a list of comma-separated hex codes:

   <img alt="Diagram showing the architecture of the system" />

4. When finished, click **Save**.

Once created, you can identify custom palettes using the asterisk (`*`) next to their name in the **Chart palettes** page:

<img alt="" />

Custom palettes will be listed in the chart editor palette picker in alphabetical order before any of the [built-in palettes](/administration/chart-palettes/omni).

## Editing custom chart palettes

1. Navigate to **Settings > Chart palettes**.
2. Click the <Icon icon="ellipsis-vertical" /> (three dots icon) next to a custom palette and select **Edit**.
3. Make your changes.
4. Click **Save** when finished. Existing charts that use the palette will be updated with the changes.

## Deleting custom palettes

<Note>
  If deleting the default palette, set a new [default palette](/administration/chart-palettes/default) first.
</Note>

1. Navigate to **Settings > Chart palettes**.
2. Click the <Icon icon="ellipsis-vertical" /> (three dots icon) next to a custom palette and select **Delete**.

Any existing charts using the palette will be updated to use the organization's default palette.


# Setting a default chart palette for your organization
Source: https://docs.omni.co/administration/chart-palettes/default

Set a default chart color palette for your Omni organization, applied automatically to new charts based on chart type and data.

The current default will have a blue <Badge>DEFAULT</Badge> badge next to its name:

<img alt="" />

## Requirements

**Organization Admin** permissions are required to set a default chart palette.

## Setting the default palette

To set a new default palette, click the <Icon icon="ellipsis-vertical" /> (three dots icon) next to the palette and select **Set as default**.

Existing charts that use the default color palette will be updated to the new default.

The default discrete and continuous palettes will also be available for use in [Apps](/visualize-present/apps/styling#charts).


# Managing chart palettes
Source: https://docs.omni.co/administration/chart-palettes/index

Predefined color palettes help you apply consistent colors across charts, workbooks, and dashboards.

Omni includes [several discrete and continuous palettes](/administration/chart-palettes/omni), and administrators can add custom ones for greater flexibility. Organization Admins can [set default palettes for the organization](/administration/chart-palettes/default) and optionally [create custom palettes](/administration/chart-palettes/custom).

## Requirements

**Organization Admin** permissions are required to create and modify custom color palettes in the **Settings > Chart palettes** page.

## Using palettes in visualizations

<Note>
  Chart palettes can only be used in X/Y style charts such as bar, scatter, line, etc.
</Note>

Chart palettes are currently only used for color faceting. You can access the chart palettes from the **Options** panel in the **Color > Options** popup. Any [custom palettes](/administration/chart-palettes/custom) created for the organization will appear in the list before the [built-in palettes](/administration/chart-palettes/omni).

For more on using palettes in visualizations, see the [Color by / Stacking documentation](/visualize-present/visualizations/configuration/color).

<img alt="" />


# Built-in palette color reference
Source: https://docs.omni.co/administration/chart-palettes/omni

The color values for the built-in palettes are provided as a reference for creating your own palette variations.

For all other palettes, refer to the [Vega Scheme Reference](https://vega.github.io/vega/docs/schemes/#scheme-reference).

<Tip>
  Click a **colored square** to copy the hex code for that color.

  Click the **Pastable hex codes** tabs in each palette section to copy the hex codes for all colors in the palette.
</Tip>

## Discrete palettes

### Basic

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="blue" />

      <Color.Item name="yellow" />

      <Color.Item name="pink" />

      <Color.Item name="teal" />

      <Color.Item name="orange" />

      <Color.Item name="green" />

      <Color.Item name="purple" />

      <Color.Item name="red" />

      <Color.Item name="olive" />

      <Color.Item name="magenta" />

      <Color.Item name="blue-light" />

      <Color.Item name="yellow-light" />

      <Color.Item name="pink-light" />

      <Color.Item name="teal-light" />

      <Color.Item name="orange-light" />

      <Color.Item name="green-light" />

      <Color.Item name="purple-light" />

      <Color.Item name="red-light" />

      <Color.Item name="olive-light" />

      <Color.Item name="magenta-light" />

      <Color.Item name="blue-dark" />

      <Color.Item name="yellow-dark" />

      <Color.Item name="pink-dark" />

      <Color.Item name="teal-dark" />

      <Color.Item name="orange-dark" />

      <Color.Item name="green-dark" />

      <Color.Item name="purple-dark" />

      <Color.Item name="red-dark" />

      <Color.Item name="olive-dark" />

      <Color.Item name="magenta-dark" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #298BE5, #F7B54E, #FF6291, #1DB9B9, #FF8515, #3D923B, #4D59E2, #E43030, #97A345, #BE43C0,
    #94C5F7, #F6E692, #FF9EC8, #96F1F3, #FFC28A, #97D087, #A5ABF8, #F08A8A, #C1CA82, #DFA3E0,
    #025DB1, #D7870A, #E11955, #1C8787, #B85800, #296228, #2530B6, #AB1616, #6E7632, #752877
    ```
  </Tab>
</Tabs>

### Pairs

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="yellow-1" />

      <Color.Item name="yellow-2" />

      <Color.Item name="pink-1" />

      <Color.Item name="pink-2" />

      <Color.Item name="teal-1" />

      <Color.Item name="teal-2" />

      <Color.Item name="orange-1" />

      <Color.Item name="orange-2" />

      <Color.Item name="green-1" />

      <Color.Item name="green-2" />

      <Color.Item name="purple-1" />

      <Color.Item name="purple-2" />

      <Color.Item name="red-1" />

      <Color.Item name="red-2" />

      <Color.Item name="olive-1" />

      <Color.Item name="olive-2" />

      <Color.Item name="magenta-1" />

      <Color.Item name="magenta-2" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #94C5F7, #298BE5, #F6E692, #F7B54E, #FF9EC8, #FF6291, #96F1F3, #1DB9B9, #FFC28A, #FF8515,
    #97D087, #3D923B, #A5ABF8, #4D59E2, #F08A8A, #E43030, #C1CA82, #97A345, #DFA3E0, #BE43C0
    ```
  </Tab>
</Tabs>

### Threes

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="blue-3" />

      <Color.Item name="yellow-1" />

      <Color.Item name="yellow-2" />

      <Color.Item name="yellow-3" />

      <Color.Item name="pink-1" />

      <Color.Item name="pink-2" />

      <Color.Item name="pink-3" />

      <Color.Item name="teal-1" />

      <Color.Item name="teal-2" />

      <Color.Item name="teal-3" />

      <Color.Item name="orange-1" />

      <Color.Item name="orange-2" />

      <Color.Item name="orange-3" />

      <Color.Item name="green-1" />

      <Color.Item name="green-2" />

      <Color.Item name="green-3" />

      <Color.Item name="purple-1" />

      <Color.Item name="purple-2" />

      <Color.Item name="purple-3" />

      <Color.Item name="red-1" />

      <Color.Item name="red-2" />

      <Color.Item name="red-3" />

      <Color.Item name="olive-1" />

      <Color.Item name="olive-2" />

      <Color.Item name="olive-3" />

      <Color.Item name="magenta-1" />

      <Color.Item name="magenta-2" />

      <Color.Item name="magenta-3" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #94C5F7, #298BE5, #025DB1, #F6E692, #F7B54E, #D7870A, #FF9EC8, #FF6291, #E11955, #96F1F3,
    #1DB9B9, #1C8787, #FFC28A, #FF8515, #B85800, #97D087, #3D923B, #296228, #A5ABF8, #4D59E2,
    #2530B6, #F08A8A, #E43030, #AB1616, #C1CA82, #97A345, #6E7632, #DFA3E0, #BE43C0, #752877
    ```
  </Tab>
</Tabs>

### Fours

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="blue-3" />

      <Color.Item name="blue-4" />

      <Color.Item name="green-1" />

      <Color.Item name="green-2" />

      <Color.Item name="green-3" />

      <Color.Item name="green-4" />

      <Color.Item name="magenta-1" />

      <Color.Item name="magenta-2" />

      <Color.Item name="magenta-3" />

      <Color.Item name="magenta-4" />

      <Color.Item name="teal-1" />

      <Color.Item name="teal-2" />

      <Color.Item name="teal-3" />

      <Color.Item name="teal-4" />

      <Color.Item name="pink-1" />

      <Color.Item name="pink-2" />

      <Color.Item name="pink-3" />

      <Color.Item name="pink-4" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #94C5F7, #298BE5, #025DB1, #013A6F, #97D087, #3D923B, #296228, #183A17, #DFA3E0, #BE43C0,
    #752877, #4B1A4C, #96F1F3, #1DB9B9, #1C8787, #135D5D, #FF9EC8, #FF6291, #E11955, #971139
    ```
  </Tab>
</Tabs>

### Ordered

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="teal" />

      <Color.Item name="blue" />

      <Color.Item name="purple" />

      <Color.Item name="magenta" />

      <Color.Item name="pink" />

      <Color.Item name="red" />

      <Color.Item name="orange" />

      <Color.Item name="yellow" />

      <Color.Item name="olive" />

      <Color.Item name="green" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #1DB9B9, #298BE5, #4D59E2, #BE43C0, #FF6291, #E43030, #FF8515, #F7B54E, #9BA345, #3D923B
    ```
  </Tab>
</Tabs>

### Ordered Pairs

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="teal-1" />

      <Color.Item name="teal-2" />

      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="purple-1" />

      <Color.Item name="purple-2" />

      <Color.Item name="magenta-1" />

      <Color.Item name="magenta-2" />

      <Color.Item name="pink-1" />

      <Color.Item name="pink-2" />

      <Color.Item name="red-1" />

      <Color.Item name="red-2" />

      <Color.Item name="orange-1" />

      <Color.Item name="orange-2" />

      <Color.Item name="yellow-1" />

      <Color.Item name="yellow-2" />

      <Color.Item name="olive-1" />

      <Color.Item name="olive-2" />

      <Color.Item name="green-1" />

      <Color.Item name="green-2" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #96F1F3, #1DB9B9, #94C5F7, #298BE5, #A5ABF8, #4D59E2, #DFA3E0, #BE43C0, #FF9EC8, #FF6291,
    #F08A8A, #E43030, #FFC28A, #FF8515, #F6E692, #F7B54E, #CBD397, #9BA345, #97D087, #3D923B
    ```
  </Tab>
</Tabs>

### Ordered Threes

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="teal-1" />

      <Color.Item name="teal-2" />

      <Color.Item name="teal-3" />

      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="blue-3" />

      <Color.Item name="purple-1" />

      <Color.Item name="purple-2" />

      <Color.Item name="purple-3" />

      <Color.Item name="magenta-1" />

      <Color.Item name="magenta-2" />

      <Color.Item name="magenta-3" />

      <Color.Item name="pink-1" />

      <Color.Item name="pink-2" />

      <Color.Item name="pink-3" />

      <Color.Item name="red-1" />

      <Color.Item name="red-2" />

      <Color.Item name="red-3" />

      <Color.Item name="orange-1" />

      <Color.Item name="orange-2" />

      <Color.Item name="orange-3" />

      <Color.Item name="yellow-1" />

      <Color.Item name="yellow-2" />

      <Color.Item name="yellow-3" />

      <Color.Item name="olive-1" />

      <Color.Item name="olive-2" />

      <Color.Item name="olive-3" />

      <Color.Item name="green-1" />

      <Color.Item name="green-2" />

      <Color.Item name="green-3" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #96F1F3, #1DB9B9, #1C8787, #94C5F7, #298BE5, #025DB1, #A5ABF8, #4D59E2, #2530B6, #DFA3E0,
    #BE43C0, #752877, #FF9EC8, #FF6291, #E11955, #F08A8A, #E43030, #AB1616, #FFC28A, #FF8515,
    #B85800, #F6E692, #F7B54E, #D7870A, #C1CA82, #97A345, #6E7632, #97D087, #3D923B, #296228
    ```
  </Tab>
</Tabs>

### Ordered Fours

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="teal-1" />

      <Color.Item name="teal-2" />

      <Color.Item name="teal-3" />

      <Color.Item name="teal-4" />

      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="blue-3" />

      <Color.Item name="blue-4" />

      <Color.Item name="magenta-1" />

      <Color.Item name="magenta-2" />

      <Color.Item name="magenta-3" />

      <Color.Item name="magenta-4" />

      <Color.Item name="pink-1" />

      <Color.Item name="pink-2" />

      <Color.Item name="pink-3" />

      <Color.Item name="pink-4" />

      <Color.Item name="green-1" />

      <Color.Item name="green-2" />

      <Color.Item name="green-3" />

      <Color.Item name="green-4" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #96F1F3, #1DB9B9, #1C8787, #135D5D, #94C5F7, #298BE5, #025DB1, #013A6F, #DFA3E0, #BE43C0,
    #752877, #4B1A4C, #FF9EC8, #FF6291, #E11955, #971139, #97D087, #3D923B, #296228, #183A17
    ```
  </Tab>
</Tabs>

### Red Green

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="red" />

      <Color.Item name="green" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #E43030, #3D923B
    ```
  </Tab>
</Tabs>

### Red Yellow Green

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="red" />

      <Color.Item name="yellow" />

      <Color.Item name="green" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #E43030, #F7B54E, #3D923B
    ```
  </Tab>
</Tabs>

## Continuous palettes

### Basic Blues

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="blue-1" />

      <Color.Item name="blue-2" />

      <Color.Item name="blue-3" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #D6E9FA, #298BE5, #013A6F
    ```
  </Tab>
</Tabs>

### Basic Greens

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="green-1" />

      <Color.Item name="green-2" />

      <Color.Item name="green-3" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #D6ECCF, #3D923B, #183A17
    ```
  </Tab>
</Tabs>

### Basic Red Yellow Green

<Tabs>
  <Tab title="Colors">
    <Color>
      <Color.Item name="red" />

      <Color.Item name="yellow" />

      <Color.Item name="green" />
    </Color>
  </Tab>

  <Tab title="Pastable hex codes">
    ```
    #E43030, #F6E692, #3D923B
    ```
  </Tab>
</Tabs>


# Content permission settings
Source: https://docs.omni.co/administration/content-permissions

Manage the default content permissions for your organization in **Settings > Content permissions**.

<Note>
  **Organization Admin** permissions are required to access and modify organization-level content permissions.
</Note>

## Default content access

Defines the default user role that all users will have for content (documents and folders) they have access to. Users can be granted additional permissions at the document or folder level - this setting only defines a default base role.

<Note>
  For individual documents, users with **Manager** or **Owner** content roles have the ability to set the organization access role higher or lower than the default role defined in this setting.
</Note>

## Default document abilities

Defines default abilities for all documents in the organization. These settings control the abilities users can select in documents:

| Ability                                                                                                             | Description                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Upload data](/analyze-explore/data-input-csvs)                                                                     | Allow users to upload data (CSV, Excel, etc.) to this document. Requires the user to have a [model role][model-role] that allows uploading data.                                                                                                                                                              |
| [Schedules](/share)                                                                                                 | Allow the creation of new deliveries and alerts on this document. Requires the user to have a [model role][model-role] that allows scheduling. Disabling will not remove existing deliveries or alerts.                                                                                                       |
| **Download**                                                                                                        | Allow users to download the document's [data](/analyze-explore/point-click-queries#downloading-results) and [dashboard](/visualize-present/dashboards/download). Requires the user to have a [model role][model-role] that allows downloading.                                                                |
| [Create spreadsheets](/analyze-explore/spreadsheet-tabs)                                                            | Allow users to create spreadsheets.                                                                                                                                                                                                                                                                           |
| **Drill**                                                                                                           | Allow users to drill into various data points in this content.                                                                                                                                                                                                                                                |
| **Duplicate**                                                                                                       | Allow users to duplicate the document. Disabling prevents users from creating a copy of the dashboard or workbook, or [copying individual tabs into another workbook](/analyze-explore/workbook-basics#copy-a-tab-to-an-existing-workbook). **Note**: Reach out to Omni support to have this feature enabled. |
| **Viewers can see workbook**                                                                                        | Allow users with the **Viewer** content role and a connection role with the **Use workbooks** ability to see a read-only version of the workbook. They will not be able to edit the workbook or see non-topic tabs or SQL tabs. AccessBoost does not apply to workbooks at this time.                         |
| [Request access](/share/#requesting-document-access)                                                                | Allow users who do not have access to this document to request access from the document owner.                                                                                                                                                                                                                |
| [Require pull request to publish](/content/develop/branch-mode#requiring-pull-requests-to-publish-document-changes) | Require users to publish changes to this document through a pull request                                                                                                                                                                                                                                      |
| [Chat with Content](/ai/dashboard-assistant)                                                                        | Allow users to use Chat with Content on the published version of the document. Requires AI data reading permissions to be enabled at the organization level and the user to have a [model role][model-role] that allows AI use.                                                                               |
| **Timezone override**                                                                                               | Allow users to change the query timezone for this document. See [Enabling timezone selection on documents](/visualize-present/dashboards/timezone-override) for more information.                                                                                                                             |

## Content creation: Shared "root" is open

Allows users to add documents and folders to the root of your organization's [**Hub**](/content/navigate) (shared folder). Otherwise, users will be able to create content in folders they have specifically been granted access to.

## AccessBoost

Enables permission boosting, which will ignore a user's database connection role. If **Non-administrators can enable AccessBoost on content** is also enabled, users with SQL editing permissions and embed users can also enable AccessBoost on documents.

Refer to the [Sharing content guide](/share#boosting-permissions-with-accessboost) for more information about AccessBoost, including its security implications.

## Delivery personalization

Controls whether users can personalize email deliveries with recipient user attributes. This setting determines the availability of the **Personalize delivery with the recipient's user attributes** checkbox in the [email delivery dialog](/share/deliveries/email#email-settings).

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>

      <th>
        Affects existing deliveries? <Tooltip><Icon icon="info-circle" /></Tooltip>
      </th>

      <th>
        Delivery setting availability <Tooltip><Icon icon="info-circle" /></Tooltip>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Configurable**</td>
      <td>Users can choose whether to personalize each delivery</td>
      <td><XCircleIcon /> **No**</td>
      <td><CheckIcon /> **Available**</td>
    </tr>

    <tr>
      <td>**Always**</td>

      <td>
        Forces personalization on for all email deliveries and automatically updates existing deliveries to use the recipient's user attributes.<br /><br />

        **This option can't be used if any connection in your Omni organization uses [per-user OAuth](/connect-data/oauth)**. If your organization has OAuth connections, you'll receive an error when you try to select this option.
      </td>

      <td><CheckIcon /> **Yes**</td>
      <td><XCircleIcon /> **Removed**</td>
    </tr>

    <tr>
      <td>**Never**</td>

      <td>
        Forces personalization off for all email deliveries and automatically updates existing deliveries to use the delivery owner's user attributes.
      </td>

      <td><CheckIcon /> **Yes**</td>
      <td><XCircleIcon /> **Removed**</td>
    </tr>
  </tbody>
</table>

<Warning>
  Switching to **Always** or **Never** will update every existing email delivery in the organization to match. Switching back to **Configurable** later leaves those deliveries as they are - it doesn't restore the per-delivery choices they had before, and each delivery will have to be set manually. You'll be prompted to confirm the switch.

  All delivery personalization mode changes are recorded in the organization's [audit log](/administration/audit-logs/event-types).
</Warning>

## Verification

Controls whether visual indicators appear in workbooks to distinguish between verified model fields and unverified workbook-specific fields (custom fields and formulas).

When **Show verification indicators** is enabled, workbook users will see indicator icons next to unverified fields in the field browser, data table headers, and visualization configurations. This helps users understand which fields come from the organization's verified (shared) data model and which are custom workbook fields.

For more details, see [Identifying workbook-only fields](/analyze-explore/point-click-queries#identifying-workbook-only-fields).

[model-role]: /administration/users/custom-roles "model role"


# Omni administration
Source: https://docs.omni.co/administration/index

Manage users, security, billing, and more in your Omni instance

As an Omni Organization Admin, you're responsible for managing your organization's users, permissions, security settings, and more. Use this section of the docs to get started with common administration tasks.

## Get started

<Columns>
  <Card title="Manage users" href="/administration/users" icon="users">
    Add, remove, and manage users in your organization
  </Card>

  <Card title="Assign permissions" href="/administration/users/permissions" icon="user-shield">
    Control what users can see and do in Omni
  </Card>

  <Card title="Organization settings" href="/administration/settings" icon="gear">
    Configure organization-wide settings and preferences
  </Card>
</Columns>

## Security and authentication

<Columns>
  <Card title="Set up SSO" href="/administration/authentication" icon="key">
    Configure single sign-on with Google, Okta, Rippling, or Microsoft Entra
  </Card>

  <Card title="Configure OpenID Connect" href="/administration/authentication/oidc" icon="key">
    Configure OAuth using the OIDC protocol
  </Card>

  <Card title="Security overview" href="/administration/security" icon="shield">
    Learn about Omni's security practices and compliance
  </Card>
</Columns>

## Monitor and manage

<Columns>
  <Card title="Usage analytics" href="/administration/analytics" icon="chart-line">
    Track how your organization uses Omni
  </Card>

  <Card title="Billing" href="/administration/billing" icon="credit-card">
    Manage your subscription and billing details
  </Card>
</Columns>


# Localization settings
Source: https://docs.omni.co/administration/localization

Configure language settings at the organization and user levels.

Localization settings control the language used for the Omni app interface. You can configure a default locale for your entire organization and, optionally, override it for individual users.

## Requirements

To use localization, you'll need:

* **Organization Admin permissions**, which are required to access and modify organization settings

## Organization-level localization

Organization-level localization is managed in **Settings > General**.

### Locale

The **Locale** setting defines the default language used for the Omni app interface across your organization.

* Changes to the locale update the language of the app UI for users who don't have a user-specific locale set.
* This setting is applied at the organization level and affects all users by default.

Omni currently supports the following locales:

| Locale code | Language                      |
| ----------- | ----------------------------- |
| `en-US`     | English (default)             |
| `ar-SA`     | العربية (السعودية) (Arabic)   |
| `de-DE`     | Deutsch (Deutschland)         |
| `es-CL`     | Español (Chile)               |
| `es-ES`     | Español (España)              |
| `fr-FR`     | Français (France)             |
| `he-IL`     | עברית (ישראל)                 |
| `it-IT`     | Italiano (Italia)             |
| `ja-JP`     | 日本語 (日本)                      |
| `ko-KR`     | 한국어 (대한민국) (Korean)           |
| `nb-NO`     | Norsk bokmål (Norge)          |
| `pt-BR`     | Português (Brasil)            |
| `pt-PT`     | Português (Portugal)          |
| `sv-SE`     | Svenska (Sverige)             |
| `th-TH`     | ไทย (ประเทศไทย) (Thai)        |
| `vi-VN`     | Tiếng Việt (Việt Nam)         |
| `zh-CN`     | 中文 (中国) (Simplified Chinese ) |

### Allowed locales

The **Allowed locales** setting defines which locales are available for use in your Omni instance.

* Only locales in this list will be available when selecting a locale for users.
* Use this setting to limit the languages that appear as options for your organization (for example, if you only support a subset of languages internally).

## User-level localization

You can override the organization-level locale for specific users in **Settings > Users**.

To set a user-specific locale:

1. Navigate to **Settings > Users**.
2. Find the user you want to update and click **Manage**.
3. On the user's settings page, choose a value in the **Locale** field.
4. Save your changes.

Users can also set their own locale in their [user profiles](/administration/users/your-account) by clicking **their avatar > Manage account**.

When a user has a locale set on their profile:

* The user-level **Locale** controls the language of the app interface for that user.
* If no user-level locale is set, the user inherits the organization-level **Locale**.

This lets you support users who need to work in different languages within the same Omni organization.

## Embedded users

For embedded Omni experiences, you can pass a `locale` user attribute in the embed configuration to control the interface language for embed users.

When provided, this attribute behaves like a user-level locale:

* If the `locale` attribute matches one of your **Allowed locales**, it will be used for that embedded user.
* If the attribute is missing or does not match an allowed locale, the user falls back to the organization-level **Locale**.


# Canceling long-running and hanging queries
Source: https://docs.omni.co/administration/running-queries

Stop queries that hang or run longer than expected, saving your database resources.

Queries that run longer than expected, or that hang entirely, can consume database resources and leave dashboards stuck loading. Omni gives you two ways to stop them:

* On the dashboard where the queries are running
* From the **Settings > Running queries** page, where you can cancel queries across multiple documents and, if you're an Organization Admin, queries by other users

## Stopping queries on a dashboard

While viewing a dashboard, you can stop running queries without leaving the page by:

* Clicking **View > Stop queries**. This item will be disabled when no queries are running.
* Clicking the <Icon icon="stop" /> **(stop) icon in the footer** while a run is in flight. This displays next to the <Icon icon="download" /> (download) and <Icon icon="paper-plane" /> (schedule) icons.

This will stop all running queries on the dashboard. Additionally, [auto-refresh](/visualize-present/dashboards/settings#auto-refresh) will be disabled until you reload the page.

<Tip>
  Use the [dashboard performance profiler](/visualize-present/dashboards/performance-profiler) to help optimize dashboard queries.
</Tip>

## Stopping queries from Settings

The **Settings > Running queries** page is useful when you need to cancel queries across multiple documents. Organization Admins will see all users' queries, while all other users will only see their own queries.

You can stop a specific query by clicking its **Cancel** button. To cancel multiple queries, select the checkboxes next to the queries and then click **Cancel selected queries**.

## Next steps

* Identify inefficient queries with the [Dashboard performance profiler](/visualize-present/dashboards/performance-profiler)
* Use [caching](/analyze-explore/performance/caching) to improve query performance
* Optimize queries with [aggregate awareness](/analyze-explore/performance/aggregate-awareness)


# Omni supported cloud regions
Source: https://docs.omni.co/administration/security/cloud-regions

Select a cloud region for your Omni instance, which determines where customer content will be stored and processed.

Omni uses Amazon Web Services (AWS) and Azure to host application deployments. While you can choose the cloud region your Omni application is hosted in, the availability of a specific region is dependent on whether your application is deployed in AWS or Azure.

| Region         | AWS deployments | Azure deployments |
| -------------- | --------------- | ----------------- |
| United States  | <CheckIcon />   | <CheckIcon />     |
| Canada         | <CheckIcon />   | <CheckIcon />     |
| EU             | <CheckIcon />   | <XCircleIcon />   |
| United Kingdom | <XCircleIcon /> | <CheckIcon />     |
| Australia      | <CheckIcon />   | <CheckIcon />     |
| India          | <CheckIcon />   | <XCircleIcon />   |
| UAE            | <XCircleIcon /> | <CheckIcon />     |
| Singapore      | <XCircleIcon /> | <CheckIcon />     |

Customer content will be stored and processed in your selected region.

## Using multiple regions

Each Omni organization account is hosted in a single region.

To use Omni across multiple regions, you must maintain an Omni organization account in each region.


# Omni product & system security
Source: https://docs.omni.co/administration/security/index

Learn more about how Omni keeps your data secure.

Omni is designed to ensure data is only accessible to those who are permitted to access it. Our technical architecture keeps organizations and data sets isolated, and the foundation of our product is a data model with robust governance capabilities that can limit the data sets, fields, and records accessible on a per-user basis.

## Product security and architecture

<img alt="" />

Omni observes the following product and design principles:

* <Tooltip>Customer Data</Tooltip> is always encrypted at rest and in transit over public networks, and customer credentials are additionally encrypted at the application level and can only be decrypted by the application components that require them.
* User authentication through your organization's identity provider like Google, Okta, or any SAML-compatible identity provider, allows you to control security requirements like MFA.
* Users can be assigned [attributes](/administration/users/attributes) that can checked in authorization logic to, for example, limit the user's access to data sets or apply filters.
* Authentication and authorization checks are applied immediately upon the receipt of every request to Omni, and, if passed, set an authorization context on subsequent code execution that ensures the request is sandboxed to the appropriate user and organization.
* Access to a customer's Omni instance by Omni personnel for support is visible to and controllable by the customer.

## Customer data

Omni processes the following data:

* Information about Omni users, for example name and email. This does not include user passwords since this is delegated to a third party identity provider
* Omni configuration data, for example connection parameters, the Omni data model, and chart and dashboard configuration, *excluding* credentials to customer systems
* Data contained in the data sources connected to Omni, referred to as "Customer Data"
* Credentials to access customer data, referred to as "Customer Credentials"

### Data segregation and encryption

<Tooltip>Customer Data</Tooltip> and <Tooltip>Customer Credentials</Tooltip> are:

* Logically segregated on Omni's systems by customer tenant ID and unique dataset identifiers
* Always encrypted at rest and in transit over public networks

Ownership of Customer Data is retained by the customer.

## Security and compliance documentation

See the [Omni Trust Center](https://trust.omni.co/).


# Omni information security program
Source: https://docs.omni.co/administration/security/information-security-program

Omni maintains written policies and procedures designed to ensure the security of our employees, partners, and customers.

Omni's CTO is responsible for the Information Security Program, which is reviewed and updated periodically.

## Compliance audits

Compliance with the policies and procedures is audited at least annually through a SOC 2 Type II audit, which is available upon request.

## People policies

Employees and contractors with access to company data and resources are required to complete the following:

* Sign a confidentiality agreement
* Agree to comply with the policies of the information security program
* Pass a background check by a third party provider

## Data protection and access control

Omni classifies <Tooltip>Customer Data</Tooltip> as our most sensitive asset, and protects it as follows:

* <Tooltip>Customer Data</Tooltip> is not permitted to be copied to destinations outside of the production infrastructure, and is not used for testing, development, or any purpose other than providing the product.
* <Tooltip>Customer Data</Tooltip> is only stored in Omni systems temporarily, and can be permanently deleted upon request
* Access to the production infrastructure and systems is granted on a least privilege basis, requires authentication with multiple factors, and logged.

  Production infrastructure is configured and deployed through automated processes, so direct human access is needed only in rare cases and is not granted to employees other than those responsible for maintaining the automated processes.
* Access to <Tooltip>Customer Data</Tooltip> via the Omni application by Omni personnel for support can be controlled and revoked by the customer
* Use of third party subprocessors on customer data is minimized and, when necessary, subject to thorough review


# Allowlisting Omni's IP addresses
Source: https://docs.omni.co/administration/security/omni-ip-addresses

Find the static IP addresses for your Omni environment and configure your firewall or allowlist for secure database connections.

By default, outgoing database connections from Omni originate from a set list of IP addresses per environment.

## Locating Omni's IP addresses

Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.

## Restricting connection access

In some cases, access to a [database](/connect-data), [SFTP server](/share/deliveries/sftp), or even [webhooks](/share/deliveries/webhooks) can be configured to allow access only from specific IP addresses. This is called an **allowlist**.

If you choose to limit access in this way, make sure that all of Omni's IP addresses are included in the allowlist.


# Vulnerability disclosure policy
Source: https://docs.omni.co/administration/security/vulnerability-disclosure

Learn how Omni handles vulnerabilities and how to report them to our security team.

We are committed to maintaining the security and integrity of our products, services, and systems. Collaboration with the security community strengthens our protections and helps ensure the safety and privacy of our users.

## Our expectations of you

* **Test responsibly**. Make sure your research doesn’t impact privacy, disrupt users, or damage our services.
* **Stay within scope**. Focus only on what this policy considers to be [in scope](#in-scope) - anything not listed is off-limits.
* **Report it**. Use our [contact information](#submitting-reports) to send us your findings.
* **Keep it confidential**. Don’t share details about the vulnerability until we’ve had time to review and/or patch it.

## What you can expect from us

When you report a vulnerability to us, you can expect:

* **Legal protection**. We won't take legal action against you if you follow the guidelines.
* **Prompt acknowledgment**. You’ll hear back from us within 3 business days and we’ll work to fix the issue quickly.

## Vulnerability evaluation

We’ll assess your report based on:

* **Impact**. What is the potential impact of this issue? Could it compromise user privacy or security?
* **Likelihood**. How easy is it to exploit? Does it require advanced skills or is it something a typical attacker could use?

### In scope

This policy covers all systems, services, and infrastructure that are developed, operated, or supported by Omni Analytics. This includes nearly all the content hosted within the following domains:

* `*.omni.co`
* `*.omniapp.co`

### Out of scope

This policy does not cover the following:

* **Third-party services**. If the issue is with a service not controlled by us, we can’t take responsibility for it.
* **Social engineering**. Phishing, smishing, and similar attacks are out of scope.
* **Cosmetic issues**. UI glitches, spelling mistakes, or minor user experience bugs aren’t considered vulnerabilities.
* **Denial of Service (DoS/DDoS)**. We’re not interested in network-level attacks.
* **Outdated browsers/plugins**. Flaws affecting outdated software are outside the scope of this policy.

## Submitting reports

If you've found a vulnerability, email us at [security@omni.co](mailto:security@omni.co) and include:

* A description of the issue and why it's a problem
* The steps to reproduce the vulnerability, including screenshots, scripts, or videos if possible

<Warning>
  Do not include personally identifiable information (PII) or payment card information (PCI) in your reports to us.
</Warning>

We value your efforts to help us improve security and we look forward to working with you!


# Organization settings
Source: https://docs.omni.co/administration/settings

Configure organization-wide settings in Omni, including user access defaults, content visibility, and support access controls.

<Note>
  **Organization Admin** permissions are required to access and modify organization settings.
</Note>

The **Settings > General** tab contains settings that apply to your entire Omni organization. From here, you can control user, content, and Omni support access.

Settings for [Apps](/administration/settings/app-policy) live on their own **Settings > Apps** tab.

Settings for your organization's [custom sidebar](/administration/settings/sidebar) live on their own **Settings > Sidebar** tab.

## General

Settings in the **General** tab control the organization's name, default timezone, localization, user invitations, and support settings.

### Default timezone

Defines the default timezone for the organization, which is used in emails sent by Omni. **Note**: This setting doesn't apply to [database connections](/connect-data/timezones), which have their own timezone settings.

### Locale and allowed locales

Controls the default language used for the Omni app interface and which languages are available to users.

* **Locale** – Sets the default app language for your organization. Users without a user-specific locale will see the app in this language.
* **Allowed locales** – Defines which locales are available as options in your Omni instance.

For more details, see the [Localization settings guide](/administration/localization).

### Session length

Controls how long non-embed users stay logged in before requiring re-authentication. Defaults to 24 hours.

To change the default, enter a whole number between 1 and 4320 hours. The maximum of 4320 hours equals 180 days.

<Note>
  This setting applies to non-embed sessions only. Embed sessions are managed separately. For information on embed session management, see [Embed session management](/embed/admin/sessions).
</Note>

### Trash visibility window

Controls how long deleted content remains visible in the [Trash](/content/archive-restore) before being automatically hidden. Defaults to 180 days.

This setting affects the visibility of archived documents, models, branches, and connections in their respective **Trash** tabs. Content archived longer ago than the configured window will be hidden in the **Trash** and will not appear in trash counts.

<Note>
  This setting only affects visibility in the **Trash**; nothing is deleted or purged.

  To make content hidden due to the retention window visible again, increase the retention window or leave the field blank to show all archived content, regardless of age.
</Note>

### New user invitations

When enabled, new users can request an invitation to the Omni organization from the login page. Otherwise, users will need to contact someone outside of Omni to be added to the Omni organization.

### Support settings

* **Session recording** - When enabled, Omni support will have access to replays of sessions where bugs or errors were encountered
* **Automatic support user creation** - When enabled, Omni support can automatically access your instance for assistance and problem solving
* **Limit Omni support logins by region** - Allows you to limit logins from Omni support to a specific region. When set to something other than **All regions**, the support user's IP address must reside in the specified region to successfully log in to your instance.

  <Note>
    Contact Omni support for access to the **Limit Omni support logins by region** setting.
  </Note>

### Homepage content

Allows you to set a default dashboard or app that adds an inline dashboard or app on the homepage for all users. This setting can be used in embedded Omni instances.

<Frame>
  <img alt="Custom content displaying on Omni homepage when 'Chat on homepage' is enabled" />
</Frame>

To set homepage content:

1. In **Settings > General**, click the **Homepage content** dropdown.
2. Start typing to search for a dashboard or app. **Note**: Only published documents with a dashboard or app will be returned. Workbook-only documents cannot be selected.
3. Select a dashboard or app.
4. Click **Save** to apply the changes.

If the selected dashboard or app isn't accessible to all users, Omni will display a `Limited visibility` message when you click save. Users without access to the content will see the default homepage instead, without the inline content. To make the content visible on all users' homepages, share it with the entire organization.

<Note>
  Homepage content adheres to the selected content's cache policy. For example, if you set a dashboard with a 24 hour cache policy as homepage content, the content is cached using that policy.
</Note>

## Contacts

The **Settings > Contacts** tab allows you to define contact persons for your organization. These settings accept comma-separated lists of email addresses.

### Billing

Defines the contact person(s) for notices about billing and payments related to your organization.

### Security and Privacy

Defines the contact person(s) for notices about security and privacy, including subprocessor updates.

## Preferences

The **Settings > Preferences** section allows you to control optional features and behaviors for your Omni organization.

### Opt out of easter eggs

When enabled, disables all easter eggs across your Omni organization. This setting applies organization-wide and affects all users.

### Opt out of product announcements

When enabled, hides in-app product announcements from non-Organization Admin users in your Omni organization. Announcements targeted specifically at Organization Admins will continue to display, including to the admin who enabled this setting.


# App settings
Source: https://docs.omni.co/administration/settings/app-policy

Control whether your organization can use Apps and which external hosts those apps are allowed to load resources from.

<Note>
  **Organization Admin** permissions are required to access and modify app policy settings.
</Note>

The **Settings > Apps** tab controls whether your organization can use [Apps](/visualize-present/apps) and which external hosts those apps may load resources from.

## Enable apps

Controls whether your organization can use [Apps](/visualize-present/apps), which let you build custom data experiences beyond traditional dashboards.

To restrict app creation to specific users or groups rather than turning apps off entirely, use the granular permission on a [custom role](/administration/users/custom-roles#permissions-reference).

## External source policy

Apps run in a sandboxed iframe whose Content Security Policy blocks outbound network requests by default. The **External source policy** sets the organization-wide ceiling on which external hosts that policy will open up — for images, scripts, stylesheets, fonts, and network connections.

This is separate from, and takes precedence over, the [**Safe domains**](/visualize-present/apps/settings#safe-domains) setting an app editor configures on an individual app.

### Policy options

| Policy            | What apps can load                                                                       | Effect on an app's Safe domains                            |
| ----------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Open**          | Omni's default hosts, plus any host an app editor adds                                   | Honored as written                                         |
| **Omni defaults** | Omni's default hosts only                                                                | Ignored                                                    |
| **Custom**        | Only the hosts you list — these **replace** the default hosts rather than adding to them | Honored only where an entry falls within one of your hosts |

**Omni defaults** is the policy for an organization that hasn't chosen one.

<Warning>
  Under **Custom**, your list replaces Omni's default hosts. If your apps rely on a default host — a charting library from `cdn.jsdelivr.net`, or `fonts.googleapis.com` — you have to list it yourself or those resources stop loading.
</Warning>

To block external loading entirely, choose **Custom** and leave the host list empty. There's no separate off switch: an empty custom list means an app loads nothing from any external host.

### Setting a custom host list

1. Go to **Settings > Apps**.

2. Under **External source policy**, set **Source policy** to **Custom**.

3. Enter your hosts in the **Custom hosts** field. Add one host per line, or separate them with commas or spaces:

   ```text theme={null}
   cdn.example.com
   *.assets.acme.co
   cdn.jsdelivr.net
   ```

4. Click **Save source policy**.

A custom list accepts up to 25 hosts and uses the same formats as an app's [Safe domains](/visualize-present/apps/settings#domain-formats). A `*.` wildcard matches subdomains but not the domain itself, so `*.example.com` covers `cdn.example.com` but not `example.com`.

## Next steps

* [Apps](/visualize-present/apps)
* [App settings](/visualize-present/apps/settings) — the per-app settings an editor controls
* [Organization settings](/administration/settings)


# Authentication settings
Source: https://docs.omni.co/administration/settings/authentication

Configure general authentication behavior, SAML, and OIDC for your Omni organization.

<Note>
  **Organization Admin** permissions are required to access and modify authentication settings.
</Note>

The **Settings > Authentication** page contains settings that control how users sign in to your Omni organization. From here, you can manage general authentication behavior and configure SAML or OIDC.

## Default sign-in methods

The **Default sign-in methods** section controls which authentication methods are available to users by default.

<Note>
  At least one [external sign-in method](#external-sign-in) must be configured before any default methods can be disabled.
</Note>

### Google

When enabled, users can use their Google Workspace account to log in. **Note**: This is a different sign-in method than [Google Workspace SAML](/administration/authentication/google-workspace), which requires additional setup.

### Email

When enabled, users can enter their email address and receive a link to log in.

#### Admin fallback

When **Email** is disabled as a sign-in method, an additional **Admin fallback** setting will display. By default, Organization Admins can sign in using email link authentication as a fallback in case other authentication methods are broken or unavailable. This ensures admins can always access Omni to troubleshoot identity provider issues.

When disabled, this fallback is removed and Organization Admins must sign in using the configured SAML or OIDC provider.

<Warning>
  Disabling the email link fallback can lock administrators out of Omni if your identity provider becomes unavailable or misconfigured. Make sure you have a recovery plan before disabling this setting.
</Warning>

## External sign-in methods

The **External sign-in methods** section allows you to enable authentication through your organization's single sign-on.

### SAML

When enabled, Security Assertion Markup Language (SAML) can be used as an authentication method. Configuring your Identity Provider (IdP) is required before users can successfully use this method to sign in to Omni.

For step-by-step setup instructions, refer to the guide for your identity provider:

* [Google Workspace](/administration/authentication/google-workspace)
* [Microsoft Entra (Azure AD)](/administration/authentication/entra/saml)
* [Okta](/administration/authentication/okta/saml)
* [Rippling](/administration/authentication/rippling/saml)

### OIDC

When enabled, OpenID Connect (OIDC) can be used as an authentication method. Configuring your OIDC Identity Provider is required before users can successfully use this method to sign in to Omni.

For setup instructions, refer to the [OIDC configuration guide](/administration/authentication/oidc).

## Modifying authentication settings

Click the toggle next to a setting to enable or disable it. When finished, click **Save** to apply the changes.

## Need help?

If you run into issues during setup, check the [SSO troubleshooting guide](/administration/authentication/troubleshooting) for common problems and solutions.


# Emoji settings
Source: https://docs.omni.co/administration/settings/emoji

Configure emoji mode for query tabs and manage custom emoji at the organization level.

Emoji settings let you control how query tabs are named in workbooks and manage custom emoji across your Omni organization. You can toggle between emoji-based and sequential tab names, set overrides for embedded experiences, and use custom emoji in dashboards, Markdown, and more.

## Requirements

**Organization Admin permissions** are required to access emoji settings.

## Accessing emoji settings

Organization-level emoji settings are managed in **Settings > Emoji**.

### Emoji tabs

The **Emoji tabs** setting controls how new query tabs are named when users create them in workbooks.

* **When enabled** (default): New query tabs are named with emoji prefixes (for example, "🔍 Query")
* **When disabled**: New query tabs are named sequentially (for example, "Query 1", "Query 2", "Query 3")

This setting applies to all users in your organization by default.

### Sequential tab naming

When emoji mode is disabled, Omni uses the workbook's tab index to generate sequential names:

* The first query tab is named "Query 1"
* The second query tab is named "Query 2"
* Additional tabs continue this pattern

This naming convention helps users quickly identify and reference specific query tabs in workbooks with many queries.

## Embed emoji override

For embedded Omni experiences, you can set a separate emoji mode that overrides the organization-level setting.

The **Embed emoji tabs** setting allows you to:

* Enable emoji mode for embed sessions while keeping it disabled for your internal users
* Disable emoji mode for embed sessions while keeping it enabled for your internal users
* Leave it unset to use the organization-level **Emoji mode** for both internal and embed users

When set, this override applies to all embed sessions in your organization. Embed users will see query tab names based on this setting rather than the organization-level emoji mode.

## Custom emoji

<Note>
  Custom emoji is currently in beta. Additionally, this feature is only available to non-white-labeled embed organizations.
</Note>

Omni's custom emoji catalog (Blobby) provides additional emoji options beyond the standard set. You can use custom emoji throughout Omni to add visual context and personality to your content.

White-label organizations do not have access to custom emoji, as the catalog contains Omni-branded emoji characters.

### Using custom emoji

<Note>
  While **Organization Admin** permissions are required to access emoji settings, users with lesser permissions can use custom emoji in Omni.
</Note>

You can insert custom emoji anywhere text is supported by using the `:emoji-name:` syntax. For example, typing `:blobby-wave:` will render the waving Blobby emoji.

Custom emoji works in the following locations:

* **Dashboard tile titles** - Add emoji to visualization and text tile titles for visual categorization
* **Markdown content** - Use emoji in markdown text tiles and markdown visualizations
* **Workbook tab names** - Include emoji in query tab names to make them more recognizable
* **Field labels** - Add emoji to dimension and measure labels in the modeling layer

### Limitations

* Downloads and deliveries are not yet supported
* Custom emoji will not render inside code blocks or inline code elements. This ensures that emoji syntax in code examples remains as plain text.

### Syntax

To use a custom emoji, wrap the emoji name in colons:

```text theme={null}
:emoji-name:
```

For example:

```text theme={null}
:blobby: Welcome to our dashboard!
```

This will render as:

> <Icon icon="https://mintcdn.com/omni-e7402367/qaBJ-B3EjoUSqHbo/snippets/icons/blobby.ico?fit=max&auto=format&n=qaBJ-B3EjoUSqHbo&q=85&s=d821c1ec8aa65710e62e9f1171fc3770" />  Welcome to our dashboard!

You can use multiple emoji in the same text:

```
:blobby-chart: Sales metrics :blobby-up:
```


# Customizing your organization's navigation sidebar
Source: https://docs.omni.co/administration/settings/sidebar

Build a custom sidebar for your organization with a visual, drag-and-drop editor and live preview.

Use the **Settings > Sidebar** editor to control what users in your Omni organization see in the navigation sidebar. You can add custom groups and items for specific content or external links, like a support site or internal wiki, then reorder and rename them. Omni's built-in groups always stay in the sidebar, but you can rename their items, change their icons, or reset them to defaults.

<Tip>
  **Embedding Omni?** Create a custom sidebar for a curated, branded navigation experience.
</Tip>

## How it works

The Omni sidebar is made of built-in groups and, optionally, custom groups you add. Each group contains items, which can point to a built-in Omni page, an external link, or an existing piece of content in the organization:

| Type                                                   | Links to                               | Visibility                                                |
| ------------------------------------------------------ | -------------------------------------- | --------------------------------------------------------- |
| <Icon icon="table-columns" /> **Built-in**             | An Omni page, such as **My documents** | All users                                                 |
| <Icon icon="up-right-from-square" /> **External link** | An external page                       | All users                                                 |
| <Icon icon="folder" /> **Content**                     | An existing folder or document in Omni | Users with at least **Viewer** permissions on the content |

<Note>
  Built-in items only exist in built-in groups. Custom groups can only contain external link and content items.
</Note>

### Default sidebar

Omni's default sidebar contains four built-in groups: **Home**, **Personal**, **Shared**, and **All**. These groups always exist and can't be removed or reordered, and **Home** always appears first. Custom groups you add can be reordered among themselves and always appear after **Home**. See [Navigating Omni](/content/navigate) for more information about the built-in pages.

## Requirements

**Organization Admin** permissions are required to access and modify sidebar settings.

## Creating a custom sidebar

An Omni organization can have one custom sidebar in use at a time. Customizing it starts from the [default sidebar](#default-sidebar): add custom groups and items, then reorder and relabel them to match your organization's needs. Your changes stay in a draft until you [save them](#save-discard).

### Adding groups

Adding a group creates a custom group. Built-in groups (**Home**, **Personal**, **Shared**, and **All**) can't be added or removed.

To add a new custom group:

1. In the sidebar, click **Settings > Sidebar**.
2. Click **+ Add group**.
3. Enter a display label for the group.
4. [Add items to the group](#add-item).

### Group titles and visibility

Every group, built-in or custom, has an optional title. Once a group has a title, click the eye icon next to it to show or hide the group's header in the sidebar.

By default, the **Personal** and **Shared** groups are titled "Personal" and "Shared," but their headers are hidden, so the default sidebar doesn't display any group headers.

<Note>
  For the **Personal** and **Shared** groups, the title is also the name of the space. If you change the title, Omni uses the new name everywhere it refers to the space: the [Share dialog](/share), folder location chips, the activity feed, breadcrumbs, and [content search](/content/search). This applies whether or not the group's header is visible in the sidebar.
</Note>

### Adding items to groups

You can only add items to custom groups. Built-in groups already contain their full set of items and can't be added to.

To add a new item to a custom group:

1. In the group, click <Icon icon="plus" /> to open the add menu.
2. Choose an item type:
   * **External link** - When prompted, specify a **Label** and **URL**, and whether the link should open in a new tab.
   * **Content** - When prompted, select the content from the content picker.
     <Note>
       When content that isn't shared with the organization is selected, a <Badge icon="lock">Some members</Badge> badge will display next to the content item. Users that don't have access to the content won't see it in the sidebar.
     </Note>
3. **Optional.** Enter a display label for the item. Leave empty to use the default label.
4. **Optional.** Click the icon to the left of the item's display label to select a custom icon, or click **Remove icon** to restore its default.

### Reordering items and groups

Built-in groups and their items can't be reordered or moved. Only custom groups and their items can be reordered:

* Drag a custom group or one of its rows by its handle <Icon icon="grip-vertical" /> to reorder it. Items can be reordered within their existing custom group or moved to a different custom group.
* You can also move a custom group by clicking its <Icon icon="ellipsis-vertical" /> icon and selecting **Move up** or **Move down**. Custom groups always stay after the **Home** group.

### Editing items

To update an existing item, click its <Icon icon="ellipsis-vertical" /> icon. The options in this menu depend on the item type:

* **Built-in** - If you customized the display label, select **Reset to defaults** to use the default label instead. This option is disabled if the item's display label hasn't been customized.
* **External link** - Select **Edit link** to update the item's label, URL, or how it opens when clicked.
* **Content** - Select **Edit** to change the content the item links to.

<Note>
  If you specify a custom label for a built-in item, the label will be used everywhere else it appears in Omni. For example, the [Share dialog](/share), page titles, browser tabs, etc.
</Note>

### Deleting items

Built-in groups and their items can't be deleted. To delete a custom group or one of its items, click its <Icon icon="ellipsis-vertical" /> icon and select **Delete**. Deleting a custom group also deletes all the items it contains.

## Saving and discarding changes

Changes are held in a draft scoped to your browser session until you save them, so reloading the page doesn't lose your changes. When finished, click **Save** to apply the customized sidebar to your organization.

To delete the changes and revert to the last saved sidebar, click **Discard**.

## Exporting a sidebar

Exporting a sidebar copies a sidebar's JSON configuration to your clipboard. Click the <Icon icon="ellipsis-vertical" /> icon near the top right corner of the page, then **Export**.

```json expandable theme={null}
{
  "groups": [
    {
      "id": "home",
      "items": [
        {
          "builtinId": "home",
          "type": "builtin"
        },
        {
          "builtinId": "chat",
          "type": "builtin"
        },
        {
          "builtinId": "routines",
          "type": "builtin"
        },
        {
          "builtinId": "skills",
          "type": "builtin"
        }
      ]
    },
    {
      "id": "personal",
      "items": [
        {
          "builtinId": "favorites",
          "type": "builtin"
        },
        {
          "builtinId": "my-documents",
          "type": "builtin"
        },
        {
          "builtinId": "activity",
          "type": "builtin"
        }
      ]
    },
    {
      "id": "shared",
      "items": [
        {
          "builtinId": "hub",
          "type": "builtin"
        },
        {
          "builtinId": "shared-with-me",
          "type": "builtin"
        }
      ]
    },
    {
      "id": "all",
      "items": [
        {
          "builtinId": "all",
          "type": "builtin"
        },
        {
          "builtinId": "trash",
          "type": "builtin"
        }
      ]
    }
  ],
  "version": 1
}
```

## Importing a sidebar

To import a sidebar:

1. Click the <Icon icon="ellipsis-vertical" /> icon near the top right corner of the page.
2. Click **Import**.
3. Paste a sidebar [exported from this page](#export).
4. Click **Import.**
5. **Optional.** Change the layout in the editor if needed.
6. When finished, [save your changes](#save-discard).

## Next steps

* [Organization settings](/administration/settings)


# Application theme settings
Source: https://docs.omni.co/administration/themes/application

Configure application theme settings in Omni, including navigation colors, fonts, dark mode, branding, and theme import/export.

<Note>
  **Organization Admin** permissions are required to access and modify application theme settings.
</Note>

Settings in the **Settings > Theme > Application** tab control the appearance of your Omni instance, including enabling light and dark mode.

## Customizing your theme

<Tip>
  **Want to speed things up?** Use the [Theme Lab](https://omni-theme.pages.dev/) to upload an image and generate a starting color palette for your theme. **This feature is experimental and may change.**
</Tip>

<Steps>
  <Step>
    Navigate to **Settings > Theme > Application tab**.
  </Step>

  <Step>
    Update the [available theme settings](#available-settings) to your liking.
  </Step>

  <Step>
    **Optional**: [Preview the theme](#previewing-the-theme) before saving.
  </Step>

  <Step>
    Click **Save** when finished. All changes will be immediately applied for internal and (if applicable) embed users.
  </Step>
</Steps>

## Importing and exporting theme configuration

To export or import theme configurations, scroll to the bottom of the **Application** tab and click the <Icon icon="ellipsis-vertical" /> menu.

* **Export** downloads the current theme as an `application-theme.json` file. All theme properties are included; properties that have not been customized are exported as `null`.
* **Import** opens a dialog where you can paste JSON or upload a `.json` file. You can also drag and drop a `.json` file directly onto the settings form. Properties not included in the imported file are reset to defaults. Changes are not saved automatically — click **Save** after importing.

The JSON format uses `styles` for light mode and `stylesDark` for dark mode. The `assets` and `assetsDark` keys contain branding asset URLs. All keys are optional; missing keys default to empty. Color values must be CSS color strings or `null`, and asset URLs must be HTTPS URLs or `null`.

```json theme={null}
{
  "styles": {
    "primary-color": "#271126"
  },
  "stylesDark": {
    "primary-color": "#FFFFFF"
  },
  "assets": {
    "logo": "https://example.com/logo.png",
    "wordmark": "https://example.com/wordmark.png"
  },
  "assetsDark": {
    "logo": "https://example.com/logo-dark.png",
    "wordmark": "https://example.com/wordmark-dark.png"
  }
}
```

## Previewing the theme

Click **Preview theme** to open a live side-by-side preview of your theme in light and dark mode before saving. The preview includes a mock sidebar, draft banner, primary button, and heading text with any custom fonts applied.

## Restoring factory defaults

To reset all theme customizations to Omni defaults, click the <Icon icon="ellipsis-vertical" /> menu and select **Restore factory defaults**. Click **Save** to persist the reset.

## Available settings

### Color scheme (light and dark mode)

These settings control whether users see light mode, dark mode, or the system default, and whether they can override the instance-wide choice.

| Setting                     | Description                                                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Default color scheme**    | Defines the default color scheme - **Default**, **Light**, or **Dark** - for the instance. Click **Change** to save the selection. |
| **Allow user color scheme** | Allows users to select their preferred color scheme for the Omni instance.                                                         |

### Styles

Each color property can be set independently for light and dark mode. If only one mode is customized, the other mode retains its default colors.

#### Interactive colors

Interactive colors affect primary buttons (such as **Run** and **Save**), outline and transparent buttons, draft and editing banners and indicators, branch bar styling, and notification badge dots.

| Setting                | Description                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action border**      | Border color for outline and transparent buttons throughout the UI                                                                                |
| **Action text**        | Text and icon color for outline and transparent buttons                                                                                           |
| **Primary color**      | Color for primary buttons and interactive elements (for example, **Run** and other action buttons)                                                |
| **On primary**         | Text and icon color displayed on top of primary-colored elements                                                                                  |
| **Editing color**      | Color for draft and editing indicators, including the draft banner, edit mode buttons, and branch indicators. Defaults to the system draft color. |
| **On editing**         | Text color displayed on editing-colored elements, such as text on draft banners and tokens                                                        |
| **Notification color** | Color for notification badges and indicator dots throughout the UI. Defaults to `#ff4794`.                                                        |

#### Navigation colors

Navigation colors affect the main [sidebar](/administration/settings/sidebar) and dialog navigation panels, such as the **Settings** sidebar. You can control the appearance of items in their default, hover, and selected states.

<Note>
  Dialogs with navigation sidebars, like **Settings**, automatically respect your navigation color choices.
</Note>

| Setting                   | Description                                                 |
| ------------------------- | ----------------------------------------------------------- |
| **Background**            | Navigation sidebar background color                         |
| **Background (hover)**    | Background color when hovering over navigation items        |
| **Background (selected)** | Background color for the currently selected navigation item |
| **Text**                  | Default text color in the navigation sidebar                |
| **Text (hover)**          | Text color when hovering over navigation items              |
| **Text (selected)**       | Text color for the currently selected navigation item       |
| **Icon**                  | Default icon color in the navigation sidebar                |
| **Icon (hover)**          | Icon color when hovering over navigation items              |
| **Icon (selected)**       | Icon color for the currently selected navigation item       |

### Branding assets

Custom branding assets allow you to replace the default Omni logo and wordmark with your own brand assets throughout the Omni interface. Assets can be customized separately for light and dark modes, with automatic fallback when only one mode is configured.

<Note>
  Custom branding asset images must be:

  * Specified using an HTTPS URL
  * In a web-compatible format such as PNG, SVG, JPG, etc.
  * Publicly accessible
</Note>

| Setting                  | Description                                                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Logo**                 | Square brand mark displayed in the header at 24×24px. Typically used for icons or compact logo designs. Appears in the navigation header across all page types.            |
| **Logo (dark mode)**     | Alternative logo for dark mode. If not provided, the light mode logo will be used in dark mode.                                                                            |
| **Wordmark**             | Horizontal brand text or logo displayed in the header at 100×24px. Best for text-based logos or wider brand marks. Appears alongside or instead of the logo in the header. |
| **Wordmark (dark mode)** | Alternative wordmark for dark mode. If not provided, the light mode wordmark will be used in dark mode.                                                                    |

#### Using custom assets in embedded applications

When custom branding assets are configured, they appear in application mode embeds where the default Omni branding is normally hidden. This allows you to maintain your brand presence in embedded analytics experiences.

* If a custom logo is set, it replaces the <Icon icon="bars" /> menu icon in application mode embeds
* Custom wordmarks are also displayed in embed contexts
* Assets automatically adapt to the user's color scheme (light or dark mode)

### Fonts

Currently, only publicly-accessible [WOFF2 formats](https://www.w3.org/TR/WOFF2/) are supported.

| Setting     | Description                                                                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Heading** | Font used for page titles, dialog titles, Markdown headings, and dashboard tile headings. Must be a valid URL to a publicly-accessible WOFF2 file. |
| **Body**    | Main font used throughout the application UI. Must be a valid URL to a publicly-accessible WOFF2 file.                                             |

## Related

* [Document theme settings](/administration/themes/documents) - Customize the look and feel of your Omni content


# Document theme settings
Source: https://docs.omni.co/administration/themes/documents

Customize the look and feel of content in your Omni instance.

<Note>
  **Organization Admin** permissions are required to access and modify document theme settings.
</Note>

The **Settings > Themes > Documents** tab lists the document themes in your Omni instance.

## Creating and editing themes

Document themes are created and edited in published dashboards. See [Applying themes](/visualize-present/dashboards/theming) to learn how to create document themes.

## Setting, duplicating, and deleting themes

You can interact with individual themes by using the <Icon icon="ellipsis-vertical" /> (three dots icon) in individual rows. This menu allows you to:

* Set and unset a default theme
* Duplicate a theme
* Delete a theme, which will unapply the theme from any documents currently using it

## Applying a default theme to documents

To apply the default theme to documents and workbooks without a set theme, click the <Icon icon="ellipsis-vertical" /> (three dots icon) at the top of the list of themes, then **Apply default theme to all documents**.


# Application and document theme settings
Source: https://docs.omni.co/administration/themes/index

Manage application and document themes in Omni to customize branding, colors, fonts, and visual style across your organization.

<Note>
  **Organization Admin** permissions are required to modify theme settings.
</Note>

The **Settings > Themes** page allows you to control the look and feel of your Omni instance, from the colors and fonts used throughout the application to the themes used in workbooks and dashboards.

## Application

Application theme settings control the colors, fonts, and styling used across your Omni instance, including light and dark mode, navigation sidebar appearance, and interactive element colors. You can also import and export theme configurations as JSON.

See [Application theme settings](/administration/themes/application) for more information.

## Document themes

Document themes control the appearance of content within workbooks and dashboards, including default color palettes for visualizations. You can create multiple document themes and set a default that applies across your instance.

See [Document theme settings](/administration/themes/documents) for more information.


# User attributes
Source: https://docs.omni.co/administration/users/attributes

Utilize user-specific variables to create dynamic content and control data access.

<Note>
  **Organization Admin** permissions are required to create and modify user attributes, including assigning them to users.
</Note>

User attributes allow you to map user-specific variables to Omni operations, such as querying, dashboarding, and data access. These attributes can be used in dashboard filters or workbooks or to filter embedded content.

<img alt="The user attributes settings page, showing a list of defined attributes." />

## User attribute basics

<AccordionGroup>
  <Accordion title="Can I use user attributes to control data access?">
    Yes. User attributes can be used in a few ways to control data access:

    * [**Access filters**](/modeling/topics/parameters/access-filters), which allow you to restrict the rows of data a user can access within a topic. Access filters apply the values assigned on a user attribute to the `WHERE` clause of every SQL query a user runs, filtering out to only the data designated to that user:

      ```yaml title="Filter by brand_name" theme={null}
      access_filters:
        - field: products.brand
          user_attribute: brand_name
          values_for_unfiltered: [all_brands]
          enable_sql_like_wildcards: true
      ```

    * [**Access grants**](/modeling/models/access-grants), which define topic- and field-level permissions. Omni will map a user's attribute value to a corresponding allowed value and determine if the user has the necessary permissions to access that topic or field:

      ```yaml title="Grant access for user group" theme={null}
      access_grants:
        blob_sales_access:
          user_attribute: "omni_user_groups"
          allowed_values: ["Blob Sales"]
          access_boostable: false
      ```

    * **Fields**. User attributes can be referenced in fields using Mustache syntax, for example: `{{ omni_attributes.<attribute-name> }}`. This construct can be used to:
      * Provide conditional access to a field, or
      * To hash a field based on a user attribute. This can be done by using a `CASE` statement in the SQL definition for a field. For example, the following `name_hidden` and `name_hashed` examples demonstrate how to use user attributes to hide or hash a name field as an alternative to using access grants to remove access entirely:

        ```yaml title="Hide or hash field based on user attribute" theme={null}
        name:
          sql: ${users.full_name}

        name_hidden:
          sql: |+
            CASE 
              WHEN {{omni_attributes.see_names}} = 'true'
              THEN ${users.name}
              ELSE 'No Access'
            END

        name_hashed:
          sql: |+
            CASE 
              WHEN {{omni_attributes.see_names}} = 'true'
              THEN ${users.name}
              ELSE MD5(${users.name})
            END
        ```
  </Accordion>

  <Accordion title="Can I use user attributes to dynamically change database connections?">
    Yes. User attributes can be used to parameterize the connection queries run against while in an Omni branch. Refer to the [Dynamically switching database environments guide](/connect-data/dynamic-environments) for more information and setup steps.
  </Accordion>

  <Accordion title="Can I use user attributes to route users to tenant-specific models?">
    Yes. [Shared extension models](/modeling/develop/shared-extensions) use user attributes to route users to the correct model extension. You define a mapping in the parent model's `dynamic_shared_extensions` parameter that links user attribute values to specific extensions.
  </Accordion>

  <Accordion title="Can I use user attributes to create dynamic content?">
    Yes. There are a few ways to do this:

    * **Dashboard Markdown tiles**. You can use user attributes in dashboard Markdown tiles with [Mustache syntax](/visualize-present/mustache-reference). For example, `{{metadata.userAttributes.<user_attribute>.values}}` would return the value of the specified user attribute.
    * **Dashboard deliveries**. User attributes can be used to [personalize deliveries](/share/deliveries/dynamic-content), including messages (where supported) and the data included in the delivery.
  </Accordion>

  <Accordion title="Can I assign user attributes to email-only users?">
    Yes. The steps for [assigning a user attribute](#assigning-attributes-to-users) are the same regardless of user type. To view [email-only users](/administration/users/email-only) when working with a specific attribute, click the **Email Only** toggle in the attribute's **Users** tab:

    <img alt="The Email Only toggle highlighted in the Users tab of a user attribute." />
  </Accordion>

  <Accordion title="Does Omni have any system (default) user attributes?">
    Yes. Refer to the [Default system attributes section](#default-system-user-attributes) for more information.
  </Accordion>
</AccordionGroup>

## Creating user attributes

To define a new user attribute, navigate to **Settings > Attributes** and click the **New Attribute** button.

Each user attribute has the following settings:

* **Name**: The name of the user attribute, how it will be displayed in the UI
* **Reference**: How the attribute will be referenced in code, such as in the model
* **Type**: Used to check that valid values are assigned to users. String and Number data types are allowed.
* **Multiple values**: Specifies whether multiple values can be assigned to a user for this attribute
* **Description**: Explanation of the attribute or how it will be used
* **Default value**: **Optional**. Set a default value that all users will inherit if a value is not directly assigned to them.

  <Warning>
    **Do not set a default value for attributes used in access filters or access grants.** Omni assigns the default value to all users immediately upon account creation. If the default value matches a [`values_for_unfiltered`](/modeling/topics/parameters/access-filters#properties) value, those users will receive unfiltered data.

    Leave the default blank to get fail-closed behavior: users without an assigned value receive an error or no rows, which is visible and fixable. If you use `values_for_unfiltered`, do not set its value as the attribute default.
  </Warning>

<img alt="The new user attribute form with fields for name, reference, type, multiple values, description, and default value." />

## Assigning attributes to users

<Note>
  The steps in this section apply to all user types, including [email-only](/administration/users/email-only) and [embed](/embed).
</Note>

After defining a user attribute, you can assign values to individual users.

<Steps>
  <Step>
    Navigate to **Settings > Attributes**.
  </Step>

  <Step>
    Click the attribute you want to set.
  </Step>

  <Step>
    In the attribute's page, click the **Users** tab.
  </Step>

  <Step>
    In the list of users, locate the user you want to work with. Use the toggles above the table to filter the list by:

    | Filter        | Description                                                                                                                                                                                                                                                                                                                                                        | Default    |
    | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
    | **User type** | Filters users by type:<ul><li>**Org users** - Show only standard users that can log into Omni</li><li>**Email only** - Show only email only users</li><li>**Embed Users** - Show only embed users</li><li>**All** - Show all users, regardless of type</li></ul>                                                                                                   | Org users  |
    | **Value**     | Filters users by their assigned attribute value. Click the control to display condition settings: <ul><li>**any** - Show all users, regardless of value</li><li>**contains** - Show users whose value contains the text you enter</li><li>**is empty** - Show users with no assigned value</li><li>**is not empty** - Show users with any assigned value</li></ul> | Any        |
    | **Source**    | Filters users by the source of their assigned attribute value: <ul><li>**Any source** - Show all users, regardless of source</li><li>**User setting** - Show users with non-default attribute values</li><li>**Default setting** - Show users with default attribute values</li></ul>                                                                              | Any source |
  </Step>

  <Step>
    Click the **Edit value** button in user's row.
  </Step>

  <Step>
    In the dialog that displays, enter the value for the user.
  </Step>

  <Step>
    Click **Save**.
  </Step>
</Steps>

After updating, the **Source** field will show whether the value is the default value (`-`) or if it was set specifically for the user (`User setting`).

## Default system user attributes

<Note>
  System attributes are read-only.
</Note>

Omni's default user attributes will be marked with a **System** badge in the **Settings > Attributes** page.

<ParamField type="number">
  A special virtual attribute that allows Organization Admins to set an organization-wide default AI credit limit for users. Unlike regular user attributes that assign individual values per user, this virtual attribute sets a default that applies to all users that don't have set [individual credit limits](/ai/settings/usage#individual-user-limit). By default, users have unlimited AI credits.

  To set this for an embed user with URL parameters, use the [embed `userAttributes` parameter](/embed/setup/url-parameters/userAttributes).

  Click this attribute in **Settings > Attributes** to open the configuration page for the attribute. See [Managing AI credit usage](/ai/settings/usage) for full details on configuring per-user credit limits.
</ParamField>

<ParamField type="boolean">
  If `true`, the user can create, save, or move content in their [personal **My documents** folder](/content/navigate). When `false`, **My documents** is hidden in the [sidebar](/administration/settings/sidebar) and content operations default to the organization scope. Controlled with the **Personal content access** setting in each [user's settings page](/administration/users/settings#personal-content).
</ParamField>

<ParamField type="boolean">
  If `true`, the split-view AI chat panel opens on the right side of the screen with the document or dashboard on the left. When `false`, the chat panel opens on the left.

  Use this attribute to set the behavior for embed users or a default for your users. Individual users can update their preference with the **Chat panel on the right** setting in their [account settings](/administration/users/your-account#chat-panel-side).
</ParamField>

<ParamField type="boolean">
  If `true`, the user is an **Organization Admin**.
</ParamField>

<ParamField type="string">
  The user's email address.
</ParamField>

<ParamField type="string">
  The user's embedded entity name. For example, `Blobs R Us`
</ParamField>

<ParamField type="string">
  The [user groups](/administration/users/groups) that the user is a member of. The value will be a comma-separated list of user group names, for example `Blob Sales, Blob Marketing`
</ParamField>

<ParamField type="string">
  A unique identifier for the user. For example, `91abbe19-b0de-4537-bc62-cec1d95420c9`
</ParamField>

<ParamField type="string">
  The user's locale code. Possible values are:

  | Locale code | Language                      |
  | ----------- | ----------------------------- |
  | `en-US`     | English (default)             |
  | `ar-SA`     | العربية (السعودية) (Arabic)   |
  | `de-DE`     | Deutsch (Deutschland)         |
  | `es-CL`     | Español (Chile)               |
  | `es-ES`     | Español (España)              |
  | `fr-FR`     | Français (France)             |
  | `he-IL`     | עברית (ישראל)                 |
  | `it-IT`     | Italiano (Italia)             |
  | `ja-JP`     | 日本語 (日本)                      |
  | `ko-KR`     | 한국어 (대한민국) (Korean)           |
  | `nb-NO`     | Norsk bokmål (Norge)          |
  | `pt-BR`     | Português (Brasil)            |
  | `pt-PT`     | Português (Portugal)          |
  | `sv-SE`     | Svenska (Sverige)             |
  | `th-TH`     | ไทย (ประเทศไทย) (Thai)        |
  | `vi-VN`     | Tiếng Việt (Việt Nam)         |
  | `zh-CN`     | 中文 (中国) (Simplified Chinese ) |

  See the [Localization guide](/administration/localization) for more information.
</ParamField>

<ParamField type="string">
  The user's name. For example, `Blob Ross` or `Blobby Parton`
</ParamField>

<ParamField type="string">
  The user's timezone, which is set using the **Query timezone** setting on the user's profile. For example, `UTC` or `America/Los_Angeles`
</ParamField>


# Defining custom model roles
Source: https://docs.omni.co/administration/users/custom-roles

Define custom roles with specific permission restrictions that can be assigned to users, groups, and connections.

<Note>
  **Organization Admin** permissions are required to manage custom model roles.
</Note>

Custom roles allow organizations to define variations of existing base roles, such as **Viewer No Download** or **Querier No CSV Upload**. These custom roles inherit the core capabilities of a base role while enabling restrictions on specific granular permissions. This structure avoids the need to create entirely new base role tiers for minor capability adjustments.

## Custom role basics

<AccordionGroup>
  <Accordion title="What are base roles and role tiers?">
    Omni organizes permissions into a hierarchy of role tiers, where each tier builds on the one below it:

    | Tier                   | Core capability                                   |
    | ---------------------- | ------------------------------------------------- |
    | **No Access**          | No access to the organization                     |
    | **Viewer**             | View content                                      |
    | **Restricted Querier** | Create topic-based queries                        |
    | **Querier**            | Create all views and fields queries and write SQL |
    | **Modeler**            | Edit the shared data model                        |
    | **Connection Admin**   | Manage connections and model permissions          |

    Each tier includes all the capabilities of the tiers below it. Custom roles are variations within a tier — they inherit the tier's core capability but can restrict specific granular permissions.

    See the [Permissions reference](/administration/users/permissions-reference) for more information on the specific abilities each tier has.
  </Accordion>

  <Accordion title="What are granular permissions?">
    Granular permissions are optional capabilities within a role tier that can be individually enabled or disabled. These are what custom roles customize.

    Some granular permissions are nested under a parent permission in the UI — for example, **Upload data** falls under **Use workbooks**. See [Creating custom roles](#creating-custom-roles) for details on how parent and child permissions work.

    A custom role keeps the tier's core capability but can restrict any combination of these granular permissions. For example, a **Querier No Upload** role has full **Querier** capabilities but with the **Upload data** permission disabled. See the [Granular permissions reference](#permissions-reference) for a full list of available permissions.
  </Accordion>

  <Accordion title="Who can create/edit/delete custom roles?">
    **Organization Admin** users can create, edit, and delete custom roles.
  </Accordion>

  <Accordion title="Where can I assign custom roles?">
    Custom roles can be:

    * Assigned to [users](/administration/users)
    * Assigned to [user groups](/administration/users/groups)
    * Set as the **Base access** on a connection
  </Accordion>

  <Accordion title="What happens when a user or group is assigned multiple roles?">
    When a user or group has multiple roles assigned, Omni uses role priority to determine which role takes effect. The higher-priority role wins.

    * **Across tiers** - Higher base role tiers (e.g., **Modeler**) always take precedence over lower tiers (e.g., **Viewer**), regardless of custom role priority.
    * **Within a tier** - Priority is determined by the order roles appear in the list, starting from the top. For example, in the screenshot below, the base **Querier** role has the highest priority because it appears first:

      <Frame>
        <img alt="Roles list showing the Querier tier with the base Querier role above the custom Querier No Upload role" />
      </Frame>

      You can change the priority of roles within a tier by clicking the <Icon icon="grip-vertical" /> icon on a role and dragging it to re-order the list. Role tiers cannot be reordered, only the roles defined in the tier itself.
  </Accordion>

  <Accordion title="Can custom roles be used with embed?">
    Yes - custom roles with a **resolved role** of **Restricted Querier** or **Viewer** may be used in [embedded contexts](/embed).

    Use the role's **name** when passing the custom role using [`connectionRoles`](/embed/setup/url-parameters/connectionRoles) and [`modelRoles`](/embed/setup/url-parameters/modelRoles), for example:

    ```json title="Example modelRoles object with custom role" highlight={3} theme={null}
    {
      "model-id-1":"RESTRICTED_QUERIER", 
      "model-id-2":"VIEWER_NO_DOWNLOAD"
    }
    ```
  </Accordion>
</AccordionGroup>

## Creating custom roles

<Steps>
  <Step title="Create the role">
    1. Navigate to **Settings > Roles**.
    2. Click **+ Create custom role**.
    3. Fill in the following:
       * **Name** - **Required**. Enter a unique name for the custom role, such as `querier_no_upload`. Names can only contain letters, numbers, underscores, and hyphens.
       * **Display Name** - **Required**. Enter a human-readable display name for the role. This is shown in the UI.
       * **Description** - Enter a description of the custom role. This will display in the **Description** column on the **Roles** page.
  </Step>

  <Step title="Select granular permissions">
    Next, choose the granular permissions you want the custom role to have. Permissions are hierarchical at two levels:

    * **Across role tiers** - Each role tier builds on the tiers below it. To grant a permission from a higher tier, the base permission for each lower tier must also be selected.

      For example, to grant **Create all views and fields queries and write SQL** (Querier), you must also select **Create topic based queries** (Restricted Querier):

      <Frame>
        <img alt="Permissions panel showing the Restricted Querier and Querier base permissions both selected" />
      </Frame>

    * **Within a role tier** - Some permissions are nested under a parent permission. The parent must be selected before you can grant any of its children, but you can deselect individual child permissions.

      For example, **Create spreadsheets** requires **Use workbooks** to be selected, but you can deselect **Upload data** independently:

      <Frame>
        <img alt="Restricted Querier tier showing Use workbooks and Create spreadsheets selected, with Upload data deselected" />
      </Frame>

    As you select and deselect permissions, the **Resolved Role** and **Exceptions** sections on the left side will update:

    <Frame>
      <img alt="New Role dialog showing selected permissions on the right, with Resolved Role showing Querier and Exceptions listing Upload data and Use Omni Agent as disabled" />
    </Frame>

    The **Resolved Role** shows the base role tier that your custom role maps to based on the permissions you've selected, which determines how the role is treated for [licensing](/administration/users/permissions#license-types). The **Exceptions** section lists any permissions that are different when compared to the base version of that role tier.
  </Step>

  <Step title="Save the role">
    Click **Save** when finished to create the role.
  </Step>
</Steps>

Once created, the role will display in the **Roles** page within its resolved role tier, along with any restrictions and the date it was created:

<Frame>
  <img alt="Roles list showing the Querier tier with the base Querier role and the custom Querier No Upload role with a No data uploads restriction" />
</Frame>

## Changing role priority in a role tier

Priority is determined by the order roles appear in the list, starting from the top. For example, in the screenshot below, the base **Querier** role has the highest priority because it appears first:

<Frame>
  <img alt="Roles list showing the Querier tier with the base Querier role listed above the custom Querier No Upload role" />
</Frame>

You can change the priority of roles within a tier by clicking the <Icon icon="grip-vertical" /> icon on a role and dragging it to re-order the list.

<Note>
  Role tiers cannot be reordered, but the base role within the tier can be moved. For example, the **Querier** role in the above screenshot could be moved, but the **Querier** tier that contains the **Querier** and **Querier No Download** roles can't.
</Note>

## Editing custom roles

<Note>
  Base roles - **Viewer**, **Restricted Querier**, **Querier**, **Modeler**, and **Connection Admin** - can't be edited.
</Note>

1. Navigate to **Settings > Roles**.
2. Click the <Icon icon="ellipsis-vertical" /> icon in the same row as the custom role and select **Edit**.
3. Make your changes.
4. Click **Save** when finished.

## Duplicating custom roles

1. Navigate to **Settings > Roles**.
2. Click the <Icon icon="ellipsis-vertical" /> icon in the same row as the custom role and select **Duplicate**.
3. Give the role a name and choose the permissions it should have.
4. Click **Save** when finished.

## Deleting custom roles

<Note>
  Base roles - **Viewer**, **Restricted Querier**, **Querier**, **Modeler**, and **Connection Admin** - can't be deleted.
</Note>

Deleting a custom role reassigns all affected users and groups to the tier's base role. For example, deleting a custom role that resolves to **Querier** will revert all assignees to the **Querier** base role.

1. Navigate to **Settings > Roles**.
2. Click the <Icon icon="ellipsis-vertical" /> icon in the same row as the custom role and select **Delete**.
3. When prompted, click **Delete**.

## Assigning custom roles

Custom roles can be assigned:

* **As the [Base Access](/administration/users/permissions#defining-permissions-for-a-connection)** level for a connection
* **To individual users** in the user's [**Model Access**](/administration/users/settings#model-access) tab
* **To [user groups](/administration/users/groups#model-access)** in a connection's **Permissions > Connection Roles** section

## Granular permissions reference

<table>
  <thead>
    <tr>
      <th>Role</th>
      <th>Permission</th>
      <th>Required permissions</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Viewer**</td>
      <td>**Run topic-based queries**</td>
      <td>Cannot be disabled</td>
    </tr>

    <tr>
      <td>**Download**</td>
      <td>Run topic-based queries</td>
    </tr>

    <tr>
      <td>**Schedule / Alerts**</td>
      <td>Run topic-based queries</td>
    </tr>

    <tr>
      <td>**Restricted Querier**</td>

      <td>
        **Create topic-based queries**
      </td>

      <td>Run topic-based queries (Viewer)</td>
    </tr>

    <tr>
      <td>**Use Omni Agent**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**View IDE**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**View SQL**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Use workbooks**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Upload data**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
          <li>Use workbooks</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Create spreadsheets**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
          <li>Use workbooks</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>[**Create apps**](/visualize-present/apps)</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries</li>
          <li>Use workbooks</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Querier**</td>
      <td>**Create all views and fields queries and write SQL**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries (Restricted Querier)</li>
          <li>View SQL</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Modeler**</td>
      <td>**Edit shared data model**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries (Restricted Querier)</li>
          <li>View SQL (Restricted Querier)</li>
          <li>Create all views and fields queries and write SQL (Querier)</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Connection Admin**</td>
      <td>**Manage connections and model permissions**</td>

      <td>
        <ul>
          <li>Run topic-based queries (Viewer)</li>
          <li>Create topic-based queries (Restricted Querier)</li>
          <li>View SQL (Restricted Querier)</li>
          <li>Create all views and fields queries and write SQL (Querier)</li>
          <li>Edit shared data model (Modeler)</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## Next steps

* [User groups](/administration/users/groups) - Assign custom roles to groups of users
* [Permissions](/administration/users/permissions) - Understand the full permissions model
* [Content sharing](/share) - Learn how content access works alongside connection roles


# Revoking user memberships
Source: https://docs.omni.co/administration/users/delete

Learn how to permanently revoke a user's membership in Omni, including what happens to their content and deliveries.

<Danger>
  Revoking user memberships is **not reversible**. Read this guide carefully before revoking a user's membership.
</Danger>

When a user's membership to your Omni instance is revoked, the following will occur:

* **Schedules created by the user will be deleted**. Unless transferred, the schedules must be re-created by another user to continue.
* [**Content in the user's Personal folder**](/content/navigate) will be accessible to **Organization Admins** through search. Content outside of the user's Personal folder will not move.
* [API Keys](https://docs.omni.co/api/authentication)
  * [PATs](https://docs.omni.co/api/authentication#token-types) will be disabled.
  * [Organization API keys](https://docs.omni.co/api/authentication#organization-api-keys) will remain active. Requests to endpoints which require context about the user taking action may fail if the user is revoked.

Even if the user is re-added to your Omni instance with the same name and email, their previous history, permissions, content, etc. will not be associated with them. It will be as if they are a brand new user.

## Preparation checklist

Before you revoke a user's membership, complete the following:

<Steps>
  <Step title="Move any content in the user's Personal folder to a different location">
    Prior to being revoked, **Organization Admins** can impersonate the user to directly access this folder and move its content.

    You can also use the [**Analytics dashboard**](/administration/analytics) to identify the content the user owns, including documents in their personal folder.
  </Step>

  <Step title="Transfer or re-create any necessary schedules created by the user">
    To find the schedules created by the user, navigate to **Settings > Deliveries** and apply a filter for the user. You can navigate to the documents from this page and re-create the schedules to prevent disruptions.

    Alternatively, you can use the [transfer ownership API](/api/schedules/transfer-schedule-ownership) to programmatically transfer ownership.
  </Step>
</Steps>

After the user is removed, **Organization Admins** will still be able to find and access the user's **Personal** content using search or the [**Analytics dashboard**](/administration/analytics).

The **Settings > Deliveries** page will also list the user's schedules, but they will need to be re-created in order to run.


# Email-only users
Source: https://docs.omni.co/administration/users/email-only

Learn how email-only users work in Omni, including how they're created, managed, and used with deliveries and embedded analytics.

<Note>
  **Organization Admin** permissions are required to manage email-only users.
</Note>

An email-only user is a delivery recipient who doesn't have an Omni account. Unlike [Standard or Embed users](/administration/users), email-only users can't log in to Omni — they only receive scheduled [email deliveries](/share/deliveries/email).

## Creating email-only users

Omni automatically creates an email-only user when an [email delivery](/share/deliveries/email) recipient has an email that can't be matched to an existing Omni user. When the delivery is saved, Omni creates an account for the recipient to track delivery usage and related metadata. See [Resolving delivery recipients by email](/share/deliveries/email/personalization#resolve-recipients) for more information.

Email-only users can also be created programmatically using the [manage email-only user API](/api/schedule-recipients/manage-email-only-user) or the [bulk manage API](/api/schedule-recipients/bulk-manage-email-only-users).

After a new email-only user is created, you should immediately set [values for their user attributes](#user-attributes).

<Note>
  Email-only users aren't counted toward any [licenses](/administration/users/permissions#license-types).
</Note>

## Accessing email-only users in Omni

To view and manage email-only users, click **Settings > Users** and select the **Email-Only** tab. This tab only appears if there is at least one email-only user in your organization.

<img alt="The Email-Only tab in the Users settings page, displaying a list of email-only users with their names and schedule counts." />

The tab displays each user's **Name** and the number of **Schedules** they are included in.

## Inviting email-only users to your organization

Email-only users can be invited to join your organization as a [Standard user](/administration/users/invite). The user's attributes will be retained, and they'll remain recipients of schedules.

1. In the **Settings > Users > Email-only tab**, locate the user you want to work with.
2. Click the <Icon icon="ellipsis-vertical" /> in the same row as the user.
3. Click **Invite to Standard User**.

Omni will move the user to the **Standard** tab and display an <Badge>Invited</Badge> badge next to their display name.

## Deleting email-only users

<Warning>
  **Heads up!** Deleting an email-only user removes their email from all deliveries where they are a recipient.
</Warning>

1. In the **Settings > Users > Email-only tab**, locate the user you want to work with.
2. Click the <Icon icon="ellipsis-vertical" /> in the same row as the user.
3. Click **Remove Scheduler User**.

## Assigning user attributes

Email-only users can be assigned [user attributes](/administration/users/attributes) like any other user type. These attributes personalize the content they receive from [email deliveries](/share/deliveries/email).

For example, you could assign a `region` attribute to each email-only user and deliver a dashboard that filters to only their region's data.

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    The steps to assign attributes to email-only users are the same as for any other user. See [Assigning attributes to users](/administration/users/attributes#assigning-attributes-to-users) for more information.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [manage email-only user API](/api/schedule-recipients/manage-email-only-user) or [bulk manage API](/api/schedule-recipients/bulk-manage-email-only-users) to assign attributes to email-only users.
  </Tab>
</Tabs>

<Warning>
  **Make sure you set user attribute values for email-only users before their deliveries run!** If user attributes have default values, email-only users will inherit the defaults if values are not explicitly set. This can result in errors or no rows being returned. For attributes used in access filters, it can also expose unfiltered data in deliveries where they're a recipient.
</Warning>

## Next steps

* Learn more about [personalizing email deliveries with recipient attributes](/share/deliveries/email/personalization)
* See what's possible with [user attributes](/administration/users/attributes)
* Set up [email deliveries](/share/deliveries/email)


# User groups
Source: https://docs.omni.co/administration/users/groups

Assign permissions to users in bulk with user groups.

<Note>
  **Organization Admin** permissions are required to manage user groups.
</Note>

User groups let you manage permissions for multiple users at once instead of configuring each user individually.

<Frame>
  <img alt="Groups page showing a list of user groups with their name, label, member count, and group ID" />
</Frame>

## Creating user groups

<Tip>
  User groups can also be created through some [SCIM integrations](/administration/authentication).
</Tip>

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **Settings > Groups**.
    2. Click **New Group**.
    3. Enter a **Name** for the group. You can also add a description.
    4. Click **Save** to create the group.

    After the group is created, you'll be redirected to the group's **Members** tab where you can [add users](#adding-users-to-groups).
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Create user group API](/api/user-groups/create-user-group) API to programmatically create a user group:

    ```http theme={null}
    curl --request POST \
      --url https://{your-omni-org}.omniapp.co/api/scim/v2/groups \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "displayName": "Blob Sales",
      "members": [
        {
          "value": "9e8719d9-276a-4964-9395-a493189a247c"
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

## Managing group members

Users can be added to and removed from groups manually, through the [API](/api/user-groups) or some [SCIM integrations](/administration/authentication).

### Adding users to groups

<Tip>
  A user's group membership is also available as the `omni_user_groups` [user attribute](/administration/users/attributes#default-system-user-attributes), which can be used for data-level permissioning.
</Tip>

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    You can add users to groups from the group's **Members** tab or directly from a [user's **Groups** tab](#user-profile-group).

    From a group's **Members tab**:

    1. Navigate to **Settings > Groups**.
    2. Click the group you want to work with.
    3. In the group's **Members** tab, click **Add Members**.
    4. Search for and select users in the modal, then click **Add**.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update user group](/api/user-groups/update-user-group) API to programmatically add users to a user group:

    ```http theme={null}
    curl --request PATCH \
      --url https://{your-omni-org}.omniapp.co/api/scim/v2/groups/{userGroupId} \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
      ],
      "Operations": [
        {
          "op": "add",
          "path": "members",
          "value": [
            {
              "display": "blob.ross@blobsrus.co",
              "value": "9e8719d9-276a-4964-9395-a493189a247c"
            }
          ]
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

### Removing users from groups

When a user is removed from a group, they lose any [permissions that were granted through that group](#assigning-permissions-to-groups). Users can be re-added as group members if needed.

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    You can remove users from groups from the group's **Members** tab or directly from a [user's **Groups** tab](#user-profile-group).

    From a group's **Members tab**:

    1. Navigate to **Settings > Groups**.
    2. Click the group you want to work with.
    3. In the group's **Members** tab, locate the user you want to remove.
    4. Click **Remove from group**.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update user group API](/api/user-groups/update-user-group) to programmatically remove a user from a group:

    ```http theme={null}
    curl --request PATCH \
      --url https://docs.omniapp.co/api/scim/v2/groups/{userGroupId} \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
      ],
      "Operations": [
        {
          "op": "remove",
          "path": "members[value eq \"9e8719d9-276a-4964-9395-a493189a247c\"]"
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

### Managing a user's groups from their settings

In addition to managing user memberships from the group's **Members** tab, you can view and modify an individual user's group memberships from their [user settings](/administration/users/settings).

This is particularly useful when managing a user who is not yet a member of any groups, or when you need to modify multiple group memberships for a single user.

## Assigning permissions to groups

Access to connections, models, and content can be granted to an entire user group at once.

### Assigning connection/model access

Model roles control what actions user group members can perform on connections and the individual models associated with those connections.

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **Settings > Connections** and open the connection you want to work with.
    2. Click the **Permissions** tab and scroll to **Connection Roles**.
    3. In the **Groups** view, locate the group you want to grant permissions to.
    4. Use the **Access** dropdown to change the group's role. If [custom roles](/administration/users/custom-roles) are defined, they will display as options in the dropdown.

    <Frame>
      <img alt="Connection Roles section showing groups listed with their model, access level dropdown, and member count" />
    </Frame>
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Assign or update user group model role API](/api/user-group-model-roles/assign-or-update-user-group-model-role) to programmatically assign model roles to user groups. The role will apply to all members of the group.

    ```https theme={null}
    curl --request POST \
      --url https://blobsrus.omniapp.co/api/v1/user-groups/{userGroupId}/model-roles \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "connectionId": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
      "modelId": "7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
      "roleName": "QUERIER"
    }
    '
    ```
  </Tab>
</Tabs>

### Assigning content access

To grant access to documents and folders, share the content with the group. See [Content sharing](/share#users-and-user-groups) for details.

## Deleting user groups

<Warning>
  Deleting a user group is not reversible. Group members will lose any connection roles and content access that were granted through the group.
</Warning>

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **Settings > Groups**.
    2. Click the <Icon icon="ellipsis-vertical" /> icon in the user group's row.
    3. When prompted, click **Yes, Delete** to confirm.

    You can also delete a group by opening its **Settings** tab and clicking the **Delete** button.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Delete user group API](/api/user-groups/delete-user-group) to programmatically delete a user group:

    ```http theme={null}
    curl --request DELETE \
      --url https://{your-omni-org}>.omniapp.co/api/scim/v2/groups/{userGroupId} \
      --header 'Authorization: Bearer {token}'
    ```
  </Tab>
</Tabs>

## Next steps

* [Custom roles](/administration/users/custom-roles) - Define custom role variations to assign to groups
* [Content sharing](/share) - Learn how to share documents and folders with users and groups
* [Permissions](/administration/users/permissions) - Understand how connection roles and permissions work


# Testing access grants and permissions with user impersonation
Source: https://docs.omni.co/administration/users/impersonate

Use Omni's impersonation feature to view the application as another user and verify that access grants and permissions work correctly.

<Note>
  **Organization Admin** permissions are required to impersonate other users. Admins can't impersonate other admins.
</Note>

The **Impersonate user** feature is useful for testing that access grants work as expected.

## Impersonating users

<Steps>
  <Step>
    Navigate to **Settings > Users** and click on a user. **Note**: If testing an [access grant](/modeling/develop/data-access-control), the user must have a [user attribute value](/administration/users/attributes) that excludes them from the grant.
  </Step>

  <Step>
    At the bottom of the user's details page, click **Impersonate user**.
  </Step>

  <Step>
    Create a new workbook based on the connection you want to test. In this environment, you can verify what the user would and wouldn't have access to and adjust their permissions accordingly.
  </Step>
</Steps>

## Impersonating a pending invite

<Note>
  Only **pending** invites can be impersonated. Expired, declined, or revoked invitations are not eligible for impersonation.
</Note>

You can impersonate a user who has been invited but hasn't yet accepted their invite. This is useful for checking their permissions and validating dashboards before the user logs in for the first time.

If you create content - such as folders or saved documents - while impersonating a pending invite, that content will be owned by the invited user. If the user later declines the invite or the invite expires without being accepted, the content will be owned by a non-member, similar to what happens when a user is revoked.

When impersonating a pending invite, the impersonation banner displays a note indicating that the invite is still pending.

## Impersonate vs View As

Omni provides two ways to test content as another user:

* **Impersonate user** provides a full-session simulation where you experience Omni exactly as that user would. This includes all role-based restrictions, connection access controls, and permissions. Access it from **Settings > Users** by clicking on a user and selecting **Impersonate user** at the bottom of their details page.

* **[View As](/visualize-present/dashboards/view-as)** is a quick preview mode available in dashboard and workbook **File** menus. It applies the selected user's attributes to resolve dashboards, filters, and access grants, but does not simulate role-based restrictions or connection access. Use this for quick user attribute testing without leaving your current context.

Use **Impersonate** for comprehensive testing that includes role-based restrictions and connection access. Use **View As** for quick user attribute testing.


# Managing users
Source: https://docs.omni.co/administration/users/index

Invite, monitor, and manage users in your Omni organization.

## Requirements

**Organization Admin** permissions are required to view and manage users.

## The user list

The user list (**Settings > Users**) is the central hub for managing the people in your Omni organization. From here, you can invite new users, monitor login activity, and access individual user settings.

The user list is organized into tabs for different user types and statuses:

| **Tab**                 | **Description**                                                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Standard**            | Standard users in your organization.                                                                                                                            |
| **Embed**               | Users accessing Omni through an [embedded instance](/embed).                                                                                                    |
| **Email-Only**          | Users added to at least one [email delivery](/share/deliveries/email) who don't have an Omni account. See [Email-only users](/administration/users/email-only). |
| **Omni Support**        | Omni support team members with access to your instance.                                                                                                         |
| **Expired Invitations** | Invitations that were not accepted within the expiration window.                                                                                                |
| **Invite Requests**     | Pending requests from users who have requested access through the login page.                                                                                   |

### Standard and Embed users

The **Standard** and **Embed** tabs display the following columns:

| **Column**     | **Description**                                                                                                                                                                                                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**       | The user's full name.                                                                                                                                                                                                                                                                                                      |
| **Email**      | The user's email address.                                                                                                                                                                                                                                                                                                  |
| **Status**     | The user's current status: **Active**, **Invited**, or **Suspended**.                                                                                                                                                                                                                                                      |
| **Last login** | When the user last logged in, displayed as relative time (for example, "2 days ago"). Shows "Never" for users who haven't logged in. This column provides a quick way to monitor user engagement without navigating to the [Analytics dashboard](/administration/analytics), which offers more detailed activity tracking. |

### Email-only users

The **Email-Only** tab lists users who receive [email deliveries](/share/deliveries/email) but don't have an Omni account. Refer to [Email-only users](/administration/users/email-only) for details on how these users are created and managed.

**Note**: Email-only users aren't counted towards any [licenses](/administration/users/permissions#license-types).

## Managing individual users

To access the settings for a specific **Standard** or **Embed** user, hover over them in the user list and click the **Manage** button that appears. On the user's profile page, you can:

* Assign an [organization role](/administration/users/settings#organization-role) and [model access](/administration/users/settings#model-access)
* Set the user's [locale](/administration/users/settings#locale) and [query timezone](/administration/users/settings#query-timezone)
* Configure [user attributes](/administration/users/attributes) for data access control
* [Impersonate the user](/administration/users/settings#impersonating-a-user) to test their data access
* Set [AI credit limits](/administration/users/settings#ai-credit-limit) to control per-user AI usage

Refer to [User settings & impersonation](/administration/users/settings) for details.

## User management tasks

<CardGroup>
  <Card title="Invite users" icon="envelope" href="/administration/users/invite">
    Send invitations, manage requests, and re-invite users with expired invitations.
  </Card>

  <Card title="Assign permissions" icon="key" href="/administration/users/permissions">
    Control access to connections and content with connection roles and model permissions.
  </Card>

  <Card title="Define custom roles" icon="shield-halved" href="/administration/users/custom-roles">
    Create variations of base roles with specific permission restrictions for users, groups, and connections.
  </Card>

  <Card title="Organize users into groups" icon="users" href="/administration/users/groups">
    Create groups to manage permissions and content access at scale.
  </Card>

  <Card title="Set up user attributes" icon="tag" href="/administration/users/attributes">
    Map user-specific variables to control data access, route connections, and personalize content.
  </Card>

  <Card title="Impersonate users" icon="user-secret" href="/administration/users/impersonate">
    Experience a full session as another user to test all permissions and role-based restrictions.
  </Card>

  <Card title="Revoke membership" icon="user-minus" href="/administration/users/delete">
    Remove a user from your organization and understand the impact on their content and schedules.
  </Card>

  <Card title="Monitor usage" icon="chart-line" href="/administration/analytics">
    Track user activity, content engagement, and more with the Analytics dashboard.
  </Card>
</CardGroup>


# Inviting users
Source: https://docs.omni.co/administration/users/invite

Send invitations, manage invitation requests, and re-invite users with expired invitations.

## Requirements

**Organization Admin** permissions are required to invite users.

## User invitation requests

If the [**New user invitations**](/administration/settings#general) setting is enabled, users can request an invitation from your organization's login page.

### Stale invitation requests

If you see invitation requests from users who are already active members of your organization, you can safely dismiss these requests. These stale requests can occur when a user submits an invitation request and then joins the organization through SSO or SCIM provisioning before an Organization Admin acts on the request.

To dismiss a stale invitation request:

1. Navigate to **Settings > Users**.
2. Click the **Invitation requests** tab.
3. Find the request from the user who is already a member.
4. Click **Dismiss** next to the request.

If you attempt to invite a user who is already an active member, you'll receive an error indicating the user already exists in the organization.

## Inviting users

<Note>
  Once an invite is sent, new users have 7 days to log into Omni. The invite will automatically expire after this time and the user will have to be [re-invited](#re-inviting-users).
</Note>

If the **New user invitations** setting isn't enabled or you need to send a one-off invite, you can manually invite new users.

1. Navigate to **Settings > Users**.
2. Click **Invite**.
3. In the **Email** field, add the emails of the users you want to invite as a comma-separated list. For example:
   ```txt theme={null}
   blobby@blobsrus.com,blob.ross@blobsrus.com
   ```
4. Click **Send invitations**.

After the invitation is sent, the user will appear in the **Users** list with an **Invited** badge and you'll be able to [assign permissions](/administration/users/settings) to the user:

<img alt="" />

## Re-inviting users

If a user hasn’t accepted their invitation by logging in to Omni or needs a new one, you can revoke and re-send their invite:

1. Navigate to **Settings > Users**.
2. In the **Users** list, find the user with the **Invited** badge.
3. Click **Manage** next to their name.
4. At the bottom of the user's profile page, click **Revoke invitation**.
5. Return to **Settings > Users** and click **Invite**.
6. In the **Email** field, add the user's email address.
7. Click **Send invitations**.

The user will receive a new invite email and appear in the **Users** list with a refreshed **Invited** badge.


# Managing data access with connection permissions
Source: https://docs.omni.co/administration/users/permissions

Assign and test database connection, data model, and content-level permissions to control user access across your Omni instance.as asd as das dw

User permissions are first set on the individual database connection then more fine-tuned permissions can be assigned to individual users or groups within the organization, streamlining the management process.

## Connection permission basics

<AccordionGroup>
  <Accordion title="Who can define connection permissions?">
    **Organization Admins** and users who have **Connection Admin** permissions for a connection can define connection permissions.
  </Accordion>

  <Accordion title="What are the connection roles?">
    Omni has six base connection roles, ordered from the **least** permissive to the **most** permissive:

    * No access
    * Viewer
    * Restricted Querier
    * Querier
    * Modeler
    * Connection Admin

    Organizations can also create [custom roles](/administration/users/custom-roles) that inherit a base role's core capabilities while restricting specific granular permissions, such as a **Querier** role without the **Upload data** permission.

    For the specifics of what each base role can and cannot do, refer to the [Permissions reference](/administration/users/permissions-reference).
  </Accordion>

  <Accordion title="Can default permissions be applied to a connection?">
    Yes. Using the **Base access** setting, you can assign the minimum role users will have for the models in the connection. More permissive roles can be set in the connection's **Model access** section. **Note**: The base role will override a less permissive role set in the **Model access** section.
  </Accordion>

  <Accordion title="Can permissions be set at the model level?">
    Yes! In the **Model access** section, you can assign granular permissions to users and user groups for specific models.

    <Tip>
      A connection's **base role** will override a less permissive role set in the **Model access** section.
    </Tip>
  </Accordion>

  <Accordion title="What permissions should I set to do [thing]?">
    It depends on what you want to achieve! Do you want to lock everything down, or only restrict access for some things? Or perhaps it varies by team or dataset?

    In the [**Common permissions scenarios guide**](/administration/users/permissions-scenarios), we've outlined some common scenarios and how to use permissions to achieve the desired result. For example, limiting access to folders based on the team a user belongs to.
  </Accordion>

  <Accordion title="Do connection permissions impact a user's license type?">
    Yes. Refer to the [User license types](#license-types) section for more information.
  </Accordion>
</AccordionGroup>

## Defining permissions for a connection

<Note>
  **Organization Admin** or **Connection Admin** permissions for the connection are required to define connection permissions.
</Note>

To access the connection's **Permissions** tab:

1. Click **Settings > Connections**.
2. Click the connection.
3. Click the connection's **Permissions** tab. On this page, you can define default access for the connection (**Base access role**) and assign permissions to users and user groups for specific models (**Model access**). If [custom roles](/administration/users/custom-roles) are defined, they will be included as options in these sections.

**Not sure what permissions to set?** Check out the [Common permissions scenarios guide](/administration/users/permissions-scenarios) to learn what permissions to set in specific scenarios, such as restricting access to datasets based on team.

## Testing data access

As you assign connection roles to users, you can [impersonate them](/administration/users/impersonate) to test what users can see. This can be helpful in preemptively surfacing access warnings, which will display when users attempt to access specific types of content.

See the [Access warnings](/share#access-warnings) guide to learn what an access warning is and how to resolve it.

## License types

Omni's licensing structure has three tiers: Viewer, Standard, and Administrator/Developer.

To calculate a user's license type, Omni looks at:

* The user's **highest Connection role** across all connections, **and**
* Whether the user is an **Organization Administrator**. These users will have an **Administrator** license by default.

The following table shows how license types match to connection roles. Refer to the [Permissions reference](/administration/users/permissions-reference) for more information about what individual connection roles can do in Omni.

| License type        | Connection role        | Permissions                                                                                                                                                                                              |
| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **None**            | **No Access**          | ❌ Cannot view content built on the connection<br />❌ Cannot query (topics)<br />❌ Cannot use SQL queries<br />❌ Cannot modify shared model files<br />❌ Cannot modify connection settings                |
| **Viewer**          | **Viewer**             | ✅ Can view dashboards built on topics<br />❌ Cannot query topics<br />❌ Cannot use SQL queries<br />❌ Cannot modify shared model files<br />❌ Cannot modify connection settings                          |
| **Standard**        | **Restricted Querier** | ✅ Can create, edit, and view workbooks and dashboards<br />✅ Can query topics (UI and AI)<br />❌ Cannot use SQL queries<br />❌ Cannot modify shared model files<br />❌ Cannot modify connection settings |
| **Standard**        | **Querier**            | ✅ Can create, edit, and view workbooks and dashboard<br />✅ Can query topics (UI and AI)<br />✅ Can use SQL queries<br />❌ Cannot modify shared model files<br />❌ Cannot modify connection settings     |
| **Admin/Developer** | **Modeler**            | ✅ Can create, edit, and view workbooks and dashboards<br />✅ Can query topics (UI and AI)<br />✅ Can use SQL queries<br />✅ Can modify shared model files<br />❌ Cannot modify connection settings       |
| **Admin/Developer** | **Connection Admin**   | ✅ Can create, edit, and view workbooks and dashboards<br />✅ Can query topics (UI and AI)<br />✅ Can use SQL queries<br />✅ Can modify shared model files<br />✅ Can modify connection settings          |

## Custom roles

Custom roles allow organizations to create variations of base roles with specific permission restrictions — for example, a **Querier** role without the **Upload data** permission. Custom roles can be assigned to users, groups, and as the base access on a connection.

For details on creating and managing custom roles, see [Custom roles](/administration/users/custom-roles).


# Connection and model permissions reference
Source: https://docs.omni.co/administration/users/permissions-reference

A detailed reference of all connection and model role permissions in Omni, covering document, query, and modeling capabilities.

<Tip>
  Refer to the [Assigning permissions guide](/administration/users/permissions) to learn how to assign permissions to users.
</Tip>

## Documents

This section describes the actions different connection/model roles can take regarding [documents](/content/develop).

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Permission</th>
      <th>No access</th>
      <th>Viewer</th>
      <th>Restricted Querier</th>
      <th>Querier</th>
      <th>Modeler</th>
      <th>Connection Admin</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[Create documents](/content/develop)</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>View document names on homepage</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

## Workbooks

This section describes the actions different connection/model roles can take in the [workbook](/analyze-explore) section of a document.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Permission</th>
      <th>No access</th>
      <th>Viewer</th>
      <th>Restricted Querier</th>
      <th>Querier</th>
      <th>Modeler</th>
      <th>Connection Admin</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Access workbooks</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>[Upload CSV & XLSX files](/analyze-explore/data-input-csvs)</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Run topic-based queries</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Run all queries</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Create & run [SQL queries](/analyze-explore/sql)</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>View SQL query results</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌\*</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Use [functions & formulas](/analyze-explore/calculations)</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Create & edit [visualizations](/visualize-present/visualizations/types)</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Use [AI query](/ai/queries) or AI [spreadsheet calculations](/analyze-explore/calculations#ai-generated)</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

\* Can be enabled via the **View SQL** granular permission on a [custom Restricted Querier role](/administration/users/custom-roles).

## Dashboards

This section describes the actions different connection/model roles can take in the [dashboard](/visualize-present/dashboards) section of a document.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Permission</th>
      <th>No access</th>
      <th>Viewer</th>
      <th>Restricted Querier</th>
      <th>Querier</th>
      <th>Modeler</th>
      <th>Connection Admin</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Access dashboards</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>[Create & edit dashboards](/visualize-present/dashboards)</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>View topic-based charts</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>View non-topic based charts</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>[Download](/visualize-present/dashboards/download)</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Create [schedules & alerts](/share/deliveries)</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Use [filters & controls](/visualize-present/dashboards/filters)</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Use drill functionality</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

## Modeling

This section describes the actions different connection/model roles can take when interacting with the connection's [model](/modeling).

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Permission</th>
      <th>No access</th>
      <th>Viewer</th>
      <th>Restricted Querier</th>
      <th>Querier</th>
      <th>Modeler</th>
      <th>Connection Admin</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Stage workbook model changes</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Access the [Content Validator](/modeling/develop/content-validator)</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Stage [shared data model](/modeling) changes using a branch</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Directly edit the [shared data model](/modeling)</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>[Refresh schema](/modeling/develop/schema-refreshes) (single model connection)</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>[Refresh schema](/modeling/develop/schema-refreshes) (multi-model connection)</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Rename a shared model or shared extension</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Create a shared extension model</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Edit connection settings</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

## Branches

This section describes the actions different connection/model roles can take when interacting with [branches](/content/develop/branch-mode).

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Permission</th>
      <th>No access</th>
      <th>Viewer</th>
      <th>Restricted Querier</th>
      <th>Querier</th>
      <th>Modeler</th>
      <th>Connection Admin</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>View branches</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Create branches</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Merge branches</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

## Administration

This section describes the actions different connection/model roles can take regarding the connection's settings.

**Note**: Managing users, such as inviting them to your Omni instance, is handled by **Organization Admins**.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Permission</th>
      <th>No access</th>
      <th>Viewer</th>
      <th>Restricted Querier</th>
      <th>Querier</th>
      <th>Modeler</th>
      <th>Connection Admin</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Manage connection permissions</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Manage connection settings</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>


# Common user access scenarios
Source: https://docs.omni.co/administration/users/permissions-scenarios

Learn how to implement user permissions to achieve different levels of access in Omni.

Omni's user roles and the permissions they contain control your users' entire experience in Omni, from what they see in the app to the data they can access and build upon.

In this guide, we'll show you how to implement permissions to achieve different levels of access in your own Omni instance.

<Check>
  If there's a scenario you want to see here, reach out to Omni support.
</Check>

## Requirements

To follow this guide, you'll need familiarity with user roles in Omni, including [content roles](/share#content-access-permissions) and [connection roles](/administration/users/permissions).

## Before you begin

Before you dive in, we recommend aligning with your team on what levels of access different groups should have in Omni - both for dashboards and for the data behind them.

Think about the sensitivity of the data in your connected databases. If it includes things like employee details or other PII, you’ll want to make sure only the right people can directly query that data.

Also consider whether your team will be building dashboards that include sensitive or internal-only information. If so, it’s important to map out folder and document permissions early so you can keep content access aligned with your organization’s needs.

## Fully locked down

In this scenario, users shouldn't:

* Be able to view existing dashboards and/or workbooks
* Have access to data in your connections (databases)

This type of setup is common when [externally embedding Omni](/embed), as it ensures that data access is tightly controlled.

To achieve this, set the [organization's **default content access role**](/administration/content-permissions) and each [connection's **base access role**](/administration/users/permissions#defining-permissions-for-a-connection) to **No access**. This approach ensures that your users won’t have access to any data by default and anything they need access to would be granted explicitly after they were provisioned.

## Limited access

<AccordionGroup>
  <Accordion title="Restrict access to specific datasets">
    In some cases you may want to allow users to only access specific datasets. There are a few ways to accomplish this:

    <Steps>
      <Step title="Set the connection's base access role to Restricted Querier">
        This will limit users to data in the connection that has been pre-joined and curated into topics.
      </Step>

      <Step title="Define access grants">
        [Access grants](/modeling/develop/data-access-control) allow you to granularly restrict access to specific fields, topics, or views using [user attributes](/administration/users/attributes). Only users with the required user attribute value will be able to access the restricted data.

        <Tip>
          When using this approach, you'll also need to set the users' **connection role** to **Restricted Querier** or below to limit the ability to query raw SQL, as this would allow users to bypass `access_grants` restrictions.
        </Tip>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Restrict folder access by team">
    In this scenario, you want your users to only be able to access content in the folders you specify. They won't be able to access any existing dashboards or workbooks outside these folders.

    To achieve this, you should:

    * **Set the [organization's default content role](/administration/content-permissions) to No access**. This ensures that, by default, users won't have access to content unless it's directly shared with them.
    * **Utilize [user groups](/administration/users/groups) to manage folder and document access**. This approach allows you to share folders and documents with the group instead of individual users. You can easily add and remove members as needed, ensuring each user always has the correct level of access.
  </Accordion>

  <Accordion title="Restrict tables & topics by team or user">
    In this scenario, you want to grant different teams or users varying levels of access to a table or a topic. This can be accomplished in a few ways:

    * **Utilize [user groups](/administration/users/groups) to define different access levels**. For example:

      * `Group A` has **Querier** permissions, giving them access to all views and fields in the connection's models
      * `Group B` has **Restricted Querier** permissions, giving them access only to topics in the connection's models

    * **Individually define [connection roles](/administration/users/permissions#defining-permissions-for-a-connection) at the user level**. If you set the connection's base access role to something more restrictive - like **No Access** or **Viewer** - you can then individually grant users less restrictive permissions. For example, `User A` could have **Querier** permissions while `User B` has **Restricted Querier** permissions.

    * **Define [access grants](/modeling/develop/data-access-control) for topics and views**. Access grants allow you to apply additional restrictions to individual topics and views. This can be implemented with [user attributes](/administration/users/attributes) or through [user groups](/administration/users/groups), which can be more straightforward to maintain.

    * **Hide topics or views in workbooks.** When a topic or view's [`hidden` parameter](/modeling/topics/parameters/hidden) is set to `true`, it will no longer be visible to users in the workbook. The topic or view can still be referenced by the model, but users will be unable to select it.
  </Accordion>

  <Accordion title="Allow Viewers to see raw SQL dashboards">
    When a tile on a dashboard is backed by raw SQL - that is, the underlying query was built with SQL using the [Advanced Editor](/analyze-explore/sql) - users with the **Viewer** connection role may run into issues when trying to view the dashboard. These users will see something like this:

    <img alt="" />

    This occurs because, despite having the **Content role** needed to view the dashboard, the query is built on data outside of their **Connection role** permissions. Connection **Viewers** can't view data built outside of topics, which limits their ability to inadvertently view data in the connection they're not supposed to have access to.

    **In this scenario, you can enable [AccessBoost](/share#boosting-permissions-with-accessboost) for the document or folder**. This will allow connection **Viewers** to view the raw SQL content. You can then manage access to the dashboard using the [document's content permission settings](/share#assigning-access-roles-to-content).

    <Warning>
      **Before using AccessBoost**, refer to the [AccessBoost guide](/share#boosting-permissions-with-accessboost) to make sure you understand how this feature works and the impact it can have.
    </Warning>
  </Accordion>
</AccordionGroup>


# Troubleshooting user permissions
Source: https://docs.omni.co/administration/users/permissions-troubleshooting

Troubleshoot the most common permission issues.

Omni offers a powerful set of user roles and the permissions to control your users' experience, but sometimes understanding all the nuances of permissions can cause confusion.

<Check>
  If there's a troubleshooting question or scenario you want to see here, reach out to Omni support.
</Check>

<AccordionGroup>
  <Accordion title="Can't display chart dashboard error">
    <Steps>
      <Step title="What it looks like">
        Restricted Queriers and Viewers see **Can't display chart** errors when viewing a dashboard.
      </Step>

      <Step title="Why it happens">
        This is typically due to Omni enforcing [connection roles](/administration/users/permissions) when content in a dashboard is built outside of a [topic](/modeling/topics).
      </Step>

      <Step title="How to fix it">
        In this video, we explain what's happening and how to resolve it using Omni's [AccessBoost](/share#boosting-permissions-with-accessboost) feature.

        <iframe title="Resolve 'Can't display chart' dashboard errors" />
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="No option to view workbook">
    <Steps>
      <Step title="What it looks like">
        Viewers don't have the option to view a workbook in a document.
      </Step>

      <Step title="Why it happens">
        By default, the workbooks are not accessible to [Viewers](/administration/users/permissions). Omni does this because Viewers don't have the ability to build in workbooks.
      </Step>

      <Step title="How to fix it">
        <AccordionGroup>
          <Accordion title="Enable document ability (organization-level)">
            Organization Admins can change this default behavior in **Settings > General > Content permissions** with the **Viewers can see workbook** setting. Click the toggle in the **Ability** column:

            * Enabling the **Ability** toggle allows the setting to be enabled or disabled on individual documents
            * **Optional**: Changing the **Default** option to **On** enables the setting by default on documents

              <img alt="" />
          </Accordion>

          <Accordion title="Enable for individual documents">
            Workbook access for Viewers can also be enabled on individual documents in **Share > Settings** and enabling **Viewers can see workbook**.

            **Note**: This requires the [organization-level version of this setting](/administration/content-permissions) to be enabled.

            <img alt="" />
          </Accordion>
        </AccordionGroup>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="You don't have access to this tab workbook error">
    <Steps>
      <Step title="What it looks like">
        Users see **You don't have access to this tab** messages when viewing a workbook tab:

        <img alt="" />
      </Step>

      <Step title="Why it happens">
        Similar to not being able to see data on a dashboard, this happens when one of the workbook tabs:

        * Is built outside of a [topic](/modeling/topics), and
        * A user has [permissions](/administration/users/permissions) of Viewer or Restricted Querier, which are only allowed to see tabs in a workbook or tiles in a dashboard built with topics
      </Step>

      <Step title="How to fix it">
        To resolve the error, the query associated with the tab must be rebuilt using a topic.

        Omni's [AccessBoost](/share#boosting-permissions-with-accessboost) feature can be enabled, which would ignore data permissions usually enforced by [connection roles](/administration/users/permissions), but this would only show the data on the dashboard not the query in the workbook.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Unable to view specific topics">
    <Steps>
      <Step title="What it looks like">
        User is unable to view a specific topic.
      </Step>

      <Step title="Why it happens">
        [Topic](/modeling/topics) visibility is primarily controlled by [access grants](/modeling/models/access-grants), which are a permissions systems configured in the [model file](/modeling/models) and then called as a [`required_access_grant`](/modeling/topics/parameters/required-access-grants) within a topic to enforce which users are able to see a given topic.
      </Step>

      <Step title="How to fix it">
        Access grants can be built to evaluate [user attributes](/administration/users/attributes) or [user groups](/administration/users/groups) to determine which users will return a true value for the access grant.

        Access grants and user groups are defined within Omni Settings and often set for a given user as part of a login process in Omni.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Restricted Queriers are unable to add topic joins">
    <Steps>
      <Step title="What it looks like">
        While in a workbook, a Restricted Querier is denied access to adding joins to a topic.
      </Step>

      <Step title="Why it happens">
        [Restricted Queriers](/administration/users/permissions) are only able to build in a workbook using [topics](/modeling/topics), which scopes their access to the data available in the database to the joins, filters and permissions configured in topics.

        Adding another table into a topic would effectively be bringing net new data into a topic, which is outside of the permissions scope for a Restricted Querier.
      </Step>

      <Step title="How to fix it">
        If you want a user to be able to add joins to a topic, elevate their permissions to **Querier** or higher.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Ownership changes after moving document">
    <Steps>
      <Step title="What it looks like">
        A user is no longer the owner of a document after moving the document to a shared folder.
      </Step>

      <Step title="Why it happens">
        At a high level, the parent folder dictates the inherited permissions of the folders and dashboards contained in the parent folder. This means that each child folder or dashboard can have the same or higher permissions as the parent folder.

        Additionally, when documents are moved to a shared folder or subfolder, their ownership will change to the user who owns the folder.

        Refer to the [Access inheritance guide](/share#inheriting-access-roles) for more information.
      </Step>

      <Step title="How to fix it">
        To retain ownership of a document, users should:

        * Keep the document in their personal folders, or
        * Move the document only to shared folders that they own
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Locked filters for Viewers or Embed users">
    <Steps>
      <Step title="What it looks like">
        Viewers or Embed users are unable to change filters on a dashboard.
      </Step>

      <Step title="Why it happens">
        Often when a dashboard has a filter applied, a locked filter is the result of an [access filters](/modeling/topics/parameters/access-filters) being enforced.

        Access filters are used to enforce row-level security - for example, in an [embedded](/embed) Omni instance that is built on a multi-tenant database.

        Access filters are created in a [topic file](/modeling/topics) by defining a field to be filtered and then reading the value of a specified [user attribute](/administration/users/attributes). All values except the one specified in the access grant will be filtered out - think of this as a SQL `WHERE` clause that can't be removed.
      </Step>

      <Step title="How to fix it">
        * Remove the access filter, or
        * Add a `value_for_unfiltered` parameter to the access filter. Users with the specified user attribute will not have the filter applied, **allowing them to see all data for the field**.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>


# Managing a user's settings
Source: https://docs.omni.co/administration/users/settings

Learn how to access the settings for individual users and test data access through impersonation.

<Note>
  Looking to change settings for your *own* account? See [Your account](/administration/users/your-account) for the self-service settings available from the profile menu.
</Note>

## Requirements

**Organization Admin** permissions are required to modify a user's settings.

## Accessing user settings

To access the settings for an individual user:

1. Navigate to **Settings > Users**.
2. In the user list, hover over the user you want to modify.
3. Click the **Manage** button that appears.

On the user's profile page, you'll be able to assign permissions to the user, set the user's locale and query timezone, and set user attribute values.

### Organization role

The **Organization role** setting controls the user's permissions to manage the organization. This includes the ability to invite and manage other users, manage database connections, and modify [organization settings](/administration/settings).

**Not sure what permissions to set?** Check out the [Common permissions scenarios guide](/administration/users/permissions-scenarios) to learn what permissions to set in specific scenarios, such as restricting access to datasets based on team.

### Locale

The **Locale** setting defines the language of the Omni app interface for this user.

* If a user-level locale is set, it controls the language this user sees in the app.
* If no user-level locale is set, the user inherits the organization's default locale.

For more information about organization and user-level localization, see [Localization settings](/administration/localization).

### Query timezone

The **Query timezone** setting defines the timezone used for query conversion, if user-specific timezones are enabled for a connection. Refer to the [Timezone settings guide](/connect-data/timezones) for more information.

### Personal content

When enabled, the **Allow personal content** setting allows users to save content to their [personal **My documents** folder](/content/navigate). This setting is enabled by default.

When disabled, **My documents** will be hidden in the [sidebar](/administration/settings/sidebar) and content operations will default to the organization scope.

### AI credit limit

The **AI credit limit** setting allows you to set a per-user credit limit that controls how many AI credits the user can consume. This setting provides an additional layer of control on top of [organization-level credit limits](/ai/settings/usage).

The control displays the user's effective limit — either their individual override or the organization default when no user-level limit is set. Click **Edit** to configure the limit:

* **Set a cap** — Define a specific credit limit in the **Credit limit** field
* **Unlimited** — Enable to allow unrestricted AI usage regardless of organization settings
* **Unset** — Remove any user-level override so the user inherits the organization's credit controls on save

User-level limits override organization-wide settings, allowing you to grant specific users higher limits or restrict usage on a per-user basis.

For more information about AI credits and organization-level credit controls, see [Managing AI credit usage](/ai/settings/usage).

### User attributes

User attributes, managed in the user's **Attributes** tab, allow you to map user-specific variables to operations in Omni, such as querying, dashboards, and controlling data access. Refer to the [User attributes guide](/administration/users/attributes) for more information and examples.

### Groups

The **Groups** tab lists the [user groups](/administration/users/groups) that the user is a member of. You can modify the user's group memberships directly from this tab:

* Click **Add to groups** to open a picker showing all available groups. Groups the user already belongs to are shown as disabled.
* Click **Remove from group** in a group's row to remove the user from that group. You will be prompted to confirm the removal.

For more information about managing group memberships and assigning permissions to groups, see [User groups](/administration/users/groups).

### Model Access

[Model permissions](/administration/users/permissions) determine the level of access the user has to individual models. Click on a model in the list to view more information about the user's role and abilities:

<Frame>
  <img alt="Alt text" />
</Frame>

Use the **User role** dropdown to change the user's model role. If [custom roles](/administration/users/custom-roles) are defined, they will also appear in the dropdown list. The **Resolved Role** and **User Abilities** sections will automatically update based on your selection.

## Impersonating a user

See [Impersonating users](/administration/users/impersonate) for more information.

## Resetting introductions

If a user needs a refresher on Omni's latest features, you can use the **Reset introductions** button at the bottom of their settings page.

This will reactivate any previously dismissed feature introductions - specifically, the tooltips that highlight updates - that display in the app:

<img alt="" />


# Managing your account settings
Source: https://docs.omni.co/administration/users/your-account

Configure your personal Omni settings, including appearance, query timezone, and personal API tokens.

Your personal Omni settings are split between two places:

* The **profile menu**, opened by clicking your avatar in the top-right corner of Omni.
* The **Your Account** page, opened by clicking **Manage account** in the profile menu, which controls your account details, query timezone, personal API tokens, personal AI memory, and AI credit usage for the current period.

<Note>
  Looking to change settings for *another* user? Organization Admins can configure user-level settings on behalf of other users from **Settings > Users**. See [User settings & impersonation](/administration/users/settings).
</Note>

## Appearance

The **Appearance** section of the profile menu controls how Omni looks for you. Changes apply only to your account.

### Light, dark, and auto mode

<Note>
  Available display modes are controlled by the [**Theme > Allow user color scheme** setting](/administration/themes/application#color-scheme-light-and-dark-mode).
</Note>

Use the light / auto / dark toggle to switch between light mode, dark mode, or automatically following your system setting.

### Themes

Applies a preset theme to your Omni experience. The following themes are available:

* **Default** - The standard Omni look.
* **Omni 1984** - A 1-bit, black-and-white aesthetic inspired by the original Macintosh System 1 / System 6 interface.
* **Omni '98** - A Windows 98 desktop aesthetic.

To apply a theme, open the profile menu and select the theme from the dropdown in the **Appearance** section. Changes take effect immediately and only apply to your account.

### Chat panel side

Controls which side the AI chat panel appears on when viewing a chat and a document or dashboard side-by-side (split view). See [Omni AI Chat](/ai/chat) for more information about the split-view chat experience.

## Session recording

<Note>
  This setting requires **Session recording** to be enabled in [**Settings > General**](/administration/settings#support-settings).
</Note>

The **Enable session recording** toggle in the profile menu allows Omni support to access replays of your sessions when you encounter bugs or errors. This is useful when working with support to reproduce an issue.

## Manage your account settings

Click **Manage account** in the profile menu to open the **Your Account** page. The top of the page displays read-only details about your account:

* **Name**
* **Email**
* **Created** - The date your Omni account was created.

### AI memory

<Note>
  The **Omni Agent > AI memory** [AI setting](/ai/settings/features#ai-memory) must be enabled to use this feature. Additionally, user memory is not supported for embedded instances.
</Note>

Stores information about yourself - such as your team, preferred presentation format, region, and so on - to help the Omni Agent provide more personalized responses. See [Saving information to memory](/ai/chat#memory) for more information.

### Locale

Sets the language and regional formatting for dates, numbers, and other localized content throughout the application. See the [Localization guide](/administration/localization) for more information.

### Query timezone

Controls the timezone used when running your queries, if user-specific timezones are enabled for a connection:

* If set to **Use default timezone**, your queries run in the timezone configured on the database connection.
* If set to a specific timezone, queries that can be adjusted will run in the timezone you select.

See the [Timezone settings guide](/connect-data/timezones) for more information about how connection and user-level timezones interact.

### Personal API tokens

<Note>
  [Personal Access Tokens must be enabled](/api/authentication#create) by an **Organization Admin** before you can generate a token.
</Note>

Allows you to generate a Personal Access Token (PAT) for use with the Omni API. PATs are scoped to your user and inherit your permissions. You can also rotate your token for zero-downtime updates. See [API authentication](/api/authentication#token-types) for more information, including [how to rotate your PAT](/api/authentication#rotate).

## AI credit usage

<Note>
  You won't see this section if your organization uses a [custom model provider](/ai/settings/model-providers) or, if in an embedded instance, the [**Show AI credit usage on profile** setting](/embed/admin/security#user-credit-usage) is disabled.
</Note>

Displays information about your AI usage for the current period, including your credit usage and when it resets.

If your organization set [per-user credit limits](/ai/settings/usage#user-level-credit-controls), you'll also see the credit limit that applies to your account.

## Connected services

Allows you to manage your personal connections to [AI integrations](/integrations/ai). Use this section to connect and disconnect your user accounts. Some integrations (like Slack) are available to all users, while others require organization-level configuration before you can connect your account.

Once an integration is connected, you can temporarily turn its tools on or off for your chat sessions from the connector menu in the [Omni Agent](/ai/chat) without disconnecting the account.


# Omni Agent
Source: https://docs.omni.co/ai/chat

Explore your data using conversational AI in a standalone chat experience.

The Omni Agent provides a standalone, conversational interface for exploring your data. Ask questions, generate queries, and visualize results without needing to work directly in a workbook.

## Requirements

To use the Omni Agent, you'll need:

* **Restricted Querier**, **Querier**, **Modeler**, or **Connection Admin** permissions
* **To verify that the following settings in [AI Hub > General > Features](/ai/settings/features) are enabled**. These settings are enabled by default, but Organization Admins can modify them as needed.
  * **Omni Agent** - Required to use the Omni Agent
  * **Omni Agent > Chat** - Required to access the chat interface
  * **Omni Agent > Chat > Chat in navigation** - Required to show the standalone chat in the main [sidebar](/administration/settings/sidebar)

## Accessing the Omni Agent

To access the Omni Agent, click **Omni Agent** in Omni's main [sidebar](/administration/settings/sidebar). The chat interface opens in a dedicated page where you can begin asking questions about your data.

<Note>
  The  sidebar item may display differently or not at all if your organization uses a [custom sidebar](/administration/settings/sidebar).&#x20;
</Note>

## Capabilities

The Omni Agent can:

* **Answer natural-language questions** about your data
* **Search existing dashboards** for tiles and visualizations that already answer your question before generating a new query
* **Generate queries** based on your prompts, routed through [topics](/modeling/topics) or any view in your model
* **Create visualizations**, including [KPI tiles](/visualize-present/visualizations/types/kpi), directly from your prompts
* **Create dashboards** based on the queries and visualizations in the session
* **Create [routines](/ai/routines)** that run a saved prompt on a schedule and deliver the result by email or Slack, and find and open your existing routines by describing them in plain language
* **Accept files and images as context**:
  * **Upload files** including text and Markdown files to provide additional context alongside your queries
  * **Attach images** by pasting from your clipboard to provide visual context for your questions
* **Save information about you to memory** to provide more personalized responses
* **Search the Omni docs** to answer questions about how to use Omni

### Getting help

If you're stuck and can't remember how to do something in Omni, ask the Omni Agent. Questions like *"How do I do \[thing]?"* will prompt the agent to search the official Omni docs and provide you with an answer, all without leaving your Omni workflow.

You can also directly tell the agent to search the docs when researching the answer to your question.

<Note>
  **Working in an embedded context?** If you have the **Hide Omni watermark** setting enabled to provide a fully white-labeled experience, the AI doc search feature will respect it. Omni doc links will not be returned in chat, even if explicitly requested.
</Note>

## Tuning responses

You can shape how the Omni Agent responds by scoping which data it draws from, controlling the context it can access, and choosing which underlying AI model handles your prompts.

### Scoping responses

The Omni Agent uses pickers to scope responses to specific connections, models, and topics. Click the <Icon icon="circle-plus" /> button at the bottom of the chat box to open the pickers:

<Frame>
  <img alt="Connection, model, and topic picker in Omni's chat interface" />
</Frame>

Up to three pickers can display in the chat interface:

* **Connections** - Lists the connections you have access to. Only displays if more than one connection is available. This setting can't be changed if you're using the chat in a workbook or dashboard.
  <Tip>
    Organization Admins can configure a default connection in [**AI Hub > Setup > Features**](/ai/settings/features#default-connection) to set which connection the Omni Agent opens with by default.
  </Tip>
* **Models** - Lists the available models in the selected connection. Only displays if:
  * The connection has more than one model, **and**
  * At least one topic in the model is accessible. This could mean that the model's [`ai_chat_topics`](/modeling/models/ai-chat-topics) is unset, making all topics accessible, or that it specifies at least one topic:
    ```yaml theme={null}
    ai_chat_topics: [ Products ]
    ```
* **Topics** - Lists the available topics in the model. Only displays if at least two topics in the model are accessible. This could mean that the model's [`ai_chat_topics`](/modeling/models/ai-chat-topics) is unset, or that it specifies at least two topics:
  ```yaml theme={null}
  ai_chat_topics: [ Products, Orders ]
  ```

#### Scoping topics

If a prompt is entered and a topic isn't selected - meaning that **Auto-select a topic** is selected in the topic picker - the AI will attempt to select the most relevant topic.

To scope the AI's response to a specific dataset, use the pickers to select a specific topic or composite topic. The AI will remain "locked" to the selected topic until the selection is changed.

Additionally, the picker menus won't display when a model only has one AI-accessible topic. If a connection has one model with a single AI-accessible topic - determined by the value of the model's [`ai_chat_topics`](/modeling/models/ai-chat-topics) parameter - the AI will be scoped only to that topic and the pickers will not display.

### Managing AI integrations

<Note>
  This feature is not supported in embedded Omni instances.
</Note>

The Omni Agent can use AI integrations to access context from tools like Google Drive, Google Calendar, Slack, GitHub, and Notion. To manage which integrations are available during your chat session, click the <Icon icon="circle-plus" /> button at the bottom of the chat box.

AI integrations that an [Organization Admin has enabled](/integrations/ai) for your organization appear at the top of the menu. Each integration shows one of two states:

* **Connect** - If you haven't connected your account yet, click **Connect** to launch the OAuth flow. This is the same authentication flow available from your [user account settings](/administration/users/your-account).
* **On/Off toggle** - If you've already connected your account, the integration displays an on/off toggle. Turning the toggle off temporarily withholds that integration's tools from the Omni Agent for your session without disconnecting your account. You can turn the integration back on at any time.

The on/off toggle is per-user and doesn't affect other users in your organization. It only controls whether the integration's tools are available to the agent in your current and future chat sessions.

### Saving information to memory

<Note>
  The **Omni Agent > AI memory** [AI setting](/ai/settings/features#ai-memory) must be enabled to use this feature. Additionally, user memory is not supported for embedded instances.
</Note>

The Omni Agent can remember information about you between chat sessions. Memory holds personal context — such as your team, the region you cover, how you like results presented — and the agent draws on it when it's relevant to your prompt.

With memory, you add personal context once and it automatically applies in every session when relevant. For example, a prompt like *"how did we do last quarter?"* can be automatically filtered to your region and presented in your preferred format based on memory, instead of needing to enter the prompt in every new session.

You can ask the [Omni Agent](/ai/chat) to save information to memory for you, or you can add it manually on your account settings page.

<Tabs>
  <Tab title="Omni Agent" icon="window-maximize">
    <SideBySide alt="Omni Agent saving team information to personal memory in chat">
      Tell the agent to remember something about you - for example, *"Remember I'm on the sales team"* - and it will save it to memory.

      Use the chip that displays in the chat to make changes: click **Manage memory** to open the **AI memory** page in [your account settings](/administration/users/your-account) or **Undo** to remove the memory.
    </SideBySide>
  </Tab>

  <Tab title="Omni UI" icon="window-maximize">
    1. Click your user icon in the top right corner of the page to open the profile menu.
    2. Click **Manage account**.
    3. Next to **AI memory**, click the **Set up** button to initially add personal context, or **Manage** to modify existing context.
    4. Use the Markdown editor on the **AI memory** page to add information you want to store, up to 8,000 characters. For example, you could specify your current role and team, specific terms and their meanings, or the default scope for your questions:

       ```markdown theme={null}
        - I'm an analyst on the Growth team
        - I cover EMEA — assume EMEA unless I ask for another region
        - When I say "recent", I mean the last 90 days
        - Show revenue in thousands
        - I mostly work in the Sales topic
       ```
    5. When finished, click **Save**.
  </Tab>
</Tabs>

Memory is personal and scoped to a single organization. It isn't shared with your team, and the agent never uses it in anyone else's conversations. If you belong to more than one Omni organization, each keeps its own memory.

Use memory for facts about you and how you work. Definitions that apply to everyone — how a metric is calculated, what a business term means — belong in your [data model](/modeling/), where the whole organization benefits from them.

### Selecting an AI model tier

<Note>
  If your Omni organization uses [custom AI models](/ai/settings/model-providers), the model tier selector will be hidden in the chat interface. In this case, the AI will use the custom model configuration from your [AI settings](/administration/ai-hub).
</Note>

The Omni Agent provides a model tier selector that allows you to choose between different AI models for your chat session. This lets you optimize for speed or intelligence based on your needs:

* **Smarter** - Uses the most capable model (Opus) for complex analysis and nuanced queries
* **Standard** - Uses a balanced model (Sonnet) that provides good performance for most queries
* **Faster** - Uses a fast model (Haiku) for quick responses to simpler questions

To select a model tier, click the model selector next to the <Icon icon="microphone" /> (microphone) icon and choose your preferred tier from the dropdown menu. The selector displays the currently active tier, which defaults to your organization or model-level AI settings.

#### Selection reset

Your selected model tier will persist throughout the session, applying to prompts sent after the tier is selected. However, the selection automatically resets to the default tier when you:

* Switch to a different data model using the model picker
* Start a new chat session

The default tier for each model is determined by the model's [`ai_settings`](/modeling/models/parameters/ai-settings) configuration, falling back to organization-level settings when not specified. If neither is configured, chat starts on the Standard tier.

## Searching existing dashboards

Before generating new queries, the Omni Agent can search for existing dashboards that might already answer your question. When you ask a question, the AI analyzes your prompt and searches through:

* **Dashboard names** - Searches the content index for dashboards with relevant titles
* **Tile and chart names** - Searches for specific visualizations that match your question

The AI uses multiple search variations of your keywords to improve the chance of finding relevant content. For example, if you ask about "inventory items count", it might search for "inventory items", "items count", and "inventory" separately. You can also provide the AI with a dashboard's ID or [custom identifier](/share#changing-document-urls-and-identifiers).

When the AI finds potentially relevant dashboards, it:

<Steps>
  <Step title="Evaluates tiles">
    Uses semantic matching to identify which specific tile or chart from a dashboard best matches your question
  </Step>

  <Step title="Shows live previews">
    Executes the underlying query and displays the actual chart or table visualization inline in the chat
  </Step>

  <Step title="Highlights direct answers">
    If a tile directly answers your question, it displays in a highlighted card with an AI-generated explanation of why it's relevant
  </Step>
</Steps>

This helps you discover existing content before creating new queries, promoting reuse of trusted dashboards and reducing duplicate analysis work.

## Creating queries and dashboards

When the Omni Agent answers a question, it generates a live query you can inspect, refresh, or roll up into a dashboard alongside other charts from the session.

### Viewing query field details

When the Omni Agent generates a query, you can view details about the fields used in the results. This helps you understand what data the AI selected and how each field is defined.

To view field details, click the <Icon icon="circle-info" /> icon near the top-right corner of the query results, next to the <Icon icon="download" /> icon. A panel displays information for each field in the query, including:

* **Field name** - The field's label and identifier in the model
* **Definition** - The SQL or calculation that defines the field
* **Description** - Additional context about the field, if defined in the model

<img alt="Query details in the Omni Agent" />

This feature provides transparency into AI-generated queries, helping you verify the AI selected appropriate fields and understand the underlying data structure. To improve the quality of field definitions displayed here, refer to [Optimizing your models for AI](/modeling/develop/ai-optimization).

### Refreshing query results

When you revisit a previous chat session, query results may be stale. To update the results with the latest data, click the <Icon icon="rotate" /> icon floating above the chat box:

<img alt="Re-run all queries icon in the Omni Agent" />

Clicking this icon re-runs all queries in the conversation, updating visualizations and results with current data. To optimize performance, only the most recent queries are re-run.

### Creating dashboards

The Omni Agent can build dashboards. There are a few ways to get started:

* **Ask the agent directly to build a dashboard** — describe the dashboard you want in the chat and the agent plans the layout, generates queries, and publishes a complete dashboard to your [**My documents**](/content/navigate) folder:
  > *"Create a dashboard showing sales performance by region with monthly trends and a top customers table"* After the dashboard is created, you can ask the agent to iterate on it in the same session — rearranging tiles, editing charts, or adding new ones.
* **From an existing chat** — you've been exploring data and created a few visualizations in a chat session, ask the agent to pull them into a dashboard
* **Upload an image** — drop in an image of a dashboard you'd like to replicate. The agent parses what it sees and uses it as a starting point

The model and thinking level used for AI dashboard creation follow the model's [`build_configuration`](/modeling/models/parameters/ai-settings/build-configuration) setting. To disable dashboard creation from chat, users with the required permissions can add the `create_dashboard_from_chat` tool to a model's [`ai_settings.disabled_tools`](/modeling/models/parameters/ai-settings/disabled-tools). This setting is per-model, not organization-wide - you will need to set it on every model to disable dashboard creation from chat entirely.

## Creating routines

The Omni Agent can create routines, find and open your existing routines from chat, and delete a routine when it's open in the split view. See [AI Routines](/ai/routines) for more information.

## Adding files as context

<Note>
  The **Omni Agent > File uploads** [AI setting](/ai/settings/features#file-uploads) must be enabled to upload files and attach images.
</Note>

You can upload text and Markdown files or paste images from your clipboard to give the Omni Agent additional context for your questions. Files are processed in your browser and are not stored on Omni's servers.

### Uploading files

You can upload text (`.txt`), Markdown (`.md`), LookML (`.lkml`), XML (`.xml`), HTML (`.html`, `.htm`), and [images](#attaching-images) to the Omni Agent to provide additional context for your questions. This is useful when you need to reference additional information alongside your data queries.

To upload a file:

1. Click the <Icon icon="circle-plus" /> icon at the bottom of the chat box
2. Select **Attach file**
3. Select a file from your computer
4. The file appears as a file chip in the chat box, indicating it's ready to be sent with your message

The Omni Agent can then read and reference the contents of the uploaded files when generating responses, allowing you to ask questions that combine your data with external context or documentation.

### Attaching images

You can paste images directly from your clipboard into the chat to provide visual context alongside your questions. This works with screenshots, images copied from web pages, or any image data on your clipboard.

To attach an image:

1. Copy an image to your clipboard (for example, take a screenshot or copy an image from a web page)
2. Click into the chat box
3. Paste the image using your system's paste command (`Cmd+V` on Mac, `Ctrl+V` on Windows/Linux)

The image appears as a file chip in the chat box, indicating it's ready to be sent with your message. You can attach multiple images to a single message by pasting them one after another.

<Warning>
  Image pasting is supported in Chrome and Safari. Firefox does not currently support pasting images into textarea elements due to browser limitations.
</Warning>

## Managing and sharing chat sessions

Each conversation with the Omni Agent is saved as a chat session you can revisit and share with other users in your organization.

### Navigating prompt history

You can quickly recall previous prompts using keyboard shortcuts, similar to a command-line interface:

* Press the **Up arrow** key to cycle backward through your previous prompts
* Press the **Down arrow** key to cycle forward through your prompt history

When you reach your oldest prompt and press Up arrow again, the navigation wraps to your most recent prompt. Pressing Down arrow after your newest prompt restores any in-progress text you were typing before navigating the history.

<Note>
  Arrow key navigation only works when your cursor is at the beginning of the input field or when the field is empty. This preserves normal cursor movement when editing text.
</Note>

The prompt history displays only your own prompts from the current chat session.

### Managing long conversations

As your conversation with the Omni Agent grows, it consumes more of the available context window. When a chat session reaches 75% of the context window, a visual indicator appears on the **New chat** button to help you recognize when starting a fresh conversation would improve performance. Context window size is determined by the [`conversation_prune_length`](/modeling/models/parameters/ai-settings/conversation-prune-length) parameter.

This feature is automatic and requires no configuration. Starting a new chat when prompted helps maintain optimal AI performance, especially for complex queries and analysis.

### Sharing chat sessions

You can share a chat session by copying the URL from your browser's address bar and sending it to another user.

Query results stored in the chat history are cached from when the creator ran them. The viewer of the shared chat will see those same cached results.

Therefore, Omni requires that the viewer of the shared chat have **Querier**, **Modeler**, or **Connection Admin** permissions, as well as the same [connection environment](/connect-data/dynamic-environments), to view the session. Users with **Restricted Querier** permissions or lower will not be able to access shared chat sessions.

The following rules determine who can see a chat:

1. The **owner** of the chat can always view the chat.
2. Any user with the **Querier role or above on all relevant models** can view the chat. Because Queriers can already write SQL queries directly in Omni, this doesn't expose any data they couldn't otherwise access.
3. **Viewers and Restricted Queriers** are blocked from viewing, preventing access to data they are not authorized to see.

## Customizing and embedding the Omni Agent

Organization Admins can tailor the agent's appearance to match their brand and surface it inside external applications.

### Applying branding

Organization Admins can customize the appearance of the AI chat interface, including the agent's name, icon, and greeting messages. Refer to the [AI branding settings](/ai/settings/branding) for more information.

### Embedding the agent

The Omni Agent can also be embedded into external applications. Refer to the [embedding the Omni Agent guide](/embed/customization/ai-chat) for setup instructions.

## Next steps

* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve the quality of AI-generated responses
* [Configure topics](/modeling/topics) to organize and scope the data the Omni Agent can access
* [Customize the Omni Agent appearance](/ai/settings/branding) with your own branding


# Chat with Content
Source: https://docs.omni.co/ai/dashboard-assistant

Chat with Content brings Omni's conversational analytics directly into your content.

Chat with Content allows you to interact with your content using natural language. Ask follow-up questions, drill into subsets, re-aggregate results, or request summaries, all without leaving the page.

## Requirements

To use Chat with Content, you'll need **Restricted Querier**, **Querier**, **Modeler**, or **Connection Admin** permissions for the model the content is built on.

## Enabling Chat with Content

<Note>
  **Organization Admin** permissions are required to modify AI & content permissions settings.
</Note>

Chat with Content requires two settings to be enabled:

1. **Read data result** in [**AI Hub > Setup**](/ai/settings/features#read-result-data). This allows the AI to read query results to perform tasks like data summarization, anomaly detection, and highlighting insights.
2. The **AI on dashboard** document ability:
   * **To enable Chat with Content globally**, navigate to [**Settings > Content permissions**](/administration/content-permissions) and locate the Chat with Content [document ability](/administration/content-permissions#default-document-abilities). This will enable Chat with Content by default, but you can disable it on a document-by-document basis.
   * **To enable Chat with Content on individual documents**, navigate to [**File > Document Settings > AI on dashboard**](/share#controlling-document-interactivity) in the document

## Using Chat with Content

<Tip>
  Want to customize the look of the chat interface? Use the [AI branding settings](/ai/settings/branding) to add your own icon, change the agent's name, and more!
</Tip>

<AccordionGroup>
  <Accordion title="Opening the chat panel">
    Once enabled, a floating avatar will appear on **published** content. Click the avatar to open a split-view interface, where the chat appears side-by-side with your content.

    The split-view layout allows you to interact with the Omni Agent while keeping your content fully visible, making it easy to reference charts and data as you chat.

    <Note>
      When embedding content with [`mode=SINGLE_CONTENT`](/embed/setup/url-parameters/mode), the chat opens in an inline panel instead of split view. This keeps users scoped to the embedded content and prevents navigation away from the single-content frame.
    </Note>
  </Accordion>

  <Accordion title="Opening the chat from edit mode">
    How you access the chat differs depending on whether you're using an embedded Omni instance or not:

    * **Embedded** - Click the <Icon icon="sparkles" /> icon in the sidebar
    * **Non-embedded Omni** - Click the floating avatar to open the chat panel

    This opens a split-view interface, allowing you to chat while working on your layout.
  </Accordion>

  <Accordion title="Focusing on specific charts">
    You can scope the agent to specific charts by:

    * Clicking a specific chart in the chat, or
    * Clicking on a tile's <Icon icon="ellipsis-vertical" /> (three dot icon) and selecting **Ask a follow up question**:
      <img alt="Add a specific chart option in Chat with Content" />

    The Omni Agent will focus on the selected chart until you remove the focus or close the chat panel.
  </Accordion>

  <Accordion title="Unfocusing from specific charts">
    To unfocus the agent from a specific chart, click the **X** on the chart chip in the chat input. You can also close the chat panel entirely, though this will remove the chat history.
  </Accordion>

  <Accordion title="Attaching images">
    <Note>
      The **Omni Agent > File uploads** [AI setting](/ai/settings/features#file-uploads) must be enabled to use this feature.
    </Note>

    You can paste images directly from your clipboard into the chat input to provide visual context alongside your questions. Copy an image to your clipboard and paste it into the chat input using your system's paste command (`Cmd+V` on Mac, `Ctrl+V` on Windows/Linux).

    The image appears as a file chip in the chat input, indicating it's ready to be sent with your message.

    <Warning>
      Image pasting is supported in Chrome and Safari. Firefox does not currently support pasting images into textarea elements due to browser limitations.
    </Warning>
  </Accordion>
</AccordionGroup>

## Getting help

If you're stuck and can't remember how to do something in Omni, ask the Omni Agent. Questions like *"How do I do \[thing]?"* will prompt the agent to search the official Omni docs and provide you with an answer, all without leaving your Omni workflow.

You can also directly tell the agent to search the docs when researching the answer to your question.

<Note>
  **Working in an embedded context?** If you have the **Hide Omni watermark** setting enabled to provide a fully white-labeled experience, the AI doc search feature will respect it. Omni doc links will not be returned in chat, even if explicitly requested.
</Note>


# Evals
Source: https://docs.omni.co/ai/evals

Measure and compare Omni AI accuracy with prompt sets and judged eval runs — from the AI Hub.

Evals measure how accurately Omni's AI answers natural-language questions about your data. You define a **prompt set** (a reusable collection of questions scoped to a single Omni model), then execute an **eval run** that scores each AI response with a built-in accuracy judge. Because a run targets a specific model branch, evals let you measure the impact of data modeling and curation changes (new fields and joins, or `ai_context` and other context adjustments) before promoting them to your shared model. Use evals to catch regressions before they reach users and to compare results across branches.

Evals live in the **AI Hub**, under the **Prompt sets** and **Eval runs** tabs.

## Requirements

* At least **Querier** access on the shared model you want to evaluate (Organization Admins and AI admins also have access)
* At least one [topic](/modeling/models/topics) optimized for AI — see [Optimizing models for Omni AI](/modeling/develop/ai-optimization)

## Prompt sets

A prompt set is a reusable list of up to 25 natural-language prompts that you run against the AI together. You can create as many prompt sets as you need — for example, one per topic, one per release, or one for regression coverage.

### Manage prompts

From the **Prompt sets** tab in the AI Hub, you can:

* **Create a prompt set** and give it a descriptive name
* **Add or edit prompts** in an existing set, up to the 25-prompt limit
* **Delete a prompt** you no longer need
* **Save changes** to persist edits
* **Archive a prompt set** to remove it from the active list without losing it. Archived sets can be restored.

### What makes an effective prompt set

Strong prompt sets are representative, broad, and unambiguous:

* **Mirror real user questions** — use the [AI usage analytics](/administration/analytics) dashboard to find what users actually ask
* **Favor breadth over depth** — covering several topics with one prompt each yields more signal than ten prompts on the same topic
* **Phrase prompts naturally** — write the way a user would ask, not in language that mirrors field names
* **Add regression prompts** when an AI answer turns out to be wrong, so the same failure is caught next time
* **Start small and expand toward the 25-prompt cap** — begin with 10–15 prompts that cover your core scenarios, then iterate on `ai_context` and `sample_queries` and add more prompts as you go

### Expected behavior

By default, the accuracy judge decides whether the AI's response is a correct, reasonable answer to the prompt on its own terms. You can optionally describe the **expected behavior** for any prompt — a reference answer describing the result you expect — and the judge checks the AI's analysis against it.

Expected behavior is useful when a prompt has a known correct answer you want to pin down, such as a specific value or ranking ("The top product by revenue should be Aniseed Syrup."), a direction ("Revenue should be up year over year."), or a breakdown the answer must include.

When a prompt defines expected behavior, the judge:

* Treats a **material divergence as a failing result** — wrong numbers, the wrong direction, or a required result that's missing. Differences in wording, formatting, or extra detail don't fail the prompt.
* Scores the response against its best interpretation, rather than failing the prompt outright, when the expected behavior is vague or only partially addressed.
* Restates the expected behavior in its rationale, so opening the chat shows exactly what was expected next to the verdict.

The expected behavior is shown only to the judge — the AI being evaluated never sees it, so it can't steer toward the expected answer. Each run snapshots the expected behavior in effect when it started, so editing a prompt's expected behavior later doesn't change how earlier runs were scored.

<Note>
  Expected behavior is set per prompt through the prompt sets API (`POST` and `PATCH /api/v1/ai/eval/prompt-sets`) — pass an optional `expectation` string of up to 16,000 characters on each prompt. It isn't yet editable from the **Prompt sets** tab in the AI Hub.
</Note>

## Running an eval

When you start an eval run, Omni runs each prompt as an asynchronous agentic AI job (the same engine behind the [Create AI job](/api/ai/create-ai-job) API), captures the AI's response, and then scores it with Omni's built-in accuracy judge. The judge model is fixed; it isn't configurable per run. When a prompt defines [expected behavior](#expected-behavior), the judge also scores the response against it.

<Steps>
  <Step title="Select a prompt set">
    Open the **Prompt sets** tab in the AI Hub and pick the prompt set you want to evaluate.
  </Step>

  <Step title="Choose a model branch">
    Select the model branch the AI should query against, or pick `main` to evaluate the live shared model. Running on a branch lets you measure the impact of in-progress model changes before promotion.
  </Step>

  <Step title="Add a description">
    Add a short description for the run — for example, "Baseline before topic restructure" or "After adding ai\_context to order\_items." Descriptions appear in the run list and the comparison view, so write something you'll recognize later.
  </Step>

  <Step title="Start the run">
    Submit the run. Each prompt executes asynchronously as an AI job and is then scored by the judge. You can leave the page — results stream in as prompts complete.
  </Step>
</Steps>

<Note>
  You can have up to two eval runs in progress at once. Wait for a run to finish (or cancel it) before starting a third.
</Note>

## How the accuracy judge works

The accuracy judge is a separate AI model that reviews each completed AI response and returns a pass/fail verdict. It's tuned to catch the analysis mistakes that most often make an answer wrong, not to grade wording, formatting, or style.

### What the judge sees

The judge reads the evaluated AI's own work for that prompt — the same internal message history the AI produced and saw while answering:

* The user prompt
* Every tool call the AI made and its result — including the generated queries, the query results, and any data the AI sampled or retrieved
* The AI's final written response

The judge evaluates only what the AI did and saw, including the state of the model and data as it existed when the prompt ran. It doesn't independently re-run queries or inspect the live semantic model. A verdict therefore reflects the AI's reasoning against the model the AI actually worked with at the time.

### What the judge checks for

The judge's instructions focus on common, high-impact analysis errors. It looks for problems like:

* **Hallucinations** — claims in the written response that the query results don't actually support. The judge verifies numbers and statements against the underlying query and results rather than trusting the AI's own summary.
* **Date and time filtering** — wrong or off-by-one date filters, missing "complete" period handling, and incorrect reasoning about fiscal periods.
* **Row-limit handling** — treating a result that hit the row limit as if it were complete, such as summing a truncated column and reporting it as a total.
* **Mental math** — figures the AI computed in its written response instead of in the query, which can be wrong or hallucinated.
* **Period-over-period errors** — comparison filters that cover the wrong window, like filtering two years of data and then applying a one-year comparison on top.
* **Ignoring the request** — not honoring an explicitly requested query structure, such as "pivot it by month."
* **Query and calculation problems** — using the wrong topic, degenerate results (all zero, null, or identical), or defining a calculated field the query never uses.

When a prompt defines [expected behavior](#expected-behavior), the judge also checks the AI's findings against it.

### How the judge scores

The judge returns a binary verdict for each prompt:

* **Pass** when the response clears every check above
* **Fail** when one or more critical errors are present — a single critical error fails the prompt

The judge also reports a **rationale** for each verdict, anchored in evidence from the conversation. Open the chat for any prompt to read both.

<Note>
  The accuracy judge is a single pass/fail correctness check, not a multi-criteria rubric. A passing verdict means the AI avoided the analysis errors above — not that the answer is the single best possible response.
</Note>

## Reviewing results

Once a run completes, open it to see per-prompt and aggregate results.

For each prompt, the run shows:

* **Accuracy** — a pass/fail verdict from Omni's built-in accuracy judge on whether the AI's response correctly answered the prompt, scored against the prompt's [expected behavior](#expected-behavior) when it's set
* **Prompt credits** — the credits consumed generating the AI response
* **Judge credits** — the credits consumed scoring the response
* **Duration** — how long the prompt took to complete
* **Open chat** — a link that opens the underlying AI conversation. Beyond the generated query, fields, and answer, this is where you can see the accuracy judge's full verdict and rationale for that prompt — including how the response compared against the expected behavior, when it was set

Aggregate metrics for the run include total credits, total duration, and overall accuracy, so you can summarize a run at a glance.

You can archive a completed run to remove it from the active list. Archived runs are preserved and can be restored later.

## Comparing two runs

To measure the impact of a model change, run an eval on a branch, then compare it to a baseline run on `main`. Comparison is limited to two runs of the **same prompt set**, so both runs evaluate the same questions.

The comparison view shows side by side, per prompt:

* **Accuracy** — the accuracy judge's pass/fail verdict on each run, so you can see exactly which prompts regressed or improved. Open the chat for any prompt to read the judge's rationale behind a verdict
* **Credits** — the combined prompt + judge credits for each run, so you can spot changes that hurt efficiency
* **Duration** — run-to-run latency differences

Use the comparison to validate a change before promoting it: if accuracy improves and credits hold steady, the change is a clear win; if accuracy is flat but credits spike, you may want to investigate before merging.

## Next steps

<CardGroup>
  <Card title="Optimize models for Omni AI" icon="brain-circuit" href="/modeling/develop/ai-optimization">
    Add ai\_context, sample queries, and field metadata to improve AI accuracy.
  </Card>

  <Card title="Learn from conversation" icon="brain" href="/ai/learn-from-conversation">
    Let the AI capture business context from your conversations.
  </Card>

  <Card title="Model AI settings" icon="sliders" href="/modeling/models/parameters/ai-settings">
    Configure AI query scope, validation, thinking levels, and context management.
  </Card>

  <Card title="Create AI job API" icon="code" href="/api/ai/create-ai-job">
    The endpoint that powers each prompt in an eval run.
  </Card>
</CardGroup>


# Generating forecasts with AI
Source: https://docs.omni.co/ai/forecasting

Create statistical forecasts and projections for time-series data using natural language.

The Omni Agent can generate statistical forecasts for time-series data using natural language prompts. Instead of relying on spreadsheet formulas, the agent uses Omni's built-in library of deterministic forecasting functions to project future values based on historical trends.

<Note>
  Forecasting runs entirely within Omni using an internal statistical library. The agent doesn't have access to the internet and doesn't send your data to any external forecasting service. Only the metadata and query results already covered by [AI data privacy](/ai/security) are shared with the LLM to interpret your prompt and present results.
</Note>

You can ask the [Omni Agent](/ai/chat) to generate a forecast directly in the Workbook Agent. For example:

* "Forecast revenue for the next 3 months"
* "Project user growth for the next quarter"
* "Predict sales trends for the next 6 months"

The Omni Agent will generate a new query if needed, analyze the query results, and generate a statistical forecast based on historical patterns in the data.

## Requirements

The **Use Omni Agent** setting in [AI settings](/ai/settings/features) must be enabled to use this feature.

## How it works

When you ask the agent to forecast or project data:

<Steps>
  <Step>
    The Omni Agent extracts the time-series data from your query results or runs a new query if needed
  </Step>

  <Step>
    It applies statistical forecasting models to identify trends and patterns
  </Step>

  <Step>
    It generates projections for the requested time period. When a forecast spans multiple periods, the agent first forecasts the remainder of the current period using daily granularity data, then forecasts the remaining periods at the granularity you requested.

    For example, if you ask the agent to forecast 2027, it first forecasts the rest of 2026 using daily historical data, then uses that result along with annual history to forecast 2027.
  </Step>

  <Step>
    The forecast results are displayed in the workbook or dashboard
  </Step>
</Steps>

This approach uses Omni's internal, deterministic forecasting functions rather than simple spreadsheet calculations, providing more accurate and statistically sound projections. Because the forecasting library is built into Omni, the agent computes projections from your own historical data without reaching out to the web or any third-party service.

## Example prompts

The following examples demonstrate the types of prompts you can use to generate forecasts with the agent.

### Basic forecasting

* "Forecast the next 3 months"
* "Project this trend forward 6 months"
* "Predict values for the next quarter"

### Specific metrics

* "Forecast monthly revenue for the next year"
* "Project user signups for the next 90 days"
* "Predict sales volume through the end of the year"

### Analysis questions

* "What will revenue look like in 6 months?"
* "How many users can we expect next quarter?"
* "Where is this metric headed?"

## Next steps

* [Building queries & filters with AI](/ai/queries): Learn how to create queries that work well with forecasting
* [Generating visualizations with AI](/ai/visualizations): Visualize your forecasts with AI-generated charts
* [Optimizing your models for AI](/modeling/develop/ai-optimization): Improve AI results with model context
* [AI data privacy](/ai/security): Learn how Omni handles your data when you use AI tools


# AI in Omni
Source: https://docs.omni.co/ai/index

Omni's AI is grounded in your semantic model — delivering accurate, governed analytics through natural language.

Omni's AI is built on your organization's [semantic model](/modeling) — the layer that defines your metrics, relationships, and business logic. This means AI-generated queries use the same governed definitions as the rest of Omni, so results are consistent and trustworthy. User permissions are enforced across every AI surface, and your data is never used to train models.

The fastest way to get started is with the [Omni Agent](/ai/chat), where you can ask questions about your data in plain language.

## Ask questions about your data

Omni provides several AI-powered surfaces for exploring your data with natural language:

<CardGroup>
  <Card title="Omni Agent" icon="message-bot" href="/ai/chat">
    A standalone chat experience for exploring data. Ask questions, generate queries and visualizations, and create dashboards — no workbook setup needed.
  </Card>

  <Card title="Workbook Agent" icon="wand-magic-sparkles" href="/ai/queries">
    Build and refine queries using natural language inside a [workbook](/analyze-explore/workbook-basics) — Omni's core environment for building and saving analyses.
  </Card>

  <Card title="Skills" icon="diagram-project" href="/ai/skills">
    Save a set of AI instructions and run it by name — for standardized reports, guided lookups, and data quality checks.
  </Card>

  <Card title="Routines" icon="calendar-clock" href="/ai/routines">
    Schedule recurring AI-powered tasks to run automatically on your data.
  </Card>

  <Card title="Chat with Content" icon="chart-mixed" href="/ai/dashboard-assistant">
    Ask questions directly on published content. Click a chart to scope the conversation, drill into subsets, or request summaries without leaving the page.
  </Card>
</CardGroup>

## AI-assisted building

Beyond helping you create queries, AI is embedded throughout Omni to help you build, visualize, and more:

<CardGroup>
  <Card title="Modeling Agent" icon="diagram-project" href="/ai/model-assistant">
    Chat while you edit YAML in the Model IDE—ask about relationships, draft measures and topics, and review proposed changes.
  </Card>

  <Card title="Dashboards" icon="table-columns" href="/ai/chat">
    Ask the Omni Agent to design and assemble a dashboard.
  </Card>

  <Card title="Apps" icon="browser" href="/visualize-present/apps">
    Describe a custom, interactive interface and the Omni Agent builds it as an app backed by live, governed queries.
  </Card>

  <Card title="Visualizations" icon="chart-bar" href="/ai/visualizations">
    Describe the chart you want and the AI will create and configure it for you.
  </Card>

  <Card title="Formula builder" icon="function" href="/analyze-explore/calculations#ai-generated">
    Describe a calculation in plain English and get a working Excel-style formula.
  </Card>

  <Card title="Forecasting" icon="chart-line-up" href="/ai/forecasting">
    Generate statistical forecasts and projections for time-series data using natural language.
  </Card>
</CardGroup>

## Improve AI quality

Omni's AI uses your defined metrics, relationships, and business logic — not guesswork on raw tables. To further improve accuracy:

* **[Evals](/ai/evals)** — Create prompt sets, run them against any model branch with a built-in accuracy judge scoring the results, and compare runs side by side to measure the impact of model changes.
* **[Optimize your models for AI](/modeling/develop/ai-optimization)** — Add descriptions, sample values, and synonyms to help the AI select the right fields and interpret questions correctly.
* **[Learn from conversation](/ai/learn-from-conversation)** — Let the AI capture business context from your conversations and encode it into the model for future queries.
* **[Suggestions](/ai/suggestions)** — Improve your model from real usage. Omni turns AI sessions and user feedback into a prioritized, ready-to-review list of model improvements — like AI context or synonyms for the fields that tripped up the AI — that you approve and apply.
* **Rate AI responses** using the <Icon icon="thumbs-up" /> / <Icon icon="thumbs-down" /> icons in the Omni app or on [Omni Slack Agent](/integrations/omni-slack-agent) responses to help improve result quality.

## Data security

Omni's AI is designed to respect your existing security boundaries. Your data stays protected and is never used to train models.

* **Permissions** — Every AI query respects row-level security and user-level access controls. Users only see data they're authorized to access.
* **[Data security](/ai/security)** — By default, Omni uses Claude on AWS Bedrock. Your data is never used to train models. Organizations can also configure [Anthropic Direct, Google Vertex AI, OpenAI, Snowflake Cortex, or Grok (xAI)](/ai/settings/model-providers).

## Manage and customize

The AI Hub is the central place to configure Omni AI and monitor how your organization uses it.

<CardGroup>
  <Card title="AI Hub" icon="house" href="/administration/ai-hub">
    Enable or disable AI features, customize branding, and configure model providers. Track adoption, answer quality, and credit usage across your organization.
  </Card>
</CardGroup>

For a deeper view of token consumption across your whole instance, see the [Credit tracking dashboard](/ai/settings/usage) in your [**Analytics** section](/administration/analytics).

## Use Omni in other tools

Bring Omni's AI-powered analytics into the tools your team already uses.

<CardGroup>
  <Card title="MCP Server" icon="plug" href="/ai/mcp">
    Query your Omni data from Claude Desktop, ChatGPT, Cursor, and other AI tools using the Model Context Protocol.
  </Card>

  <Card title="Agent skills" icon="code" href="/developers/agent-skills">
    Open-source agent skills that bring model building, querying, and content management into your development environment.
  </Card>
</CardGroup>


# Learn from conversation
Source: https://docs.omni.co/ai/learn-from-conversation

Let the AI capture business context from your conversations to improve future queries.

When you interact with the AI — correcting a query, explaining what a metric means, or clarifying how a field should be filtered — that context is valuable. Learn from conversation lets the AI capture those insights and apply them to your [semantic model](/modeling), so future queries benefit from what was discussed.

For example, if you tell the AI that "revenue should only include orders with status Complete, Shipped, or Processing," the AI can learn that rule and encode it into the model as field descriptions, `ai_context`, synonyms, or new field definitions.

## Requirements

This feature requires **Querier** permissions or higher, as these users can create workbook-level model changes and branches. Users with lesser permissions will not see the <Icon icon="brain" /> icon in the chat interface.

## How it works

After a conversation where you've shared business context, click the <Icon icon="brain" /> that appears alongside the AI's response. This triggers a review flow:

1. The AI analyzes the conversation and generates model updates — such as field descriptions, labels, synonyms, `ai_context` annotations, or new dimensions and measures
2. A review modal displays the proposed changes as model YAML
3. You can accept, edit, or reject the changes before they're applied

Changes are written to the model as YAML, making them available to all users querying through that model. Check out the following video to see how it works in Omni!

<iframe title="Learn from Conversation" />

## Auto-learn

Auto-learn is enabled by default for all organizations. With auto-learn enabled, the AI proactively identifies moments in a conversation where you're sharing useful business context — like defining a metric, specifying filter criteria, explaining what a field means, or providing alternate names for a concept.

When this happens, the AI surfaces a learning summary in the chat. You can then click to apply it through the same review flow described above.

## What the AI can learn

The learn flow can generate updates including:

* **Field descriptions and labels** — document what fields mean in your business context
* **`ai_context` annotations** — add hints that help the AI select the right fields in future queries
* **Synonyms** — register alternate names so the AI recognizes different ways users refer to the same concept
* **New dimensions and measures** — define calculated fields that came up in the conversation
* **View-level context** — describe what a view represents and how it should be used


# MCP authentication
Source: https://docs.omni.co/ai/mcp/authentication

Choose how to authenticate MCP clients with your Omni instance: OAuth for streamlined setup or API keys for manual control.

The Omni MCP Server supports two authentication methods. Choose the one that best fits your needs:

|                  | OAuth                                         | API key                                                |
| ---------------- | --------------------------------------------- | ------------------------------------------------------ |
| Best for         | Individual users who want quick, secure setup | Admins managing keys centrally, or automated workflows |
| Setup complexity | Low - browser flow                            | Medium - manual configuration                          |
| Key management   | Automatic                                     | Manual                                                 |
| User permissions | Uses your permissions                         | Uses key creator's permissions                         |

## OAuth authentication

OAuth lets MCP clients connect to Omni without requiring you to manually create and manage API keys. When you connect, Omni creates an API key on your behalf and links it to your user account.

<Note>
  PATs generated through MCP OAuth are different from standard PATs. See the [MCP OAuth PATs section](#mcp-oauth-pats) for more information.
</Note>

### Requirements

To use OAuth authentication with the MCP Server, your organization must have the **MCP server setting** enabled. Organization Admins can enable this setting in [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).

### How it works

<Note>
  The OAuth flow will use the cookie of the last Omni instance you logged into when redirecting you to the authorization page. If you are a member of multiple organizations, log out and then log back in to the organization you want to connect to immediately before starting the OAuth flow.
</Note>

When you first connect an MCP client to Omni using OAuth, the flow will look similar to the following:

1. You add the [connection URL](#connection-url) to your MCP client.
2. The MCP client will trigger the OAuth flow.
3. Your browser will open to an authorization page for your Omni organization.
4. Review the permissions on the authorization page.
5. Click **Authorize**.
6. Omni will automatically create an [**MCP OAuth PAT**](#mcp-oauth-pats) for the MCP client and link it to your Omni user account.

After authorization, all MCP queries use your Omni permissions and access controls. The flow uses OAuth 2.1 with PKCE for security.

### MCP OAuth PATs

When you authenticate via OAuth, Omni automatically creates a special PAT called an **MCP OAuth PAT**. These differ from standard PATs in a few ways:

<Steps>
  <Step title="Any user can create one">
    Standard PATs require **Restricted Querier** or higher permissions, but MCP OAuth PATs are created automatically for any user who completes the OAuth flow. This can include **Viewers**.
  </Step>

  <Step title="Permissions reflect the user's in-app permissions">
    MCP OAuth PATs inherit the creating user's in-app permissions.

    This means that while **Viewers** can create an MCP OAuth PAT, they won't be able to run queries or retrieve data through MCP since their permissions don't allow querying in-app.
  </Step>

  <Step title="Not visible in Omni">
    MCP OAuth PATs are not currently visible in Omni.

    <Tip>
      While these PATs can't currently be viewed in the Omni app, you can use the [List API tokens endpoint](/api/api-tokens/list-api-tokens) to retrieve information about MCP-generated PATs.
    </Tip>
  </Step>
</Steps>

To turn MCP access on or off for the whole organization, Organization Admins can use the [**MCP server** setting](/ai/settings/mcp#mcp-server) in **AI Hub > General > Features**. Disabling it returns a `403` for new authorization requests and blocks existing grants from making tool calls.

For a full comparison of all API key types in Omni, refer to the [API authentication](/api/authentication) documentation.

### Connection URL

Use this URL when setting up OAuth in your MCP client:

```text theme={null}
https://callbacks.omniapp.co/callback/mcp
```

This URL routes requests to your Omni organization after you identify yourself during the OAuth flow.

## API key authentication

API key authentication gives you direct control over key creation and management. This approach is useful when:

* You need to manage API keys centrally for your organization
* You're setting up automated workflows or CI/CD pipelines
* You want to use a service account rather than individual user credentials
* Your MCP client doesn't support OAuth

### How it works

1. Create an [API key in Omni](/api/authentication)
2. Configure the key in your MCP client's settings
3. The client includes the key in all requests to Omni

### Connection URL

When using API key authentication, connect directly to your Omni instance:

```text theme={null}
https://<YOUR_OMNI_INSTANCE>/mcp/https
```

Replace `<YOUR_OMNI_INSTANCE>` with your Omni URL (e.g., `acme.omniapp.co`).

## Troubleshooting

### OAuth issues

<AccordionGroup>
  <Accordion title="MCP server access disabled (403 error)">
    Your organization has disabled MCP server access. Ask an Organization Admin to enable it in [**AI Hub > MCP**](/ai/settings/mcp#mcp-server)
  </Accordion>

  <Accordion title="Authorization flow doesn't start">
    * Verify your MCP client supports OAuth 2.1 with PKCE
    * Check that you're using the correct URL: `https://callbacks.omniapp.co/callback/mcp`
    * Ensure your Omni instance is accessible from your browser
  </Accordion>

  <Accordion title="Authorization fails after clicking &#x22;Authorize&#x22;">
    * Check that your browser allows redirects to the MCP client
    * Verify you have permission to create API keys in your organization
    * Try disconnecting and reconnecting the MCP client
  </Accordion>
</AccordionGroup>

### API key issues

<AccordionGroup>
  <Accordion title="Authentication fails">
    * Verify the API key is correct and hasn't been revoked
    * Check that the key has appropriate permissions
    * Ensure you're using the correct instance URL
  </Accordion>
</AccordionGroup>

### General issues

<AccordionGroup>
  <Accordion title="Queries fail after successful authorization">
    * Confirm the API key is active in your Omni settings
    * Verify you have access to the model and topics you're querying
    * Check that your Omni user permissions allow data access
  </Accordion>
</AccordionGroup>

## Next steps

Ready to connect? Follow the setup guide for your MCP client:

<Columns>
  <Card title="ChatGPT" href="/ai/mcp/chatgpt" icon="message-bot">
    OpenAI's AI assistant with developer mode
  </Card>

  <Card title="Claude Code" href="/ai/mcp/claude-code" icon="code">
    Command-line based version of Anthropic Claude
  </Card>

  <Card title="Claude Desktop" href="/ai/mcp/claude-desktop" icon="desktop">
    App version of Anthropic Claude
  </Card>

  <Card title="Codex" href="/ai/mcp/codex" icon="terminal">
    OpenAI's agentic coding tool
  </Card>

  <Card title="Cursor" href="/ai/mcp/cursor" icon="arrow-pointer">
    AI-powered IDE designed for fast, agentic programming
  </Card>

  <Card title="Microsoft Copilot" href="/ai/mcp/microsoft-copilot" icon="robot">
    Microsoft's AI assistant, configured through Copilot Studio
  </Card>

  <Card title="Visual Studio Code" href="/ai/mcp/vscode" icon="microsoft">
    Popular open-source IDE with powerful AI features
  </Card>
</Columns>


# Using the MCP Server in ChatGPT
Source: https://docs.omni.co/ai/mcp/chatgpt

Connect your Omni data to ChatGPT with Omni's MCP Server.

ChatGPT supports MCP connections, allowing you to bring your Omni data directly into ChatGPT conversations. Once successfully connected, you can ask ChatGPT questions about your data and get answers powered by Omni.

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* The following in ChatGPT:
  * **A plan that supports apps and connectors.** This includes Pro, Plus, Business, Enterprise, and Education plans.
  * **For manual OAuth or API key setup only**: [Developer mode](https://developers.openai.com/api/docs/guides/developer-mode/) enabled in ChatGPT. Toggle it on in **Settings > Apps > Advanced settings**.
* To have the following enabled in Omni:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).
  * **Personal access tokens (PATs)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#token-types).

## Setup

Choose your setup method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="ChatGPT App (Recommended)">
    The official Omni Analytics app for ChatGPT provides the fastest setup experience with no manual configuration required.

    <Steps>
      <Step title="Install the app">
        Visit the [Omni Analytics ChatGPT app](https://chatgpt.com/apps/omni-analytics/asdk_app_694e8b8715108191a49fe2db4398d9e2) page and click **Add** to install the app.
      </Step>

      <Step title="Authorize the connection">
        1. ChatGPT will redirect you to an Omni authorization page.
        2. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your ChatGPT conversations.

        In a new chat, click the <Icon icon="plus" /> (plus) icon, then select the Omni connector to enable it.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Custom OAuth">
    OAuth provides streamlined setup without manually managing API keys. Use this method if you need to configure the connector manually using developer mode.

    <Steps>
      <Step title="Open connector settings">
        In ChatGPT, navigate to **Settings > Apps & Connectors**.
      </Step>

      <Step title="Create a new connector">
        Click **Create** next to **Advanced settings**.
      </Step>

      <Step title="Configure the connector">
        Fill in the following fields:

        * **Connector name** — Enter a name, such as `Omni`
        * **Description** — Enter a description, such as `Connect to Omni analytics data`
        * **Server URL** — Paste the following URL:

          ```text theme={null}
          https://callbacks.omniapp.co/callback/mcp
          ```

        Click **Add** to create the connector.
      </Step>

      <Step title="Authorize the connection">
        1. ChatGPT will redirect you to an Omni authorization page.
        2. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your ChatGPT conversations.

        In a new chat, click the <Icon icon="plus" /> (plus) icon, then select the Omni connector to enable it.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Open connector settings">
        In ChatGPT, navigate to **Settings > Apps & Connectors**.
      </Step>

      <Step title="Create a new connector">
        Click **Create** next to **Advanced settings**.
      </Step>

      <Step title="Configure the connector">
        Fill in the following fields:

        * **Connector name** — Enter a name, such as `Omni`
        * **Description** — Enter a description, such as `Connect to Omni analytics data`
        * **Server URL** — Enter your instance URL:

          ```text theme={null}
          https://<YOUR_OMNI_INSTANCE>/mcp/https
          ```

        Replace `<YOUR_OMNI_INSTANCE>` with your Omni URL (e.g., `acme.omniapp.co`).
      </Step>

      <Step title="Configure authentication">
        Set the authentication method to **Bearer token** and enter your [Omni API key](/api/authentication).
      </Step>

      <Step title="Verify the connection">
        In a new chat, click the <Icon icon="plus" /> (plus) icon, then select the Omni connector. Ask a question about your data to confirm the connection is working.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, you can use it in any ChatGPT conversation by enabling the connector.

<Steps>
  <Step>
    Open a new chat and click the <Icon icon="plus" /> (plus) icon to select apps. Enable the Omni connector.
  </Step>

  <Step>
    Enter a prompt, such as `Hey Omni, tell me how many users have been sourced by search and email`.
  </Step>

  <Step>
    ChatGPT may prompt you to approve tool usage for actions that modify data. Click **Allow** to proceed.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data.
  </Step>
</Steps>


# Using the MCP Server in Claude Code
Source: https://docs.omni.co/ai/mcp/claude-code

Connect your Omni data to Claude Code with Omni's MCP Server.

Claude Code is the command line version of Anthropic's AI assistant, Claude. Once successfully connected to Omni, you can interact with your Omni data right in your Claude Code session.

**Looking for the Omni agent skills for Claude Code?** See the [Agent skills documentation](/developers/agent-skills) for a broader set of skills beyond querying.

**Looking for Claude Desktop?** Check out the [Claude Desktop guide](/ai/mcp/claude-desktop).

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* To install Claude Code
* To have the following enabled in Omni:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).
  * **Personal access tokens (PATs)**. An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#token-types).

## Setup

<Tabs>
  <Tab title="Claude Connector (Recommended)">
    The official Omni connector for Claude provides the fastest setup experience with no manual configuration required.

    <Steps>
      <Step title="Install the connector">
        Visit the [Omni Analytics connector](https://claude.com/connectors/omni-analytics) page and click **Add to Claude** to install the connector. This adds the Omni MCP server to both Claude Desktop and Claude Code.
      </Step>

      <Step title="Start a new Claude Code session">
        Run `claude` to start a new session. The Omni MCP server will be available automatically.
      </Step>

      <Step title="Authorize the connection">
        1. Claude Code will detect the Omni connector and prompt you to authenticate.
        2. Your browser will open and redirect you to an Omni authorization page.
        3. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Claude Code sessions:

        <img alt="Claude Code session with the Omni MCP server connected" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual CLI Setup">
    You can also add the Omni MCP server manually via the Claude Code CLI.

    <Steps>
      <Step title="Add the Omni MCP server">
        In your terminal, run the following command:

        ```bash theme={null}
        claude mcp add --transport http omni https://callbacks.omniapp.co/callback/mcp
        ```
      </Step>

      <Step title="Start a new Claude session">
        Run `claude` to start a new session.
      </Step>

      <Step title="Authenticate with Omni">
        1. Run `/mcp` to open the MCP servers list:
           <img alt="Claude Code MCP servers list showing Omni needs authentication" />
        2. Navigate to and select the Omni MCP server:
           <img alt="Claude Code MCP server selection" />
        3. Press **Enter** to select the **Authenticate** option.
           <img alt="Claude Code authentication redirect prompt" />
        4. Your browser will open and redirect you to an Omni authorization page.
        5. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Claude Code sessions:

        <img alt="Claude Code session with the Omni MCP server connected" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code Cloud">
    Claude Code Cloud runs agents on your repositories in the cloud. MCP servers are configured by committing a `.mcp.json` file to the root of any repository where you want Omni available.

    <Note>
      You'll need an Omni API key for this setup. See [API authentication](/api/authentication) if you need to create one.
    </Note>

    <Steps>
      <Step title="Create the .mcp.json file">
        In the root of your repository, create a file named `.mcp.json`:

        ```json title=".mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni MCP": {
              "type": "http",
              "url": "https://<YOUR_OMNI_INSTANCE>/mcp/https",
              "headers": {
                "Authorization": "Bearer <OMNI_API_KEY>",
                "X-MCP-Model-ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "X-MCP-Topic-Name": "<OPTIONAL_TOPIC_NAME>",
                "X-MCP-User-Required": "<true/false>",
                "X-MCP-User-ID": "<USER_ID>",
                "X-MCP-Query-All-Views": "<true/false>"
              }
            }
          }
        }
        ```

        Replace the placeholder values:

        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication)
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: `false`)
        * `<USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
        * `<true/false>` for `X-MCP-Query-All-Views` - **Optional**. Set to `true` to enable all-views-and-fields mode, allowing the AI to query any view in the model (not just topics). Requires the model's `query_all_views_and_fields` setting to be enabled. Default: `false`.
      </Step>

      <Step title="Commit the file">
        Commit `.mcp.json` to your repository. When you start a new Claude Code Cloud session on that repository, the MCP server will be loaded automatically.

        **To keep credentials out of version control**, reference environment variables using `${VAR}` syntax instead of hardcoding values:

        ```json title=".mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni MCP": {
              "type": "http",
              "url": "https://${OMNI_INSTANCE}/mcp/https",
              "headers": {
                "Authorization": "Bearer ${OMNI_API_KEY}",
                "X-MCP-Model-ID": "${OMNI_MODEL_ID}",
                "X-MCP-Topic-Name": "${OMNI_TOPIC_NAME}",
                "X-MCP-User-Required": "false",
                "X-MCP-Query-All-Views": "${OMNI_QUERY_ALL_VIEWS}"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Add Cloud Environment variables">
        If you used `${VAR}` references in your `.mcp.json`, add the corresponding values to your Cloud Environment variables (e.g., `OMNI_API_KEY=key`). These are injected at runtime and never stored in your repository.
      </Step>

      <Step title="Start a new session">
        Start a new Claude Code Cloud session from [claude.ai/code](https://claude.ai/code) or the Claude desktop app. When prompted, select the GitHub repository where you committed `.mcp.json`. Claude Code Cloud will detect the file and load the Omni MCP server automatically.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tool denial in 'don't ask' mode">
    Claude Code may sometimes return an error similar to:

    ```bash wrap theme={null}
    Permission to use mcp__omni__pickModel has been denied because Claude Code is running in don't ask mode
    ```

    This mode automatically blocks tools that aren't pre-approved rather than prompting you for approval. To resolve this issue, you have a few options:

    * **Restart Claude Code with the tools allowed**:
      ```bash theme={null}
      claude --allowed-tools 'mcp__omni__*'
      ```
    * **Update your permission settings** to allow MCP tools. Add `mcp__omni__*` to your allowed tools in your Claude Code settings or `.claude/settings.json`
    * **Switch out of 'don't ask' mode**, which will ensure you are prompted to approve tool calls
  </Accordion>
</AccordionGroup>


# Using the MCP Server in Claude Desktop
Source: https://docs.omni.co/ai/mcp/claude-desktop

Connect your Omni data to Claude Desktop with Omni's MCP Server.

Claude Desktop is the app version of Anthropic's AI assistant, Claude. Once successfully connected to Omni, you can interact with your Omni data right in the Claude Desktop interface.

**Looking for Claude Code?** Check out the [Claude Code guide](/ai/mcp/claude-code).

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* The latest version of [Claude Desktop](https://claude.ai/download) installed
* **The MCP Server AI setting** enabled in your Omni instance. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).
* **For API key setup only**: [npm and Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed. Check with:
  ```bash theme={null}
  node -v
  npm -v
  ```

## Setup

Choose your setup method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="Claude Connector (Recommended)">
    The official Omni connector for Claude provides the fastest setup experience with no manual configuration required.

    <Steps>
      <Step title="Install the connector">
        Visit the [Omni Analytics connector](https://claude.com/connectors/omni-analytics) page and click **Add to Claude** to install the connector.
      </Step>

      <Step title="Authorize the connection">
        1. Claude will redirect you to an Omni authorization page.
        2. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Claude Desktop chats.

        In a chat, click the <Icon icon="plus" /> (plus) icon, then **Connectors**. Your Omni MCP connection should be enabled:

        <img alt="Claude Desktop chat with the Omni connector enabled" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Custom OAuth">
    OAuth provides streamlined setup without manually managing API keys. Use this method if you need to configure the connector manually.

    <Steps>
      <Step title="Open Claude Desktop settings">
        In Claude Desktop, navigate to **Settings > Connectors**.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector**.
      </Step>

      <Step title="Configure the connector">
        In the dialog that displays, fill in the following:

        * **Name** - Enter a name for the connector, such as `Omni`
        * **Remote MCP Server URL** - Paste the following URL:

          ```text theme={null}
          https://callbacks.omniapp.co/callback/mcp
          ```

        Your configuration should look like this:

        <img alt="Claude Desktop custom MCP connector configuration dialog" />

        Click **Add** to create the connector.
      </Step>

      <Step title="Authorize the connection">
        Claude Desktop will add the connector to the connector list.

        1. Click the **Connect** button next to the Omni connector you just created.
        2. Your browser will open and redirect you to an Omni authorization page.
        3. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Claude Desktop chats.

        In a chat, click the <Icon icon="plus" /> (plus) icon, then **Connectors**. Your Omni MCP connection should be enabled:

        <img alt="Claude Desktop chat with the Omni connector enabled" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Open Claude Desktop settings">
        In Claude Desktop, navigate to **Settings > Developer**.
      </Step>

      <Step title="Edit the config file">
        Click **Edit Config**. This opens (or creates) `claude_desktop_config.json`.
      </Step>

      <Step title="Add the MCP server">
        Add the following to the `mcpServers` key:

        ```json title="claude_desktop_config.json" theme={null}
        {
          "mcpServers": {
            "Omni MCP": {
              "command": "npx",
              "args": ["@omni-co/mcp"],
              "env": {
                "DEBUG": "true",
                "MCP_SERVER_URL": "https://<YOUR_OMNI_INSTANCE>/mcp/https",
                "MCP_API_KEY": "<OMNI_API_KEY>",
                "MCP_MODEL_ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "MCP_TOPIC_NAME": "<OPTIONAL_TOPIC_NAME>",
                "MCP_USER_REQUIRED": "<true/false>",
                "MCP_USER_ID": "<USER_ID>",
                "MCP_QUERY_ALL_VIEWS": "<true/false>"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Configure the server">
        Replace the placeholder values:

        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL (e.g., `acme.omniapp.co`)
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication)
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:
          ```txt wrap theme={null}
          https://acme.omniapp.co/models/9d9440e5-8522-4507-b092-1ac26ba26673/ide/model
          ```
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: false)
        * `<USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
        * `<true/false>` for `MCP_QUERY_ALL_VIEWS` - **Optional**. Set to `true` to allow the AI to query any view in the model instead of only topics. Requires the model's [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) setting to be enabled. Defaults to `false`.
      </Step>

      <Step title="Restart Claude Desktop">
        Save the file and restart Claude Desktop.
      </Step>

      <Step title="Verify the connection">
        Navigate to **Settings > Developer** and click **Omni MCP**. You should see a `running` badge:

        <img alt="Claude Desktop MCP Server status showing running badge" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, Claude Desktop automatically uses it when you ask questions about your data. You can prompt Claude to use Omni by referring to it by name or description.

1. Enter a prompt in the chat panel, such as `Hey Omni, tell me how many users have been sourced by referrals`.

2. Each time Claude uses an MCP tool, you'll be prompted to approve its usage. Click **Allow once** or **Allow always** to proceed:

   <img alt="Claude Desktop MCP approval prompt" />

3. The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data:

   <img alt="Claude Desktop chat with MCP Server running a query" />


# Using the MCP Server in Codex
Source: https://docs.omni.co/ai/mcp/codex

Connect your Omni data to Codex with Omni's MCP Server.

Codex is OpenAI's agentic coding tool that can connect to external data sources with MCP. Once successfully connected to Omni, you can interact with your Omni data right in your Codex sessions.

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* [Codex](https://openai.com/index/codex/) installed (CLI or IDE extension)
* To have the following enabled in Omni:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp).
  * **Personal access tokens (PATs)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#token-types).

## Setup

Choose your authentication method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth provides streamlined setup without manually managing API keys.

    <Steps>
      <Step title="Add the Omni MCP server">
        In your terminal, run the following command:

        ```bash theme={null}
        codex mcp add omni --url https://callbacks.omniapp.co/callback/mcp
        ```
      </Step>

      <Step title="Start a Codex session">
        Run `codex` to start a new session. Codex will detect the Omni MCP server and initiate the OAuth flow.
      </Step>

      <Step title="Authenticate with Omni">
        1. Your browser will open and redirect you to an Omni authorization page.
        2. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Codex sessions.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Configure the MCP server">
        You can add the server via CLI or by editing the Codex config file directly.

        **Option A: CLI**

        ```bash theme={null}
        codex mcp add omni https://<YOUR_OMNI_INSTANCE>/mcp/https
        ```

        **Option B: Config file**

        Edit `~/.codex/config.toml` (user-level) or `.codex/config.toml` (project-scoped) and add:

        ```toml config.toml theme={null}
        [mcp_servers.omni]
        url = "https://<YOUR_OMNI_INSTANCE>/mcp/https"

        [mcp_servers.omni.http_headers]
        Authorization = "Bearer <OMNI_API_KEY>"
        X-MCP-Model-ID = "<OPTIONAL_OMNI_MODEL_ID>"
        X-MCP-Topic-Name = "<OPTIONAL_TOPIC_NAME>"
        X-MCP-User-Required = "<true/false>"
        X-MCP-User-ID = "<OPTIONAL_OMNI_USER_ID>"
        X-MCP-Query-All-Views = "<true/false>"
        ```
      </Step>

      <Step title="Replace placeholder values">
        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL (e.g., `acme.omniapp.co`)
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication)
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:

          ```txt wrap theme={null}
          https://acme.omniapp.co/models/9d9440e5-8522-4507-b092-1ac26ba26673/ide/model
          ```
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: false)
        * `<OPTIONAL_OMNI_USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
        * `<true/false>` for `X-MCP-Query-All-Views` - **Optional**. Set to `true` to allow the AI to query any view in the model instead of only topics. Requires the model's [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) setting to be enabled. Defaults to `false`.
      </Step>

      <Step title="Verify the connection">
        Start a new Codex session and confirm the Omni MCP server is available.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, Codex automatically uses it when you ask questions about your data. You can prompt Codex to use Omni by referring to it by name or description.

<Steps>
  <Step>
    Start a Codex session and enter a prompt, such as `Hey Omni, tell me how many users signed up last month`.
  </Step>

  <Step>
    Codex may prompt you to approve MCP tool usage. Approve the tool call to proceed.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data.
  </Step>
</Steps>


# Using the MCP Server in Cursor
Source: https://docs.omni.co/ai/mcp/cursor

Connect your Omni data to Cursor with Omni's MCP Server.

Cursor is an AI-powered code editor that can connect with other tools—like Omni!—with MCP. Once successfully connected, you can interact with your Omni data right in Cursor's interface.

**Looking for the Omni agent skills for Cursor?** See the [Agent skills documentation](/developers/agent-skills) for a broader set of skills beyond querying.

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* **A version of [Cursor](https://cursor.sh/) that supports MCP**
* **To have the following enabled in Omni**:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).
  * **Personal access tokens (PATs)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#token-types).

## Setup

Choose your authentication method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth provides streamlined setup without manually managing API keys.

    <Steps>
      <Step title="Open MCP settings">
        In Cursor, click **Cursor > Settings > Cursor settings**.
      </Step>

      <Step title="Add a new MCP server">
        Click **Tools & Integrations** in the settings navigation, then click **New MCP Server** under **MCP Tools**.
      </Step>

      <Step title="Configure the server">
        Cursor will create an `mcp.json` file. Paste the following:

        ```json title="mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni": {
              "url": "https://callbacks.omniapp.co/callback/mcp"
            }
          }
        }
        ```

        Save the file.
      </Step>

      <Step title="Authorize the connection">
        Before you can use the MCP, you'll need to authorize the connection.

        1. Click the **Connect** button next to the MCP.
        2. Your browser will open and redirect you to an Omni authorization page.
        3. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in Cursor chats.

        <img alt="Cursor MCP Server status" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Open MCP settings">
        Open the **Command Palette** (`⌘ + Shift + P` on Mac, `Ctrl + Shift + P` on Windows), search for `MCP`, and select **View: Open MCP Settings**.
      </Step>

      <Step title="Add a new MCP server">
        Click **Tools & Integrations** in the settings navigation, then click **New MCP Server** under **MCP Tools**.
      </Step>

      <Step title="Configure the server">
        Cursor creates an `mcp.json` file. Paste the following:

        ```json title="mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni": {
              "url": "https://<YOUR-OMNI-INSTANCE>/mcp/https",
              "headers": {
                "Authorization": "Bearer <OMNI_API_KEY>",
                "X-MCP-Model-ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "X-MCP-Topic-Name": "<OPTIONAL_TOPIC_NAME>",
                "X-MCP-User-Required": "<true/false>",
                "X-MCP-User-ID": "<OPTIONAL_OMNI_USER_ID>",
                "X-MCP-Query-All-Views": "<true/false>"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Replace placeholder values">
        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL (e.g., `acme.omniapp.co`)
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication). Cursor also supports [environment variables](https://docs.cursor.com/context/model-context-protocol#authentication) for the key.
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:
          ```txt wrap theme={null}
          https://acme.omniapp.co/models/9d9440e5-8522-4507-b092-1ac26ba26673/ide/model
          ```
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: false)
        * `<USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
        * `<true/false>` for `X-MCP-Query-All-Views` - **Optional**. Set to `true` to allow the AI to query any view in the model instead of only topics. Requires the model's [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) setting to be enabled. Defaults to `false`.

        Save the file.
      </Step>

      <Step title="Verify the connection">
        Check the server's status in **Settings**:

        <img alt="Cursor MCP Server status" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, Cursor automatically uses it when you ask questions about your data. You can prompt Cursor to use Omni by referring to it by name or description.

<Steps>
  <Step>
    Open the AI pane/chat panel and select **Agent** mode:

    <img alt="Cursor chat panel with Agent mode selected" />
  </Step>

  <Step>
    Enter a prompt, such as `Hey Omni, tell me how many users have been sourced by search and email`.
  </Step>

  <Step>
    Each time Cursor uses an MCP tool, you'll be prompted [to approve its usage](https://docs.cursor.com/context/model-context-protocol#tool-approval). Click **Run tool** to proceed.

    <img alt="Cursor MCP tool approval prompt" />

    You can also use Cursor's [Yolo mode](https://docs.cursor.com/chat/agent#yolo-mode) to automatically run MCP tools without requiring approval.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data:

    <img alt="Cursor running an MCP query" />
  </Step>
</Steps>


# AI MCP Server
Source: https://docs.omni.co/ai/mcp/index

Unlock new ways to analyze & explore your data by connecting external AI tools to your Omni model with Omni's MCP Server.

The Omni MCP Server enables natural language querying across your datasets, similar to how you’d interact with Omni, while taking advantage of the enhanced context, reasoning, or memory capabilities of external AI tools.

For example, you could include the results of a web search as additional context to the MCP before running an Omni query.

<img alt="MCP Server in Cursor" />

## Features

* **Natural language querying** – Ask questions using natural language and let Omni translate it into a query
* **Iterative, multi-step analysis** – Chain queries together, retain results in memory, and perform deeper analysis across steps
* **Flexible integration** - Connect to a variety of compatible AI clients to expand beyond Omni's native chat experience
* **Dynamic model selection** - Switch between Omni models during a session without reconfiguring the MCP Server
* **Scoped, secure data access** – Interactions are scoped only to the model (and topic, if provided) supplied to the MCP, preventing unauthorized data access when querying
* **User level permissioning** - MCP queries can be scoped to the permissions of a given user to pass through security from Omni's semantic layer

## Tools

The MCP Server includes tools for querying Omni data and searching the official Omni docs for product and *"How do I..."*-type questions. See [MCP server tools](/ai/mcp/tools) for more information.

## Authentication

The Omni MCP Server supports two authentication methods:

* **OAuth 2.1** - **Recommended**. Streamlined setup through your browser. Omni creates API keys on your behalf automatically. Requires [**Personal Access Tokens (PATs)**](/api/authentication#token-types) to be enabled for your organization.
* **API key** - Manual key creation for centralized management or automated workflows.

See the [MCP authentication guide](/ai/mcp/authentication) for more information.

## Data access and security

* **Data access** - Interactions are scoped only to the model (and topic, if provided) supplied to the MCP, preventing unauthorized data access when querying
* **User permissions** - All MCP queries use the permissions of the authenticated user, ensuring proper data access controls
* **Data handling & security** - Data returned from queries run by the MCP is handled the same way it is for [Omni's other AI features](/ai/security). **Note**: By using the MCP Server, your data will be in the tool where you use the MCP Server. For example, if you use Cursor with the MCP Server, your data would be in Cursor.

## Requirements

To use the MCP Server, an Organization Admin must enable the following settings:

* **Enable AI** in **Settings > General** and **Omni Agent** in [**AI Hub > Features**](/ai/settings/features). These are required to use the MCP Server's querying tools, which are also used by the in-app Omni Agent.
* **MCP server** in [**AI Hub > MCP**](/ai/settings/mcp), plus the individual tool settings you plan to use - note that **Single shot query generation** (`getData`) is disabled by default
* For OAuth authentication, [**Personal Access Tokens**](/api/authentication#token-types)

## Getting started

Ready to get started? Check out the setup guides for the clients we've tested for compatibility:

<Columns>
  <Card title="ChatGPT" href="/ai/mcp/chatgpt" icon="message-bot">
    OpenAI's AI assistant with developer mode
  </Card>

  <Card title="Claude Code" href="/ai/mcp/claude-code" icon="code">
    Command-line based version of Anthropic Claude
  </Card>

  <Card title="Claude Desktop" href="/ai/mcp/claude-desktop" icon="desktop">
    App version of Anthropic Claude
  </Card>

  <Card title="Codex" href="/ai/mcp/codex" icon="terminal">
    OpenAI's agentic coding tool
  </Card>

  <Card title="Cursor" href="/ai/mcp/cursor" icon="arrow-pointer">
    AI-powered IDE designed for fast, agentic programming
  </Card>

  <Card title="Microsoft Copilot" href="/ai/mcp/microsoft-copilot" icon="robot">
    Microsoft's AI assistant, configured through Copilot Studio
  </Card>

  <Card title="Visual Studio Code" href="/ai/mcp/vscode" icon="microsoft">
    Popular open-source IDE with powerful AI features
  </Card>
</Columns>

## Improving results

To get the best results, we recommend:

1. Optimizing your Omni models for AI. Refer to [this guide](/modeling/develop/ai-optimization) to learn how to curate your models and include context.
2. Rating the results that the AI returns


# Using the MCP Server in Microsoft Copilot
Source: https://docs.omni.co/ai/mcp/microsoft-copilot

Connect your Omni data to Microsoft Copilot with Omni's MCP Server.

Microsoft Copilot can use Omni as a data source through MCP. You add the Omni MCP Server to an agent in [Microsoft Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp), then use that agent from Microsoft Copilot to ask questions about your data.

<Note>
  Custom MCP servers aren't added in the Microsoft Copilot chat assistant directly; they're added through Copilot Studio. You'll set up the connection on a Copilot Studio agent, then surface that agent in Microsoft Copilot.
</Note>

## Requirements

<Note>
  Every person who wants to use the MCP Server must create their own connection.
</Note>

To follow the steps in this guide, you'll need:

* The following in Microsoft Copilot Studio:
  * **A Copilot Studio environment** where you have permission to create and edit agents and tools.
  * **[Generative orchestration](https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-generative-actions) enabled** on the agent, which is required to use MCP tools.
* The following in Omni:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).
  * **Personal access tokens (PATs)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#token-types).

## Setup

Choose an authentication method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help deciding.

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth provides streamlined setup without manually managing API keys.

    <Steps>
      <Step title="Add the MCP Server">
        1. In Copilot Studio, open your agent and go to the **Tools** page.
        2. Select **Add a tool**, then **New tool**.
        3. Select **Model Context Protocol** to open the MCP wizard.
        4. Fill in the following fields:
           * **Server name** — Enter a name, such as `Omni`
           * **Server description** — Enter a description, such as `Connect to Omni analytics data`
           * **Server URL** — Paste the OAuth URL:
             ```txt theme={null}
             https://callbacks.omniapp.co/callback/mcp
             ```
      </Step>

      <Step title="Configure authentication">
        1. Set **Authentication** to **OAuth 2.0**.
        2. Select **Dynamic Discovery**.
        3. Select **Create**.
      </Step>

      <Step title="Authorize the connection">
        1. On **Add tool**, select **Create a new connection**.
        2. Your browser will open and redirect you to an Omni authorization page.
        3. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Add the tool to your agent">
        Select **Add to agent** to finish. Confirm [generative orchestration](https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-generative-actions) is enabled on the agent so it can call the MCP tools.
      </Step>

      <Step title="Verify the connection">
        Open the **Test your agent** pane in Copilot Studio and send a trivial prompt such as `Hey Omni, what models can you access?`. If the agent invokes the Omni tool and returns a response, the connection is working.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Add the MCP Server">
        1. In Copilot Studio, open your agent and go to the **Tools** page.
        2. Select **Add a tool**, then **New tool**.
        3. Select **Model Context Protocol** to open the MCP wizard.
        4. Fill in the following fields:

           * **Server name** — Enter a name, such as `Omni`
           * **Server description** — Enter a description, such as `Connect to Omni analytics data`
           * **Server URL** — Enter your instance URL with `/mcp/https` appended:
             ```txt theme={null}
             https://<YOUR_OMNI_INSTANCE>/mcp/https
             ```

           Replace `<YOUR_OMNI_INSTANCE>` with your Omni URL (e.g., `acme.omniapp.co`).
      </Step>

      <Step title="Configure authentication">
        1. Set **Authentication** to **API Key**.
        2. Set **Type** to **Header**.
        3. Set the **Parameter name** to `Authorization`.
        4. Select **Create**.
      </Step>

      <Step title="Add the tool to your agent">
        1. On **Add tool**, select **Create a new connection**.
        2. When prompted for the API key, enter your [Omni API key](/api/authentication) prefixed with `Bearer `:
           ```txt theme={null}
           Bearer <OMNI_API_KEY>
           ```
        3. Select **Add to agent** to finish.

        <Note>
          Copilot Studio's MCP tool sends a single authentication header, so the optional `X-MCP-*` headers used to scope other clients (model ID, topic, user) can't be set here. To scope queries, configure the model and topic in Omni instead.
        </Note>
      </Step>

      <Step title="Verify the connection">
        Open the **Test your agent** pane in Copilot Studio and send a trivial prompt such as `Hey Omni, what models can you access?`. If the agent invokes the Omni tool and returns a response, the connection is working.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is added to your agent, Copilot Studio uses it automatically when you ask questions about your data.

<Steps>
  <Step>
    Confirm [generative orchestration](https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-generative-actions) is enabled on the agent.
  </Step>

  <Step>
    In the Copilot Studio test pane, enter a prompt such as `Hey Omni, tell me how many users have been sourced by search and email`. Once the agent is published, you can send the same prompt from Microsoft Copilot.
  </Step>

  <Step>
    If prompted, approve the tool invocation to proceed.
  </Step>

  <Step>
    The MCP Server will pick a model and topic, then run a query to retrieve the data.
  </Step>
</Steps>

To make the agent available to end users in Microsoft Copilot, [publish it from Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/publication-fundamentals-publish-channels) and add it to Microsoft Copilot.


# MCP server tools
Source: https://docs.omni.co/ai/mcp/tools

Unlock new ways to analyze & explore your data by connecting external AI tools to your Omni model with Omni's MCP server.

The MCP server includes tools for querying Omni data and searching the official Omni docs for product and *"How do I..."*-type questions.

## Tool availability

To use the MCP server tools, the following settings must be enabled:

* The top-level **MCP server** setting in [**AI Hub > MCP**](/ai/settings/mcp). Enabled by default.
* The **Enable AI** and **Omni Agent** settings in [**AI Hub > Features**](/ai/settings/features#workbook-agent). The MCP querying and docs search tools use the same AI pipeline as the Omni Agent, so disabling **Omni Agent** disables every MCP tool except `pickModel`. The tools will still appear in your MCP client, but calls will return `403 Feature is not enabled` errors.

Organization Admins can also individually enable or disable tool capabilities in the MCP settings page.

If certain tools are not available in your MCP client, check with an Organization Admin to confirm which capabilities are enabled for your organization.

## Querying

The MCP server uses the tools in this section to process the queries it receives.

### pickModel

Returns a list of available models and their IDs, which the MCP client uses to select which model to query. You can also provide a model ID in the MCP configuration to skip this step.

This tool is available if the [Agentic capabilities](/ai/settings/mcp#agentic) or [Single shot query generation setting](/ai/settings/mcp#single-shot) is enabled.

### pickTopic

Returns available topics in the model selected by [`pickModel`](#pick-model) and selects the most relevant topic for the query.

If the AI is allowed to query any view in the model (enabled with the `X-MCP-Query-All-Views` header during setup), this step becomes optional: the AI can query any view in the model directly, not just topics.

This tool is available if the [Agentic capabilities](/ai/settings/mcp#agentic) or [Single shot query generation setting](/ai/settings/mcp#single-shot) is enabled.

### getData

<Note>
  The [Single shot query generation setting](/ai/settings/mcp#single-shot) must be enabled to use this tool.
</Note>

Executes the query against the selected model and topic (or view, if the AI can query outside of topics) and returns the results.

### runQuery

<Note>
  The [Single shot query generation setting](/ai/settings/mcp#single-shot) must be enabled to use this tool.
</Note>

Accepts a JSON query definition and executes it directly against the [Run query API](/api/queries/run-query), without requiring the AI to construct a query from a model and topic selection. Use this tool when the query JSON is already known — for example, you paste a query definition or the query definition was produced earlier in the conversation.

When using this tool, note that:

* Results default to a limit of 500 rows and cap at 10,000
* Keys such as `userEditedSQL` that would cause the query to run raw SQL against the connection will be refused
* If a model is provided with the `X-MCP-Topic-Name` header during setup and `query.modelId` is also provided, they must match or the request will fail

## Advanced agentic queries

<Note>
  The [Agentic capabilities setting](/ai/settings/mcp#agentic) must be enabled to use the tools in this section.
</Note>

For complex, multi-step questions that require deeper analysis beyond what a single query can provide, the MCP server includes two additional tools that expose Omni's full agentic AI assistant: `askOmni` and `checkStatus`. Using these tools together prevents timeout issues that could occur if waiting for long-running agentic jobs to complete in a single request.

### askOmni

Submits an agentic analysis job to Omni and returns immediately without waiting for completion. Designed for open-ended questions that may require multiple steps, data exploration, or iterative analysis. When a `branchId` is provided, the agentic job runs its queries against that [model branch](/content/develop/branch-mode) and any model edits the agent makes are saved to that branch rather than creating a new one.

This tool can also:

* [**Create and edit dashboards.**](/ai/chat#creating-dashboards) - When you ask the agent to edit an existing dashboard, the changes land in a [draft](/content/develop/drafts). The changes won't be live until you review and manually publish the changes. Brand new dashboards created by the agent are published immediately.
* [**Create and find routines.**](/ai/routines). Ask for something recurring (*"every Monday at 9am, email me a summary of last week's signups"*) and the agent sets up a scheduled prompt that runs with your permissions and delivers by email or Slack. You can also find or list your existing routines (*"what do I have scheduled?"*) and the agent returns matches as edit links.

### checkStatus

Polls the status of a previously submitted job using its `jobId`.

### listBranches

Lists existing branches of a given base model. Use this tool alongside `askOmni`'s `branchId` parameter to target an existing branch instead of creating a new one.

This tool does not honor the `X-MCP-User-ID` impersonation header. When using an Organization API key, the results reflect the API key owner's permissions rather than the impersonated user's permissions.

## Content access

<Note>
  The [Content access setting](/ai/settings/mcp#content-access) must be enabled to use the tools in this section.
</Note>

Allows the MCP server to search your organization's saved content, like dashboards, see the queries a dashboard contains, and run them.

### searchDashboards

Searches your Omni organization for existing dashboards that match a provided name, folder, or tile name. This helps prevent generating new queries for data that already exists in a saved dashboard.

Search results are scoped using the calling user's API key or the `X-MCP-User-ID` impersonation header (if provided), ensuring that results reflect what the user can access according to their content and model permissions.

### listDashboardQueries

Lists a dashboard's tiles (saved queries). This tool is designed to pair with `searchDashboards` — search finds the dashboard, this tool shows what it contains.

This tool does not honor the `X-MCP-User-ID` impersonation header. When using an Organization API key, the results reflect the API key owner's permissions rather than the impersonated user's permissions.

### runSavedQuery

Executes a saved dashboard tile's query by ID and returns the current results as JSON. This tool is designed for pulling consistent, model-aware data from a known tile rather than generating a new query.

If an invalid or inaccessible `queryId` is provided, the tool returns an error without listing tile names to prevent information disclosure beyond impersonation scope. Use [`listDashboardQueries`](#list-dashboard-queries) to retrieve valid query IDs for a dashboard.

Query results are scoped using the calling user's API key or the `X-MCP-User-ID` impersonation header (if provided), ensuring that data access safeguards such as row-level security (RLS) and access grants are respected.

### startDashboardDownload

Starts an asynchronous job to download a dashboard as a PNG file, using the [Initiate dashboard download API](/api/dashboard-downloads/initiate-download). The tool only accepts a dashboard identifier — none of the other options in the UI's download dialog (such as row limits or paper size) are exposed to the model, since a PNG is the only format the tool requests.

This tool honors the `X-MCP-User-ID` impersonation header: the download job is created as the impersonated user.

Only one download job can run per user per dashboard at a time. If a download is already in progress, the tool returns an error that names the existing job's ID and points to [`checkDashboardDownload`](#check-dashboard-download) and [`fetchDashboardDownload`](#fetch-dashboard-download).

### checkDashboardDownload

Polls the status of a dashboard download job started by [`startDashboardDownload`](#start-dashboard-download), using its `jobId`.

This tool honors the `X-MCP-User-ID` impersonation header.

### fetchDashboardDownload

Retrieves the finished PNG file for a completed dashboard download job, using its `jobId`. Files larger than 10 MB are refused. When this happens, the tool explains how to download the file directly from the API instead.

This tool honors the `X-MCP-User-ID` impersonation header.

## Search Omni docs (searchOmniDocs)

<Note>
  The [Omni documentation search setting](/ai/settings/mcp#doc-search) must be enabled to use this tool.
</Note>

Searches the Omni documentation and synthesizes answers in response to prompts that ask questions about how to use Omni. Responses include citations to documentation pages used to construct the answer to the prompt. This tool uses the same AI-powered search pipeline as the Omni Agent, ensuring accurate and contextually relevant responses.

For example, you could ask *"How do I create a calculated field in Omni?"* and the `searchOmniDocs` tool will search the documentation, analyze the relevant pages, and return a comprehensive answer with links to the source documentation.

## Tool and setting comparison

The following table shows what MCP tools are available if a specific [MCP setting](/ai/settings/mcp) is enabled.

| MCP tool                                            | Agentic<br />capabilities | Omni documentation search | Single shot<br />query<br />generation | Content<br />access |
| --------------------------------------------------- | ------------------------- | ------------------------- | -------------------------------------- | ------------------- |
| [pickModel](#pick-model)                            | <CheckIcon /> yes         | <XCircleIcon /> no        | <CheckIcon /> yes                      | <XCircleIcon /> no  |
| [pickTopic](#pick-topic)                            | <CheckIcon /> yes         | <XCircleIcon /> no        | <CheckIcon /> yes                      | <XCircleIcon /> no  |
| [getData](#get-data)                                | <XCircleIcon /> no        | <XCircleIcon /> no        | <CheckIcon /> yes                      | <XCircleIcon /> no  |
| [runQuery](#run-query)                              | <XCircleIcon /> no        | <XCircleIcon /> no        | <CheckIcon /> yes                      | <XCircleIcon /> no  |
| [askOmni](#ask-omni)                                | <CheckIcon /> yes         | <XCircleIcon /> no        | <XCircleIcon /> no                     | <XCircleIcon /> no  |
| [checkStatus](#check-status)                        | <CheckIcon /> yes         | <XCircleIcon /> no        | <XCircleIcon /> no                     | <XCircleIcon /> no  |
| [listBranches](#list-branches)                      | <CheckIcon /> yes         | <XCircleIcon /> no        | <XCircleIcon /> no                     | <XCircleIcon /> no  |
| [searchDashboards](#search-dashboards)              | <XCircleIcon /> no        | <XCircleIcon /> no        | <XCircleIcon /> no                     | <CheckIcon /> yes   |
| [listDashboardQueries](#list-dashboard-queries)     | <XCircleIcon /> no        | <XCircleIcon /> no        | <XCircleIcon /> no                     | <CheckIcon /> yes   |
| [runSavedQuery](#run-saved-query)                   | <XCircleIcon /> no        | <XCircleIcon /> no        | <XCircleIcon /> no                     | <CheckIcon /> yes   |
| [startDashboardDownload](#start-dashboard-download) | <XCircleIcon /> no        | <XCircleIcon /> no        | <XCircleIcon /> no                     | <CheckIcon /> yes   |
| [checkDashboardDownload](#check-dashboard-download) | <XCircleIcon /> no        | <XCircleIcon /> no        | <XCircleIcon /> no                     | <CheckIcon /> yes   |
| [fetchDashboardDownload](#fetch-dashboard-download) | <XCircleIcon /> no        | <XCircleIcon /> no        | <XCircleIcon /> no                     | <CheckIcon /> yes   |
| [searchOmniDocs](#search-omni-docs)                 | <XCircleIcon /> no        | <CheckIcon /> yes         | <XCircleIcon /> no                     | <XCircleIcon /> no  |

## Related

* [AI MCP settings](/ai/settings/mcp) - Enable and disable MCP server tool capabilities
* [AI feature settings](/ai/settings/features) - Enable and disable individual AI features in your Omni organization
* [AI Hub](/administration/ai-hub) - Monitor how your organization uses Omni AI


# Using the MCP Server in Visual Studio Code
Source: https://docs.omni.co/ai/mcp/vscode

Connect your Omni data to Visual Studio Code with Omni's MCP Server.

Visual Studio Code (VS Code) is a code editor that, when paired with GitHub Copilot, empowers development with AI-backed features. VS Code can connect with other tools—like Omni!—using MCP. Once successfully connected, you can interact with your Omni data right in VS Code's interface.

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* The latest version of [VS Code](https://code.visualstudio.com/) installed
* Access to [Copilot](https://code.visualstudio.com/docs/copilot/setup), which VS Code uses to run its [AI in Agent mode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
* To have the following enabled in Omni:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to [**AI Hub > MCP**](/ai/settings/mcp#mcp-server).
  * **Personal access tokens (PATs)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#token-types).

## Setup

Choose your authentication method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth provides streamlined setup without manually managing API keys.

    <Steps>
      <Step title="Add the MCP Server">
        1. Open the **Command Palette** (`⌘ + Shift + P` on Mac, `Ctrl + Shift + P` on Windows).
        2. Search for `MCP` and select **MCP: Add Server**.
        3. Select **HTTP (HTTP or Server-Sent events)** and press **Enter**.
        4. Paste the OAuth URL and press **Enter**:
           ```txt theme={null}
           https://callbacks.omniapp.co/callback/mcp
           ```
        5. Enter a name for the server (e.g., `Omni MCP`) and press **Enter**.
        6. Select **Global** or **Workspace settings** and press **Enter**.
      </Step>

      <Step title="Start the MCP Server">
        VS Code should open a file named `mcp.json` and automatically prompt you to authorize the connection:

        <img alt="" />

        If this doesn't happen, complete the following:

        1. Open the **Command Palette** again.

        2. Search for `MCP` and select **MCP: List Servers**.

        3. Click the **Omni** server in the list.

        4. Click **Start Server** or **Restart** above the server in the `mcp.json` file:

           <img alt="" />

        5. When prompted, allow VS Code to open the browser.
      </Step>

      <Step title="Authorize the connection">
        1. Your browser will open and redirect you to an Omni authorization page.
        2. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#token-types) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        You should see logs in the **Terminal** panel indicating the server started:

        ```shell theme={null}
        [info] Starting server Omni
        [info] Connection state: Starting
        [info] Starting server from LocalProcess extension host
        [info] Connection state: Running
        [info] Discovered 3 tools
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Add the MCP Server">
        1. Open the **Command Palette** (`⌘ + Shift + P` on Mac, `Ctrl + Shift + P` on Windows).
        2. Search for `MCP` and select **MCP: Add Server**.
        3. Select **HTTP (HTTP or Server-Sent events)** and press **Enter**.
        4. Paste your Omni instance URL with `/mcp/https` appended:
           ```txt theme={null}
           https://<YOUR_OMNI_INSTANCE>/mcp/https
           ```
        5. Enter a name for the server (e.g., `Omni MCP`) and press **Enter**.
        6. Select **Workspace Settings** and press **Enter**.
      </Step>

      <Step title="Configure the MCP Server">
        A `.vscode/mcp.json` file was created in your project. Open it and update it to include headers:

        ```json title=".vscode/mcp.json" theme={null}
        {
          "inputs": {
            "type": "promptString",
            "id": "omni-mcp-key",
            "description": "API key for Omni Data MCP",
            "password": true
          },
          "servers": {
            "Omni": {
              "url": "https://<YOUR_OMNI_INSTANCE>/mcp/https",
              "headers": {
                "Authorization": "Bearer <OMNI_API_KEY>",
                "X-MCP-Model-ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "X-MCP-Topic-Name": "<OPTIONAL_TOPIC_NAME>",
                "X-MCP-User-Required": "<true/false>",
                "X-MCP-User-ID": "<OPTIONAL-OMNI-USER-ID>",
                "X-MCP-Query-All-Views": "<true/false>"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Replace placeholder values">
        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL (e.g., `acme.omniapp.co`)
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication)
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:
          ```txt wrap theme={null}
          https://acme.omniapp.co/models/9d9440e5-8522-4507-b092-1ac26ba26673/ide/model
          ```
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: false)
        * `<USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
        * `<true/false>` for `X-MCP-Query-All-Views` - **Optional**. Set to `true` to allow the AI to query any view in the model instead of only topics. Requires the model's [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) setting to be enabled. Defaults to `false`.

        Save the file.
      </Step>

      <Step title="Start the MCP Server">
        1. Open the **Command Palette** again
        2. Search for `MCP` and select **MCP: List Servers**
        3. Click the **Omni** server in the list
        4. Click **Start Server**

        You should see logs in the **Terminal** panel indicating the server started:

        ```shell theme={null}
        [info] Starting server Omni
        [info] Connection state: Starting
        [info] Starting server from LocalProcess extension host
        [info] Connection state: Running
        [info] Discovered 2 tools
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, VS Code automatically uses it when you ask questions about your data. You can prompt VS Code to use Omni by referring to it by name or description.

<Steps>
  <Step>
    Open the chat panel (`⌃ + ⌘ + I` on Mac, `Ctrl + Alt + I` on Windows).
  </Step>

  <Step>
    Select [**Agent** mode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_use-mcp-tools-in-agent-mode).
  </Step>

  <Step>
    Enter a prompt, such as `Hey Omni, tell me how many users have been sourced by search and email`.
  </Step>

  <Step>
    By default, you need to confirm each tool invocation. Click **Continue** to proceed.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured for API key authentication) and topic, then run a query to retrieve the data.
  </Step>
</Steps>


# Modeling Agent
Source: https://docs.omni.co/ai/model-assistant

Chat with AI while you edit your semantic model in the Model IDE—ask questions, draft YAML, and choose how changes are applied.

The **Modeling Agent** is a chat panel in the [Model IDE](/modeling/develop/guides/model-ide) designed to help you build and maintain your semantic model. Use it to ask questions about your model, get suggestions for fields and relationships, and work through YAML edits.

<Note>
  The Modeling Agent is grounded in your **current model and connection** (topics, views, relationships, and [field-level access controls](/modeling/develop/data-access-control)), not arbitrary SQL against your warehouse. To improve answers across Omni AI, see [Optimize models for Omni AI](/modeling/develop/ai-optimization).
</Note>

## Requirements

To use the Modeling Agent, you need:

* The **Omni Agent** setting enabled in [**AI Hub > General > Features**](/administration/ai-hub) for your organization
* Permission to open and edit models in the **Model IDE** for your connection (see [modeling permissions](/modeling/develop/guides/permissions-content-org))

## Open the Modeling Agent

1. Open a model in the **Model IDE**.
2. In the **IDE rail**, click **Show Modeling Agent** (sparkles icon) to open the chat panel.
3. Type in the prompt box. Your conversation stays in the panel while you switch files, save, or change modeling modes.

## Example prompts

You can ask in plain language. You do not need to paste YAML unless you want to point at something specific.

```txt theme={null}
How do the customers and orders views relate in this model?
```

```txt theme={null}
Identify opportunities to improve AI context given this chat prompt: "How is my pipeline doing?"
- conflicting context
- redundant context
- missing context

Make sure to flag if any assumptions are being made so the user can make clarifications,

Update the model with your recommendations:
1. Write `ai_context` mapping business terms to fields
  - **Data nuances** — explain what isn't obvious from field names
2. Add `synonyms` to key dimensions and measures
  - Map alternative names, abbreviations, and domain-specific terminology so the Omni Agent matches user queries to the correct field. Works on both dimensions and measures.
  - **Synonyms vs ai_context**: Use `synonyms` for field-level name mapping. Use `ai_context` for topic-level behavioral guidance, data nuances, and multi-field relationships.
3. Curate `ai_fields` to remove noise
  - Reduce noise for large models
4. Improve field `description` values
  - Good descriptions help both the Omni Agent and human analysts.
```

```txt theme={null}
Read the docs for skills and generate one based on the above prompt.
```

```txt theme={null}
Create a dimension that groups the margin field in order_items into logical bins
```

```txt theme={null}
Create a topic that groups our sales-related tables for self-serve reporting.
```

```txt theme={null}
Fix the model validation errors
```

```txt theme={null}
Update every revenue measure so they are all formatted with currency_2
```

## Built-in skills

The Modeling Agent includes default skills that appear as clickable buttons below the prompt box. These skills guide the agent through specialized tasks without requiring you to write detailed prompts.

### Optimize topic for AI

The **Optimize topic for AI** skill analyzes a topic and its views to identify opportunities for improving AI metadata. When you click this skill, the Modeling Agent asks which topic to analyze, then reviews metadata across four categories:

* **Token efficiency** — Identifies verbose or redundant metadata and flags missing `ai_fields` directives that could reduce token usage
* **Clarity** — Highlights ambiguous fields missing context and non-descriptive labels that may confuse the AI
* **Deduplication** — Finds repeated information between `ai_context` and `description` fields, or between field-level and topic-level metadata
* **Sample queries** — Reviews existing sample queries and recommends additions or improvements, including suggestions for golden datasets

After the analysis, the Modeling Agent provides specific recommendations and can apply changes directly to your model.

<Tip>
  Use this skill regularly when building or updating topics to ensure your AI metadata supports high-quality query generation and reduces unnecessary token consumption. For guidance on AI optimization beyond this skill, see [Optimize models for Omni AI](/modeling/develop/ai-optimization).
</Tip>

### Suggest model from query history

<Note>
  This skill applies to [Snowflake](/connect-data/setup/snowflake) and [Postgres](/connect-data/setup/postgres) connections. Each database has specific requirements:

  * **Snowflake**: The database user must have `IMPORTED PRIVILEGES` on the `SNOWFLAKE` database.
    ```sql theme={null}
    GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE <omni_role>;
    ```

  * **Postgres**: The `pg_stat_statements` extension must be enabled.
    ```sql theme={null}
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    ```
</Note>

The **Suggest model from query history** skill analyzes actual SQL query patterns from your warehouse to help generate semantic models based on real usage. When you click this skill, the Modeling Agent analyzes query history from `ACCOUNT_USAGE.QUERY_HISTORY` (Snowflake) or `pg_stat_statements` (Postgres) and provides insights across several areas:

* **Table usage** — Identifies the most frequently queried tables, with breakdowns showing which tables are used as base tables versus joined tables
* **Column patterns** — Tracks how columns are used in `SELECT`, `WHERE`, `GROUP BY`, and `ORDER BY` clauses, along with aggregation function frequencies
* **Join patterns** — Discovers common join relationships between tables, deduplicated by join type and keys
* **Field classification** — Suggests which fields should be dimensions, measures, or time dimensions based on usage patterns
* **Calculated dimensions** — Identifies scalar transforms and common calculated field patterns that could be defined in your model
* **Query view candidates** — Finds repeated CTE patterns that could be extracted as reusable query views

The agent uses these insights to suggest views, measures (with appropriate `aggregate_type` and symmetric aggregation settings), relationships (with `reversible` semantics), and query views that align with how your team actually queries the data.

## Modeling modes

The panel includes a **mode** menu so you control how proposed model changes are applied. Your selected mode persists between sessions.

| Mode        | How it works                                                                              | Best for                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Sandbox** | Proposes all changes at once. You review and accept or reject before anything is written. | Exploring ideas, pressure-testing updates, and reviewing larger changes before they enter the model. |
| **Review**  | Writes changes, then pauses for your approval before continuing.                          | Step-by-step collaboration when you want close oversight as changes are made.                        |
| **Auto**    | Applies changes immediately, including branch creation, without pausing.                  | Fast iteration when you're already working on a [branch](/content/develop/branch-mode).              |

In **Sandbox** mode, all proposed changes are bundled and presented as expandable diffs for each affected file. You make a single **Accept all** or **Reject all** decision before anything is written to the model.

<Note>
  If you edit the **shared** model, your workflow may require a **branch** before the Modeling Agent can write changes. Create a branch from the IDE when prompted, then continue the conversation.
</Note>

## Next steps

* [Model IDE](/modeling/develop/guides/model-ide) — Files, branching, and validation
* [Branch Mode](/content/develop/branch-mode) — Isolate model edits before promotion
* [Content validator](/modeling/develop/content-validator) — Catch issues across workbooks and dashboards
* [AI settings](/administration/ai-hub) — Org-wide AI controls

## Troubleshooting

<AccordionGroup>
  <Accordion title="I don't see the sparkles / Show Modeling Agent control.">
    Confirm **Use Omni Agent** is on in [**AI Hub > General > Features**](/administration/ai-hub) and that your role can access the Model IDE for the connection.
  </Accordion>

  <Accordion title="The Modeling Agent won't apply edits">
    On the shared model you may need a **branch** first. Create a branch in the IDE, then ask again.
  </Accordion>

  <Accordion title="Answers feel generic">
    Add richer descriptions, [AI context](/modeling/models/ai-context) on views and topics, and [sample queries](/modeling/models/sample-queries) so Omni's AI has more to work with across the product.
  </Accordion>
</AccordionGroup>

## Getting help

If you're stuck and can't remember how to do something in Omni, ask the Omni Agent. Questions like *"How do I do \[thing]?"* will prompt the agent to search the official Omni docs and provide you with an answer, all without leaving your Omni workflow.

You can also directly tell the agent to search the docs when researching the answer to your question.

<Note>
  **Working in an embedded context?** If you have the **Hide Omni watermark** setting enabled to provide a fully white-labeled experience, the AI doc search feature will respect it. Omni doc links will not be returned in chat, even if explicitly requested.
</Note>


# Building queries & filters with AI
Source: https://docs.omni.co/ai/queries

Create, iterate, filter, and summarize queries with natural language.

The Workbook Agent enables conversational analytics that take the need for technical know-how out of data analysis.

## Workbook Agent

<Note>
  This feature requires enabling the **Omni Agent** setting in [AI settings](/ai/settings/features#workbook-agent).
</Note>

The Workbook Agent can help you create and refine workbook queries using natural language. You can ask questions like:

<img alt="What was the total revenue for the last three months? How many new users signed up last month? How many support tickets are submitted on weekends?" />

The Workbook Agent will either provide a text response or generate a query in the workbook.

## Generating queries

How you access the Workbook Agent differs depending on whether you're using an embedded Omni instance or not:

* **Embedded** - Click the <Icon icon="sparkles" /> icon in the sidebar
* **Non-embedded Omni** - Click the floating avatar to open the chat panel

A panel will open next to the field browser with some tips about how to use the agent, as well as a text box to ask your first question.

In addition to generating queries, the Workbook Agent can also:

* **Iterate on the questions you ask to provide a more refined result**. For example:

  ```txt theme={null}
  You: How many orders did we have in California?
  Omni Agent: 1,005
  You: How about in just the last 30 days?
  Omni Agent: 126
  ```

  **Note**: Closing the Workbook Agent will delete the text history.

- **Add totals to results**, such as adding a [column total](/analyze-explore/point-click-queries#column-totals) that sums a **Sale Price** measure
- **Create new measure fields**, such as a **Sale Price Average**
- **Attach images** by pasting from your clipboard to provide visual context (for example, pasting a screenshot of a chart you want to analyze)

  To attach an image, copy it to your clipboard and paste it directly into the Workbook Agent text input. The image appears as a file chip, ready to be sent with your message.

  <Note>
    The **Workbook Agent > File uploads** [AI setting](/ai/settings/features#file-uploads) must be enabled to use this feature.
  </Note>

<Tip>
  Along with the Workbook Agent in the workbook, you can also use the [Generate an AI query API](/api/ai/generate-a-query) to interact with it. You can then use the response to run the query with the [Run a query API](/api/queries/run-query).

  If your model has [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) enabled and you want to query views outside of topics via the API, set the `queryAllViews` parameter to `true`.
</Tip>

## Creating filters

Make filtering easier by having the agent create filters for you using natural language. You can describe a filter like *Only include orders created on a Saturday* or *Exclude customers with a status of deactivated* and the agent will automatically apply the filter to the query.

## Summarizing query results

<Note>
  This feature requires enabling the **Omni Agent** setting in [AI settings](/ai/settings/features#workbook-agent).
</Note>

In addition to helping you build queries, the agent can also summarize the results of the query for you. For example, you can ask the agent to:

* Describe any anomalies in the data
* Identify insights into trends
* Detail the next steps you should take

To get started, enter a prompt directly in the Workbook Agent. To make a summary part of a dashboard, use the [**AI summary visualization**](/visualize-present/visualizations/types/ai-summary).

## Generating forecasts

The agent can generate statistical forecasts for time-series data. Refer to [Generating forecasts with AI](/ai/forecasting) to learn more.

## Generating visualizations

The agent can also generate visualizations based on your query results. Refer to [Generating visualizations with AI](/ai/visualizations) to learn more.

## Building apps

You can ask the Omni Agent to turn the current workbook into an app. When you do this while already working in a workbook, the app attaches to that workbook and uses the query tabs that already exist.

If your workbook hasn't been saved yet, it's saved to **My documents** first. The agent uses every query tab in the workbook unless you ask it to use a specific subset, and tells you which tabs it skipped.

See [Apps](/visualize-present/apps) to learn more.

## Getting help

If you're stuck and can't remember how to do something in Omni, ask the Omni Agent. Questions like *"How do I do \[thing]?"* will prompt the agent to search the official Omni docs and provide you with an answer, all without leaving your Omni workflow.

You can also directly tell the agent to search the docs when researching the answer to your question.

<Note>
  **Working in an embedded context?** If you have the **Hide Omni watermark** setting enabled to provide a fully white-labeled experience, the AI doc search feature will respect it. Omni doc links will not be returned in chat, even if explicitly requested.
</Note>

## Improving AI results

Queries and filter prompts submitted to Workbook Agent may require some tweaking to get the best result. Refer to the [Optimizing your models for AI guide](/modeling/develop/ai-optimization) to learn how to curate your models and include context to achieve this.


# AI Routines
Source: https://docs.omni.co/ai/routines

Schedule recurring AI-powered tasks to run automatically on your data.

Routines let you schedule AI-powered tasks to run automatically on a recurring basis. Set up a routine once, and Omni runs your prompt through the [Omni Agent](/ai/chat) on the schedule you define and then delivers the result to the people you choose.

Unlike a standard schedule that delivers the same static dashboard or file every time, a routine runs a prompt on each execution. The result is a written, plain-language response — a summary, an answer, or an interpretation of what changed — rather than just a refreshed asset.

## Use cases

Routines work best for recurring questions where an AI-written response adds more than a static export would. For example:

* **Morning briefings for sales teams** — "Summarize yesterday's closed-won deals by rep and flag any account that slipped to next quarter," delivered before the team logs on
* **Operational summaries** — "Describe how today's order volume and fulfillment times compare to the same day last week, and call out anything unusual"
* **Pipeline and revenue narratives** — "Write a short update on how we're tracking against this month's revenue target and which segments are driving the change"
* **Plain-language monitoring** — "Check for any spikes in error rates or refunds over the last 24 hours and explain what you find"

## How routines work

A routine runs your prompt through the Omni Agent on the schedule you set. Each run executes independently and respects your organization's permissions and data access controls. The result is delivered as text to the destination you choose — by email, or to a [Slack](/share/deliveries/slack) channel or users.

Each routine runs with the same permissions as the user who created it, so a routine can only query data its creator has access to.

<Note>
  Routine results do not include hyperlinked dashboard links, even when delivered to Slack.
</Note>

## Creating routines

<Note>
  **Restricted Querier** permissions or higher are required to create routines.
</Note>

Routines can be created by asking the agent, in the Omni UI, through the API, or from the [Omni CLI](/developers/cli).

<Tabs>
  <Tab title="Omni Agent" icon="comment">
    Ask for anything recurring and the agent will set up the routine for you:

    > *"Every Monday at 9am, email me a summary of last week's signups"*

    The routine will be created and immediately active, use the model and topic the conversation is scoped to, and run with your permissions. Results are delivered to you unless you say otherwise — name other people, a user group, or a Slack channel in your prompt to deliver elsewhere. Slack delivery requires a [connected Slack workspace](/share/deliveries/slack).

    In the Omni Agent, the new routine appears as a card in the conversation. Click **Edit routine** to open it in split view beside the chat, where you can review and adjust the prompt, schedule, destination, and recipients.

    You can do this anywhere you can talk to the Omni Agent:

    * **[Omni Agent](/ai/chat)** — in chat, in the Omni app
    * **[Omni Slack Agent](/integrations/omni-slack-agent#routines)** — DM the agent or `@Omni` it in a channel
    * **[MCP](/ai/mcp/tools#ask-omni)** — through the `askOmni` tool, from an MCP client like Claude or Cursor
    * **[API](/api/ai/create-ai-job)** — submit the prompt as an AI job with `POST /api/v1/ai/jobs`
    * **[Omni CLI](/developers/cli/commands/ai)** — submit the same job with `omni ai job-submit`
  </Tab>

  <Tab title="Omni UI" icon="window-maximize">
    <Steps>
      <Step title="Define the routine's settings">
        1. Click **Routines** in the [sidebar](/administration/settings/sidebar).

           <Note>
             The  sidebar item may display differently or not at all if your organization uses a [custom sidebar](/administration/settings/sidebar).&#x20;
           </Note>
        2. Click **New routine**.
        3. Fill in the fields:
           * **Routine name** — A descriptive name for the routine
           * **Description** — Optional details about what the routine does
           * **Prompt** — The instruction the Omni Agent runs on each execution
           * **Model** — The data model the routine queries, with an optional **Topic** to focus query generation
           * **Destination** — Where each run is delivered. Choose **Email** and pick the users or user groups to notify, or **Slack** and pick a channel or users. Slack requires a [connected Slack workspace](/share/deliveries/slack); to deliver to a private channel, invite the Omni Slackbot to it first.
      </Step>

      <Step title="Define the schedule">
        In this step, you'll define the cadence for the routine. The routine's schedule can be defined using the visual options or with cron:

        <AccordionGroup>
          <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
            Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

            By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
          </Accordion>

          <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
            A cron expression is a string that describes the individual details of a schedule:

            | Order | Unit         | Allowed values  | Allowed special characters |
            | ----- | ------------ | --------------- | -------------------------- |
            | 1     | minute       | 0-59            | \* , - /                   |
            | 2     | hour         | 0-23            | \* , - /                   |
            | 3     | day of month | 1-31            | \* , - / L W ?             |
            | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
            | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
            | 6     | year         | any             | \* , - /                   |

            Using cron, you can create schedules like the following:

            ```markdown title="At 9:00 AM every day" theme={null}
            0 9 ? * * *
            ```

            ```markdown title="At 6:30AM on the last day of the month" theme={null}
            30 6 L * ? *
            ```

            ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
            45 8 ? * MON-FRI *
            ```

            Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

            <Tip>
              Click the <Icon icon="sparkles" /> icon above the **Cron string** field to generate a cron schedule from a prompt like *"every weekday at 9AM"* or *"first Monday of each month at noon"*.
            </Tip>
          </Accordion>
        </AccordionGroup>
      </Step>

      <Step title="Save the routine">
        When finished, click **Save routine**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Create an AI Routine API](/api/ai-routines/create-an-ai-routine) to create a new routine. The routine will run with the same permissions as the authenticating user.

    For example:

    ```http wrap expandable theme={null}
    curl --request POST \
      --url https://{your-omni-instance}.omniapp.co/api/v1/ai/routines \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "destination": {
        "type": "email",
        "recipientEmails": [
          "blob.ross@blobsrus.com",
          "blob.the.builder@blobsrus.com"
        ],
        "userGroupIds": [
          "550e8400-e29b-41d4-a716-446655440000"
        ]
      },
      "modelId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "Blob Sales morning sales brief",
      "prompt": "Summarize yesterday’s closed-won deals by rep and flag any account that slipped to next quarter,",
      "schedule": "0 9 ? * * *",
      "timezone": "America/New_York",
      "branchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "description": "Overview of yesterday's deals, including flags for slipped accounts.",
      "topicName": "sales"
    }
    '
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [`omni ai-routines routine-create` command](/developers/cli/commands/ai-routines) to create a routine using the [Omni CLI](/developers/cli).

    The request body is passed with `--body` (or piped in on stdin):

    ```bash wrap expandable Deliver to a Slack channel theme={null}
    omni ai-routines routine-create --body '
    {
      "destination": {
        "type": "slack",
        "recipientId": "C01234567",
        "slackRecipientType": "channel"
      },
      "modelId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "Blob Sales morning sales brief",
      "prompt": "Summarize yesterday's closed-won deals by rep and flag any account that slipped to next quarter.",
      "schedule": "0 9 ? * * *",
      "timezone": "America/New_York"
    }
    '
    ```

    To print the `body` shape first, run:

    ```bash theme={null}
    omni ai-routines routine-create --schema
    ```

    See the [CLI commands reference](/developers/cli/commands) for more information.
  </Tab>
</Tabs>

## Finding routines from chat

Ask the agent to find or list your routines, for example:

> *"What do I have scheduled?"*
> *"Open the Monday routine that posts to #growth"*

The agent returns up to 10 matching routines. Click the routine to open it in split view beside the chat. On surfaces that can't show split view, such as the [Omni Slack Agent](/integrations/omni-slack-agent) or an [MCP](/ai/mcp/tools#ask-omni) client, each result includes an edit link instead.

## Deleting routines

<Warning>
  Deleting a routine can't be undone and will immediately stop the routine if it is currently running.
</Warning>

<Tabs>
  <Tab title="Omni Agent" icon="comment">
    The agent can delete a routine that is currently open in split view. To have the agent delete a routine:

    1. Open the routine in split view by clicking **Edit routine** on the routine card in the conversation.
    2. Ask the agent to delete the routine.
    3. The agent will prompt you to confirm the deletion.
    4. Click **Delete routine**.
  </Tab>

  <Tab title="Omni UI" icon="window-maximize">
    1. Click **Routines** in the [sidebar](/administration/settings/sidebar).
    2. On the **Routines** page, locate the routine you want to delete.
    3. Click the <Icon icon="ellipsis-vertical" /> icon next to the routine.
    4. Select **Delete routine**.
    5. When prompted, confirm the deletion.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Delete an AI Routine API](https://docs.omni.co/api/ai-routines/delete-an-ai-routine) to delete a routine. First retrieve the routine's ID using the [List AI Routines API](http://localhost:3002/api/ai-routines/list-ai-routines) and then pass the ID as the `{routineId}` path parameter:

    ```http theme={null}
    curl --request DELETE \
      --url https://{your-omni-instance}.omniapp.co/api/v1/ai/routines/{routineId} \
      --header 'Authorization: Bearer {token}'
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [`omni ai-routines routine-delete` command](/developers/cli/commands/ai-routines) to delete a routine using the [Omni CLI](/developers/cli).

    1. First, get the ID of the routine:

       ```bash theme={null}
       omni ai-routines routines-list
       ```

       Which will return a list of AI routines:

       ```bash theme={null}
       ┌──────────────────────────────────────┬─────────────┬───────────┬───────────┬─────────────┬──────────┐
       │ Id                                   │ Name        │ Branch Id │ Condition │ Description │ Disabled │
       ├──────────────────────────────────────┼─────────────┼───────────┼───────────┼─────────────┼──────────┤
       │ eb8e4f86-008f-416b-b63a-0049a006df15 │ Daily Sales │ -         │ -         │ -           │ false    │
       └──────────────────────────────────────┴─────────────┴───────────┴───────────┴─────────────┴──────────┘
       ```
    2. Delete the routine, passing its ID as follows:

       ```bash theme={null}
       omni ai-routines routine-delete eb8e4f86-008f-416b-b63a-0049a006df15
       ```

       The CLI will display confirmation after successfully deleting the routine:

       ```bash theme={null}
       Id:       eb8e4f86-008f-416b-b63a-0049a006df15
       Deleted:  true
       ```

    See the [CLI commands reference](/developers/cli/commands) for more information.
  </Tab>
</Tabs>

## Managing routines

From the **Routines** page, you can:

* View your routines and whether each is active or paused
* See when each routine last ran and when it will run next
* Edit a routine's settings, prompt, schedule, or recipients
* Trigger an immediate run of the routine
* Pause or resume a routine
* Delete routines you no longer need

Routines can also be managed with the [API](/api/ai-routines) or the [Omni CLI](/developers/cli).

## Best practices

* **Be specific in your prompts** — Clear, detailed instructions produce more consistent results across automated runs
* **Test before scheduling** — Run your prompt in the [Omni Agent](/ai/chat) first to verify it produces the result you expect before creating a routine
* **Choose appropriate schedules** — Match the routine's frequency to how often the underlying data changes and when the result is useful
* **Review results regularly** — Check routine output periodically to make sure it still meets your needs as your data and questions evolve

## Limitations

* The agent can create routines, find and open existing routines, and delete the routine that is currently open in split view, but can't update routines from chat. Manage existing routines from the [Routines page](#managing-routines), [API](/api/ai-routines), or [Omni CLI](/developers/cli).
* Routines cannot edit dashboards. They can only inspect and report on a dashboard referenced in a prompt.
* Using routines in embedded context is not currently supported
* Each routine delivers to a single destination. To send a run to both email and Slack, create one routine per destination.


# AI data security
Source: https://docs.omni.co/ai/security

Learn how Omni handles your data when you use AI tools.

Several features in Omni are powered by AI, allowing you to use natural language to ask questions about your data, get help creating queries, build calculations, and more.

## LLM providers

By default, Omni uses Anthropic's Claude model hosted on Amazon Web Services (AWS) Bedrock to power its AI features.

Organizations can also configure custom AI model providers, including Anthropic Direct, Google Vertex AI, OpenAI, and Grok (xAI). Refer to the [alternative model providers](/ai/settings/model-providers) documentation for more information about configuring custom providers.

Any data, including metadata, provided to the LLMs used by Omni will not be used for training. When using custom providers, API keys are securely stored per organization and are not exposed in the UI after saving.

## User prompt categorization

When a user enters a prompt, Omni will first use the LLM to categorize the request to determine how to respond.

### Shared data

To determine the correct category for the prompt, Omni shares the prompt itself with the LLM. Specifically, this is the natural language question or prompt provided by the user. For example, *"How many users signed up last month?"* or *"Filter by the last two years."*

## Query generation

When generating a query, the output of the AI's processing is a new Omni query, which is a collection of metadata - including field names, filters, sorts, pivots, topic name, and limit - that is translated into SQL. This new query is then run within the current workbook to provide an answer to the user's prompt.

Because the AI uses an abstract query format and not SQL to create queries, the generated query respects the permissions set in Omni. This means it's not possible to access data outside of the topics, models, and connections a user has been restricted to in Omni.

Additionally, this approach ensures that no private, relational, or result set data is shared to generate queries. Only metadata about the current query, user prompt, and selected topic fields is sent to the LLM, thus maintaining the privacy and security of your data.

### Shared data

While relational data is not shared to generate queries, Omni does share certain metadata with the LLM to generate accurate responses. This metadata includes:

<table>
  <thead>
    <tr>
      <th>Description</th>
      <th>What's shared?</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Current query metadata</strong></td>
      <td>Information about the currently selected query in the workbook, such as field names, sorts, limits, pivots, and filters</td>
    </tr>

    <tr>
      <td><strong>User prompt</strong></td>
      <td>The natural language question or prompt provided by the user. For example, *"How many users signed up last month?"* or *"Filter by the last two years."*</td>
    </tr>

    <tr>
      <td><strong>Context (`ai_context`)</strong></td>
      <td>Free text that provides context. This is set at the [topic](/modeling/topics/parameters/ai-context) or [view](/modeling/views/parameters/ai-context) level using the `ai_context` parameter.</td>
    </tr>

    <tr>
      <td><strong>Fields within the selected topic</strong></td>
      <td>Metadata about the fields in the currently selected topic, such as field names, labels, descriptions, data types, and whether they're aggregates (`count`, `sum`, `average`) or dimensions. **Note**: Even if a user has access to multiple topics in a workbook, only metadata for the topic that's currently selected is accessed.</td>
    </tr>
  </tbody>
</table>

Omni will share the [metadata for the current query](#query-generation) to generate accurate formulas.

## Data summarization

Omni's AI uses the LLM to power its data summarization features, which includes using the AI summary visualization or the Omni Agent to summarize the results of a query.

### Shared data

<Note>
  Models are region-specific to ensure data privacy. For example, if you're based in the EU, the models you use will be deployed in an EU-based region to ensure your data never leaves your region.
</Note>

To generate accurate summaries, the following is shared with the LLM:

* The [metadata for the current query](#query-generation)
* A CSV of the current query's results

All data will remain within AWS. Summary responses from the Omni Agent within a given session will be retained for 30 days, but the query results themselves will obey their respective Omni cache policies.

## Features and shared data

The following table details each of Omni's AI features and the data it shares. Refer to the [AI settings reference](/ai/settings/features) for information about enabling and disabling these features.

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>User prompt</th>
      <th>Current query metadata</th>
      <th>Current query results</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Chat** ([Workbook Agent](/ai/queries), [Omni Agent](/ai/chat), [Chat with Content](/ai/dashboard-assistant))</td>
      <td>Yes <CheckIcon /></td>
      <td>Yes <CheckIcon /></td>
      <td>No <XCircleIcon /></td>
    </tr>

    <tr>
      <td>[**Data summarization**](/ai/queries#summarizing-query-results)</td>
      <td>Yes <CheckIcon /></td>
      <td>Yes <CheckIcon /></td>
      <td>Yes <CheckIcon /></td>
    </tr>

    <tr>
      <td>**AI summary visualization**</td>
      <td>Yes <CheckIcon /></td>
      <td>Yes <CheckIcon /></td>
      <td>Yes <CheckIcon /></td>
    </tr>

    <tr>
      <td>[**Blank workbook topic picking**](/ai/queries)</td>
      <td>Yes <CheckIcon /></td>
      <td>Yes <CheckIcon /></td>
      <td>No <XCircleIcon /></td>
    </tr>
  </tbody>
</table>


# AI branding
Source: https://docs.omni.co/ai/settings/branding

Customize the appearance of the AI chat interface in your Omni organization.

<Note>
  **Organization Admin** permissions are required to access and modify AI settings.
</Note>

The **AI Hub > General > Branding** tab is used to customize the appearance of the AI chat interface, including the [Workbook Agent](/ai/queries), [Omni Agent](/ai/chat), and [Chat with Content](/ai/dashboard-assistant).

These settings impact the AI chat experience, including those that are [externally embedded](/embed/customization/ai-chat). To see how your changes will impact the Omni Agent, click **Save**.

## Agent name

The name of the Omni Agent, used in chat conversations.

## URL to agent image

A publicly accessible image, used as the Omni Agent's icon. A square PNG (128x128 pixels) will produce the best results.

## Intro headline

An optional greeting, displayed at the beginning of a chat session.

## Intro body

Optional additional text, displayed at the beginning of a chat session.

## Prompt placeholder

Placeholder text to display in the end user's chat box.


# AI Feature settings
Source: https://docs.omni.co/ai/settings/features

Enable and disable individual AI features in your Omni organization.

<Note>
  **Organization Admin** permissions are required to access and modify AI settings.
</Note>

## Enable AI

Enables AI features in the instance. **Must be enabled to individually enable or disable the other AI features in this tab.**

## Omni Agent

Enables the [AI agent in workbooks](/ai/queries) and the [standalone chat](/ai/chat) page. **Must be enabled to individually enable or disable the other AI features listed under this setting.**

### Chat

When enabled, the [Omni Agent](/ai/chat) page is accessible outside of workbooks. This also enables [embedding the Omni Agent into external applications](/embed/customization/ai-chat).

### Chat in navigation

Controls whether the Omni Agent appears in the main [sidebar](/administration/settings/sidebar). When disabled, the Omni Agent entry point is hidden from default and embed navigation, while other chat surfaces (ex: workbook, dashboard) remain accessible. Enabled by default.

This setting is useful for embed customers who want chat functionality in workbooks and dashboards without exposing the standalone Omni Agent page in the sidebar.

### Skills

Controls whether users can access [skills](/ai/skills). When enabled, users can access the [**Skills** page](/ai/skills#ui-create-skill) in the main [sidebar](/administration/settings/sidebar) and create and run skills in the [Omni Agent](/ai/skills#agent-create-skill). Enabled by default.

<Tooltip href="/ai/skills#ide-create-skill">Model-defined skills</Tooltip> are not affected by this setting. These skills will still be runnable even when this setting is disabled.

### Blank workbook topic picking

Enables the **Ask AI** option in blank workbook tabs.

### Read result data <Tooltip href="/ai/security"><Icon icon="database" /></Tooltip>

Allows the AI to read query results. [Used to respond](/ai/queries#summarizing-query-results) to summarization prompts, detect anomalies, and highlight insights in the chat interface. **Must be enabled to use [Chat with Content](/ai/dashboard-assistant).**

### File uploads <Tooltip href="/ai/security"><Icon icon="database" /></Tooltip>

Allows users to upload files and images in chat conversations for analysis and context.

### AI Memory <Tooltip href="/ai/security"><Icon icon="database" /></Tooltip>

<Note>
  This feature is not currently supported for embedded instances.
</Note>

Controls whether users can store personal context on their profile that the Omni Agent reads across conversations. When enabled, users can save information from chat to their [personal memory](/ai/chat#memory) or add context manually from their account settings page.

When disabled, the Omni Agent cannot use personal memories in chat sessions, save new memories, or update existing memories. The **AI memory** section on users' account settings pages will not be visible to users. Existing user memories are retained and will become accessible to users and the Omni Agent when the setting is re-enabled.

## AI visualization summary <Tooltip href="/ai/security"><Icon icon="database" /></Tooltip>

Enables the [**AI summary** visualization type](/visualize-present/visualizations/types/ai-summary) and [AI-generated subtitles and descriptions on charts](/visualize-present/dashboards/charts#adding-chart-subtitles-and-descriptions).

## Default connection

<Note>
  This setting only appears when your organization has more than one [connection](/connect-data).
</Note>

Defines the database connection the [Omni Agent](/ai/chat) initially uses when a user opens a session. If not set, Omni will use the first connection in an alphabetically-sorted list of connections.

When a user opens the Omni Agent, the connection is selected in the following order of precedence:

<Steps>
  <Step title="URL parameter or chat history">
    A connection specified in the URL (`?modelId=`) or previously used in the chat session
  </Step>

  <Step title="Organization default">
    The connection configured in this setting
  </Step>

  <Step title="Alphabetical">
    The first connection alphabetically (default behavior)
  </Step>
</Steps>

If the configured default connection is deleted, hidden by access controls, or otherwise not visible to a user, Omni selects the first connection alphabetically.

## Related

* [MCP Settings](/ai/settings/mcp) - Enable and disable individual tools for the MCP Server


# AI MCP Server settings
Source: https://docs.omni.co/ai/settings/mcp

Enable and disable individual MCP Server tools in your Omni organization.

## Requirements

To access and modify MCP Server settings, you'll need:

* **Organization Admin** permissions
* **To enable these settings**:

  * **Enable AI** in **Settings > General**
  * **Omni Agent** in **AI Hub > General > Features**

  These are required to use the MCP Server's querying tools, which are also used by the in-app Omni Agent. If **Omni Agent** is disabled, MCP tools other than [pickModel] will still appear in your MCP client but will return `403 Feature is not enabled` errors when called.

## MCP server

Controls whether users can authorize external AI tools (like Claude Desktop, ChatGPT, or Cursor) to connect to Omni via the [MCP Server](/ai/mcp). **Enabled by default**.

When disabled:

* New OAuth authorization requests return a `403` error
* Existing MCP grants are blocked from making tool calls

To configure [Personal Access Tokens](/api/authentication#token-types), navigate to **Settings > API access**.

## Agentic capabilities

Controls access to Omni's full agentic AI assistant through the MCP Server. **Enabled by default.**

When enabled, the following tools are available:

* [askOmni] - Submit open-ended, multi-step analysis jobs
* [checkStatus] - Poll the status of agentic jobs
* [listBranches] - Discover existing branch IDs for a model
* [pickModel] - Select which Omni model to query
* [pickTopic] - Select which topic to query

<Note>
  The [pickModel] and [pickTopic] tools are shared selectors that register once when either **Agentic capabilities** or **Single shot query generation** is enabled. These options are only available when the top-level **MCP server** setting is enabled.
</Note>

## Omni documentation search

Controls access to Omni's documentation search through the MCP Server. **Enabled by default.**

When enabled, the [searchOmniDocs] tool can be used to search and retrieve information from Omni's official documentation.

## Single shot query generation

Controls access to direct query generation through the MCP Server. **Disabled by default.**

When enabled, the following tools are available:

* [getData] - Execute queries against selected models and topics
* [runQuery] - Execute a full JSON query definition directly
* [pickModel] - Select which Omni model to query
* [pickTopic] - Select which topic to query

## Content access

Controls access to content search and saved query execution through the MCP Server. **Enabled by default.**

When enabled, the following tools are available:

* [searchDashboards] - Find existing dashboards by name, folder, or tile name
* [listDashboardQueries] - List saved queries on a dashboard
* [runSavedQuery] - Execute a specific saved dashboard query by ID and get its current results
* [startDashboardDownload] - Start an asynchronous dashboard PNG download job
* [checkDashboardDownload] - Poll the status of a dashboard download job
* [fetchDashboardDownload] - Retrieve the completed dashboard PNG file

## Related

* [AI feature settings](/ai/settings/features) - Enable and disable individual AI features in your Omni organization
* [AI Hub](/administration/ai-hub) - Monitor how your organization uses Omni AI

[getData]: /ai/mcp/tools#get-data

[runQuery]: /ai/mcp/tools#run-query

[pickModel]: /ai/mcp/tools#pick-model

[pickTopic]: /ai/mcp/tools#pick-topic

[searchDashboards]: /ai/mcp/tools#search-dashboards

[listDashboardQueries]: /ai/mcp/tools#list-dashboard-queries

[runSavedQuery]: /ai/mcp/tools#run-saved-query

[searchOmniDocs]: /ai/mcp/tools#search-omni-docs

[listBranches]: /ai/mcp/tools#list-branches

[askOmni]: /ai/mcp/tools#ask-omni

[checkStatus]: /ai/mcp/tools#check-status

[startDashboardDownload]: /ai/mcp/tools#start-dashboard-download

[checkDashboardDownload]: /ai/mcp/tools#check-dashboard-download

[fetchDashboardDownload]: /ai/mcp/tools#fetch-dashboard-download


# Using Databricks Genie for Omni AI
Source: https://docs.omni.co/ai/settings/model-providers/databricks-genie

Configure Databricks Genie as an AI model provider in Omni using your own serving endpoints.

When using Databricks Genie as your [AI model provider][model-providers], you can use AI models deployed through Databricks serving endpoints to power AI features in Omni.

## Requirements

<Note>
  Databricks Genie requires you to create and configure your own serving endpoints in Databricks before configuring them in Omni. Unlike other providers, there are no pre-configured model options.
</Note>

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions in Omni
* **In Databricks**:
  * A Databricks workspace with serving endpoints configured. See the [Databricks serving endpoints documentation](https://docs.databricks.com/aws/en/machine-learning/model-serving/create-manage-serving-endpoints) for more information.
  * A Databricks Personal Access Token (PAT) with permissions to access your serving endpoints. See the [Databricks PAT documentation](https://docs.databricks.com/aws/en/dev-tools/auth/pat) for more information.
  * The name(s) of your Databricks serving endpoint(s)

## Configuration

<Steps>
  <Step>
    In Omni, navigate to **AI Hub > General > Model**.
  </Step>

  <Step>
    Select **Databricks Genie** as the **Provider**.
  </Step>

  <Step>
    Define the **Query model** and **Text/reasoning model**. You can use the same endpoint for both models or specify different endpoints for different tasks.

    <Note>
      The endpoint names you provide must exactly match the serving endpoint names configured in your Databricks workspace. For example, if you named a serving endpoint `omni-model-provider`, you would enter `omni-model-provider` in Omni.
    </Note>
  </Step>

  <Step>
    Add the connection details:

    * **Base URL** - Enter the serving endpoint URL of your Databricks workspace, for example: `https://<your-workspace>.cloud.databricks.com/serving-endpoints`
    * **API key** - Enter your Databricks [Personal Access Token](https://docs.databricks.com/aws/en/dev-tools/auth/pat)
  </Step>

  <Step>
    Click **Save**.
  </Step>
</Steps>

After the setup is successfully completed, Omni will use Databricks Genie for AI features. Try asking the [Omni Agent](/ai/chat) a few questions to test the setup.

## Related

* [AI in Omni](/ai)
* [AI settings](/administration/ai-hub)
* [Alternative model providers][model-providers]

[model-providers]: /ai/settings/model-providers


# Using Google Gemini Enterprise Agent Platform (Vertex AI) for Omni AI
Source: https://docs.omni.co/ai/settings/model-providers/google-vertex-ai

Configure Google Vertex AI as an AI model provider in Omni.

Google Gemini Enterprise Agent Platform (formerly Vertex AI) provides access to Claude models through Google Cloud Platform (GCP). By connecting Vertex AI to Omni, you can power features like the [Workbook Agent](/ai/queries) and [Chat with Content](/ai/dashboard-assistant) using your organization's GCP infrastructure.

Authentication uses workload identity federation (WIF), which federates Omni's ECS task role identity into your GCP project. No long-lived service account keys are stored in Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **In Omni**:
  * **An AWS-hosted Omni instance**
  * **Organization Admin** permissions
* **In Google Cloud Platform, permissions that allow you to**:
  * Create and configure workload identity federation providers
  * Configure trust policies for external AWS identities
  * Grant IAM permissions for Vertex AI API access
  * Enable Vertex AI API in your GCP project

- **The `gcloud` CLI**

## GCP setup

Complete the following setup within your GCP project before configuring Vertex AI in Omni.

<Steps>
  <Step title="Enable Vertex AI API">
    Ensure the Vertex AI API is enabled in your GCP project. You can enable it through the [Google Cloud Console](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com) or using the `gcloud` CLI:

    ```bash wrap theme={null}
    gcloud services enable aiplatform.googleapis.com --project=<GCP_PROJECT_ID>
    ```

    Replace `<GCP_PROJECT_ID>` with the ID of your GCP project.
  </Step>

  <Step title="Create a workload identity federation provider">
    Create a workload identity pool and provider to allow Omni's AWS ECS tasks to authenticate to your GCP project.

    <Steps>
      <Step title="Retrieve Omni's AWS identity information">
        1. In Omni, navigate to **AI Hub > General** and click the **Model tab**.
        2. In the **Provider** dropdown, select **Gemini Enterprise Agent Platform (Claude)**.
        3. The fields required to configure the model will display, including a field with **Omni's AWS identity information**. It will contain values similar to the following:

           ```text Federated Identity example theme={null}
           arn:aws:iam::123456789012:role/Prod-Prod
           ```

           ```text Attribution condition prefix example theme={null}
           arn:aws:sts::123456789012:assumed-role/Prod-Prod
           ```

           These values identify Omni to Google Cloud. Note that:

           * **It contains Omni's AWS account ID**. This is the `123456789012` segment. You'll need this when creating the provider in the next step.
           * **Both values are prefixes that match all AI-calling services**. Omni uses multiple ECS task roles for AI-calling services that all share this prefix. Your attribute condition must use a **starts-with** comparison to match all of them. An exact-match condition will never match.
      </Step>

      <Step title="Create a workload identity pool and AWS provider">
        In your Google Cloud project, create a workload identity pool and an AWS provider that trusts the identity you copied in the previous step.

        <Tabs>
          <Tab title="Console" icon="window-maximize">
            1. In the Google Cloud Console, navigate to [**IAM & Admin > Workload Identity Federation**](https://console.cloud.google.com/iam-admin/workload-identity-pools).
            2. Click **Create pool**.
            3. Enter a name, such as `omni`, and continue.
            4. Add a provider to the pool:
               * **Provider type** - AWS
               * **Provider name** - Enter a name, such as `Omni`
               * **AWS account ID** - The account ID from the value you copied in&#x20;
            5. Configure the provider attribute mappings. AWS presents Omni's identity in a different format than the value shown in Omni, so the mappings reconstruct the role ARN before comparing it.

               1. Click **Edit mapping**.
               2. For `google.subject`, paste the following into the corresponding **AWS** field:

                  ```text wrap theme={null}
                  assertion.arn.extract('assumed-role/{role}/')
                  ```
               3. For `attribute.aws_role_arn`, paste the following into the corresponding **AWS** field:

                  ```text wrap theme={null}
                  'arn:aws:iam::' + assertion.account + ':role/' + assertion.arn.extract('assumed-role/{role}/')
                  ```

               The mappings should look like the following when finished:

               <Frame>
                 <img alt="Configured provider attribute mappings in the Google Cloud Console" />
               </Frame>
            6. Configure the provider attribute conditions:
               1. Click **Add condition**.
               2. In the text field, add the attribute condition. Replace  with the  value you copied from Omni in :

                  ```text wrap theme={null}
                  attribute.aws_role_arn.startsWith('OMNI_ATTRIBUTION_CONDITION_PREFIX')
                  ```

                  For example:

                  ```text wrap theme={null}
                  attribute.aws_role_arn.startsWith('arn:aws:sts::123456789012:assumed-role/Prod-Prod')
                  ```

                  The attribute conditions should look like the following when finished:

            <Frame>
              <img alt="Configured provider attribute condition in the Google Cloud Console" />
            </Frame>

            7. Click **Save**.
          </Tab>

          <Tab title="gcloud CLI" icon="terminal">
            Using the `gcloud CLI`, run the following to create a workload identity pool:

            ```bash highlight={2} theme={null}
            gcloud iam workload-identity-pools create omni \
              --project=GCP_PROJECT_ID \
              --location=global \
              --display-name="Omni"
            ```

            Replace **GCP\_PROJECT\_ID** with the ID of your GCP project.

            Then, create the provider:

            ```bash wrap highlight={2,5,7} theme={null}
            gcloud iam workload-identity-pools providers create-aws omni-aws \
              --project=GCP_PROJECT_ID \
              --location=global \
              --workload-identity-pool=omni \
              --account-id=OMNI_AWS_ACCOUNT_ID \
              --attribute-mapping="google.subject=assertion.arn.extract('assumed-role/{role}/'),attribute.aws_role_arn='arn:aws:iam::'+assertion.account+':role/'+assertion.arn.extract('assumed-role/{role}/')" \
              --attribute-condition="attribute.aws_role_arn.startsWith('OMNI_ATTRIBUTION_CONDITION_PREFIX')"
            ```

            Replace the following values:

            | Placeholder                      | Replace with                                 |
            | -------------------------------- | -------------------------------------------- |
            | **GCP\_PROJECT\_ID**             | The ID of your GCP project                   |
            | **OMNI\_AWS\_ACCOUNT\_ID**       | The account ID from the value you copied in  |
            | The entire  value you copied in  |                                              |
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Step>

  <Step title="Grant the workload identity pool access to Vertex AI">
    Give the workload identity pool permission to call Vertex AI.

    Choose one of the following options:

    <AccordionGroup>
      <Accordion title="Option 1 - Grant direct access" icon="arrow-right" description="Grant the pool the Vertex AI User role directly on your project.">
        Grant the pool the **Vertex AI User** role (`roles/aiplatform.user`) directly on your project, replacing **GCP\_PROJECT\_ID** with the ID of your GCP project:

        ```bash wrap title="Grant the pool Vertex AI access" theme={null}
        PROJECT_NUMBER=$(gcloud projects describe GCP_PROJECT_ID --format='value(projectNumber)')

        gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
          --role="roles/aiplatform.user" \
          --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/omni/*"
        ```

        When you configure Omni, leave the **Service account impersonation URL** field blank.
      </Accordion>

      <Accordion title="Option 2 - Impersonation through a service account" icon="mask" description="Have the pool impersonate a named service account that holds the Vertex AI User role.">
        If your organization requires Vertex AI access to be held by a named service account (for example, to satisfy least-privilege or audit policies), grant the pool permission to impersonate a service account that holds `roles/aiplatform.user`, instead of granting the pool directly.

        Run the following, replacing **GCP\_PROJECT\_ID** with the ID of your GCP project:

        ```bash wrap title="Grant access through a service account" theme={null}
        # Create a service account (or use an existing one)
        gcloud iam service-accounts create omni-vertex-sa \
          --display-name="Omni Vertex AI Service Account" \
          --project=GCP_PROJECT_ID

        # Grant it the Vertex AI User role
        gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
          --member="serviceAccount:omni-vertex-sa@GCP_PROJECT_ID.iam.gserviceaccount.com" \
          --role="roles/aiplatform.user"

        # Allow the pool to impersonate the service account
        PROJECT_NUMBER=$(gcloud projects describe GCP_PROJECT_ID --format='value(projectNumber)')

        gcloud iam service-accounts add-iam-policy-binding \
          omni-vertex-sa@GCP_PROJECT_ID.iam.gserviceaccount.com \
          --role="roles/iam.workloadIdentityUser" \
          --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/omni/*" \
          --project=GCP_PROJECT_ID
        ```

        When you configure Omni, set the **Service account impersonation URL** to the following, replacing **GCP\_PROJECT\_ID** with the ID of your GCP project:

        ```txt wrap theme={null}
        https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/omni-vertex-sa@GCP_PROJECT_ID.iam.gserviceaccount.com:generateAccessToken
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Get the workload identity provider audience">
    Retrieve the audience value for your workload identity provider. This will be used in the Omni configuration:

    ```bash wrap theme={null}
    gcloud iam workload-identity-pools providers describe omni-aws \
      --project=GCP_PROJECT_ID \
      --location=global \
      --workload-identity-pool=omni \
      --format="value(name)"
    ```

    The output will be in the format:

    ```txt wrap theme={null}
    //iam.googleapis.com/projects/GCP_PROJECT_ID/locations/global/workloadIdentityPools/omni/providers/omni-aws
    ```
  </Step>

  <Step title="Enable the Claude models and confirm quota">
    Before Omni can generate responses, the Claude models you plan to use must be enabled for your GCP project and your region must have quota for them.

    1. In the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), enable each Claude model you plan to use with Omni and accept its terms. Anthropic models aren't enabled by default.
    2. Confirm your project has non-zero quota for those models in the region you'll configure in Omni. You can review and request quota changes under [IAM & Admin > Quotas](https://console.cloud.google.com/iam-admin/quotas) in the Google Cloud console.

    See Google's documentation on [using Claude models on Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude) for more information.
  </Step>
</Steps>

## Omni configuration

After you complete the setup in GCP, you can add Google Vertex AI as your AI provider in Omni.

<Steps>
  <Step>
    In Omni, navigate to **Settings > General** and ensure **Enable AI** is toggled on.
  </Step>

  <Step>
    Navigate to **AI Hub > General** and click the **Model tab**.
  </Step>

  <Step>
    In the **Provider** dropdown, select **Gemini Enterprise Agent Platform (Claude)**.
  </Step>

  <Step>
    Configure the following fields:

    | Field                                 | Description                                                                                                                                                                                                                                 |
    | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **GCP Project**                       | The ID of the GCP project where Vertex AI is enabled.                                                                                                                                                                                       |
    | **Region**                            | The GCP region where your Vertex AI models are hosted (e.g., `us-east5`).                                                                                                                                                                   |
    | **WIF Provider Audience**             | The full [workload identity provider audience path](#wip-audience).                                                                                                                                                                         |
    | **Service Account Impersonation URL** | **Optional**. If using service account impersonation, provide the URL in the format: `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<service-account-email>:generateAccessToken`. Leave blank if using direct access. |
    | **Smartest model**                    | The most capable model for complex reasoning tasks.                                                                                                                                                                                         |
    | **Standard model**                    | The model used for typical query generation.                                                                                                                                                                                                |
    | **Fastest model**                     | The model used for simpler, high-volume tasks.                                                                                                                                                                                              |
  </Step>

  <Step>
    Click **Save**.
  </Step>
</Steps>

<Note>
  Model identifiers in Vertex AI may vary by region and project. Omni supports custom model identifiers to accommodate region-specific availability. Refer to the [Google Cloud documentation](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/model-versioning) for available models in your region.
</Note>

## Troubleshooting

* **Authentication errors (403):** Verify that your workload identity pool uses the role prefix shown in Omni's AI settings and that the attribute condition uses a **starts-with** comparison.
* **Permission denied errors:** Ensure the service account has the `roles/aiplatform.user` role and that the workload identity pool has permission to impersonate the service account (`roles/iam.workloadIdentityUser`).
* **Model not found errors:** Model availability varies by GCP region. Verify that the model IDs you've configured are available in your selected region, or enable cross-region access in your GCP project.
* **Invalid audience:** Double-check that the WIF Provider Audience matches the full path from the command output in the [Get WIP audience step](#wip-audience).
* **Rate limit or quota errors:** If you receive an error like `Your application has exceeded its allocated rate limit or quota for a specific API`, verify that the models you're using have a positive quota balance.

## Related

* [AI in Omni](/ai)
* [AI settings](/administration/ai-hub)
* [Alternative model providers][model-providers]

[model-providers]: /ai/settings/model-providers


# Bring Your Own Key (BYOK)
Source: https://docs.omni.co/ai/settings/model-providers/index

Configure a custom AI model provider for your Omni organization.

<Note>
  BYOK is available on the **Enterprise plan**. Please contact your Omni Account Executive or [Omni support](mailto:support@omni.co) to learn more.
</Note>

By default, Omni uses AWS Bedrock and you can control the default Claude model used for various AI features by adjusting the [`ai_settings`](/modeling/models/parameters/ai-settings) parameter in the Omni model.

If you prefer to use a different provider or your own API key, Omni also supports the following providers: Anthropic Direct, Google Vertex AI, OpenAI, Snowflake Cortex, Databricks Genie, or Grok (xAI). Provider settings are configured in **AI Hub > General > Model**. Organization Admin permissions are required to access and modify AI model settings.

## Supported providers

<Columns>
  <Card title="AWS Bedrock" icon="aws">
    **Default provider**. Uses Omni's managed AWS credentials and model selection.
  </Card>

  <Card title="Anthropic Direct" icon="sparkles">
    Direct API access to Anthropic's Claude models. Allows you to select which model is used.
  </Card>

  <Card title="Google Vertex AI" icon="google" href="/ai/settings/model-providers/google-vertex-ai">
    Access to Claude models through Google Vertex AI using workload identity federation (WIF). Requires configuration in GCP.
  </Card>

  <Card title="OpenAI" icon="openai" href="/ai/settings/model-providers/openai">
    Access to GPT models. Supports integration with OpenAI-compatible APIs like Azure OpenAI and Ollama and [custom model identifiers][openai] for bring-your-own-model (BYOM) configurations.
  </Card>

  <Card title="Snowflake Cortex" icon="snowflake" href="/ai/settings/model-providers/snowflake-cortex">
    Access to Anthropic's Claude models through Snowflake Cortex. Requires configuration in Snowflake.
  </Card>

  <Card title="Databricks Genie" icon="trowel-bricks" href="/ai/settings/model-providers/databricks-genie">
    Access to models via Databricks serving endpoints. Requires configuration in Databricks.
  </Card>

  <Card title="Grok (xAI)" icon="x-twitter">
    Access to xAI's Grok models.
  </Card>
</Columns>

## Configuration options

<Warning>
  Omni has not thoroughly tested all model options. Performance may vary depending on the model selected.
</Warning>

Omni uses a three-tier model system to balance performance and cost across different AI features:

* **Smartest model** - The most capable model, used for the most complex reasoning tasks requiring advanced capabilities.
* **Standard model** - A balanced model for typical query generation and detailed questions.
* **Fastest model** - An optimized model for simpler, high-volume tasks like text completion and basic assistance.

### Available settings

* **Provider** - The AI model provider to use for your organization. The provider determines which models are available and how API requests are handled.
* **Smartest model** - The most capable model in your provider's lineup, used for complex reasoning tasks. Not available for AWS Bedrock or Databricks Genie, which use region-based model selection.
* **Standard model** - The model used for typical query generation and analytical tasks. Choose a balanced model for good performance across use cases.
* **Fastest model** - The model used for simpler, high-volume tasks like text completion and basic assistance. A smaller, faster model is recommended to optimize performance and cost.
* **Custom model** - **Applicable only to OpenAI**. Override the default model selection with a custom model ID. See [Custom model identifiers with OpenAI][openai] for more information.
* **API key** - Your API key for the selected provider. API keys are securely stored and not displayed after saving. Required for:
  * Anthropic Direct
  * Google Vertex AI - Uses workload identity federation (WIF) credentials instead of an API key. Requires GCP project, region, WIF provider audience, and optional service account impersonation URL
  * OpenAI - Applicable to built-in models and [custom models][openai]
  * Snowflake Cortex - Use a Snowflake Programmatic Access Token (PAT)
  * [Databricks Genie][databricks] - Use a Databricks Personal Access Token (PAT)
  * Grok
* **Base URL** - The base URL for API requests. Available for:
  * [**OpenAI**][openai] - Use this to connect to OpenAI-compatible APIs like Azure OpenAI or self-hosted Ollama instances
  * **Snowflake Cortex** - Provide your Snowflake account's base URL
  * [**Databricks Genie**][databricks] - Provide your Databricks workspace URL (e.g., `https://your-workspace.cloud.databricks.com`)

## Related

* [Databricks Genie setup][databricks]
* [Google Vertex AI setup][vertex-ai]
* [OpenAI custom model identifiers][openai]

[databricks]: /ai/settings/model-providers/databricks-genie

[openai]: /ai/settings/model-providers/openai

[vertex-ai]: /ai/settings/model-providers/google-vertex-ai


# Using a custom OpenAI model for Omni AI
Source: https://docs.omni.co/ai/settings/model-providers/openai

Use custom model identifiers with OpenAI to connect Omni to Ollama, Azure OpenAI, fine-tuned models, and more.

When using OpenAI as your [AI model provider][model-providers], you can specify custom model identifiers to use models not listed in the default model dropdowns. This is useful for:

* Using locally-hosted models through Ollama (e.g., `llama3.1:70b`)
* Using Azure OpenAI deployments with custom names
* Using newly-released models before they're added to the default list
* Using fine-tuned or specialized models

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions in Omni
* **An OpenAI API key**

## Configuration

<Note>
  Custom models default to a 400,000 token context window.
</Note>

<Steps>
  <Step>
    In Omni, navigate to **AI Hub > General > Model**.
  </Step>

  <Step>
    Select **OpenAI** as the **Provider**.
  </Step>

  <Step>
    In the **Smartest model**, **Standard model**, or **Fastest model** dropdown, select **Custom model identifier**.
  </Step>

  <Step>
    Enter your model identifier in the **Custom model** field that appears (e.g., `llama3.1:70b`, `gpt-4-turbo-2024-04-09`, or your Azure deployment name).
  </Step>

  <Step>
    If your endpoint uses a different base URL (such as for Azure OpenAI or Ollama), configure the **Base URL** field.
  </Step>

  <Step>
    Enter your OpenAI API key in the **API key** field.
  </Step>

  <Step>
    Click **Save**.
  </Step>
</Steps>

After the setup is successfully completed, Omni will use the custom model for AI features. Try asking the [Omni Agent](/ai/chat) a few questions to test the setup.

## Related

* [AI in Omni](/ai)
* [AI settings](/administration/ai-hub)
* [Alternative model providers][model-providers]

[model-providers]: /ai/settings/model-providers


# Using Snowflake Cortex for Omni AI
Source: https://docs.omni.co/ai/settings/model-providers/snowflake-cortex

Configure Snowflake Cortex as an AI model provider in Omni.

Snowflake Cortex provides access to industry-leading large language models (LLMs) hosted directly within your Snowflake infrastructure. By connecting Cortex to Omni, you can power features like the [Workbook Agent](/ai/queries) and [Chat with Content](/ai/dashboard-assistant) without your data ever leaving the Snowflake security boundary. Because the LLMs are hosted within Snowflake, your metadata and query context remain governed by Snowflake's existing security and compliance framework.

## Limitations

Currently, only Claude models are supported for this integration:

* **Query models** - Claude 4.5 Sonnet, Claude 4 Sonnet, Claude 4.5 Opus, Claude 4 Opus, Claude 3.7 Sonnet, Claude 3.5 Sonnet.
* **Text models** - Claude 4.5 Haiku, Claude 3.5 Haiku.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions in Omni
* **In Snowflake, permissions that allow you to**:
  * Grant roles to database users
  * Manage network policies
  * Enable cross-region inference (for Claude model availability)
  * Create a Programmatic Access Token (PAT). This token serves as the **API Key** in your Omni configuration. See the [Snowflake PAT documentation](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) for how to create one.

    <Warning>
      Snowflake is phasing out single-factor password authentication by **October 2026**. Ensure you are using PATs for your Cortex API configuration to avoid future service interruptions.
    </Warning>

## Snowflake setup

Complete the following setup within your Snowflake instance before configuring Cortex in Omni.

<Steps>
  <Step title="Grant Cortex access">
    The Snowflake role used for your Omni connection must have the `CORTEX_USER` database role. Run the following to grant this role if the Omni user doesn't currently have it:

    ```sql theme={null}
    GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE <your_omni_role>;
    ```
  </Step>

  <Step title="Enable cross-region support">
    To ensure model availability (particularly for Claude models), enable cross-region inference. This allows Snowflake to route requests to regions where specific models are hosted:

    ```sql theme={null}
    ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';
    ```
  </Step>

  <Step title="Configure network policies">
    If your Snowflake account uses network policies, you'll need to allow Omni's egress IP addresses to permit the API traffic. You can find these IPs on the **Connection** setup page in Omni.

    After you retrieve Omni's IP addresses, run the following:

    ```sql theme={null}
    CREATE NETWORK POLICY IF NOT EXISTS cortex_api_policy
      ALLOWED_IP_LIST = ('<omni_ips>');
    ```
  </Step>
</Steps>

## Omni configuration

After you complete the setup in Snowflake, you can add Snowflake as your AI provider in Omni.

<Steps>
  <Step>
    In Omni, navigate to **Settings > General** and ensure **Enable AI** is toggled on.
  </Step>

  <Step>
    Navigate to **AI Hub > General** and click the **Model** tab.
  </Step>

  <Step>
    In the **Provider** dropdown, select **Snowflake Cortex**.
  </Step>

  <Step>
    Configure the following fields:

    | Field           | Description                                                                                                            |
    | :-------------- | :--------------------------------------------------------------------------------------------------------------------- |
    | **Base URL**    | Your Cortex API endpoint: `https://[account_identifier].snowflakecomputing.com/api/v2/cortex/v1`                       |
    | **API Key**     | Your Snowflake [Programmatic Access Token (PAT)](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens). |
    | **Query model** | The model used for generating SQL (e.g., `claude-3-7-sonnet`).                                                         |
    | **Text model**  | The model used for text processing and summaries (e.g., `claude-3-5-haiku`).                                           |
  </Step>

  <Step>
    Click **Save**.
  </Step>
</Steps>

## Troubleshooting

* **Insufficient privileges:** Ensure the role associated with your PAT has been granted the `SNOWFLAKE.CORTEX_USER` database role.
* **Region errors:** If you receive errors regarding model availability, verify that `CORTEX_ENABLED_CROSS_REGION` is set to `'ANY_REGION'`.
* **Network blocks:** Double-check that all Omni egress IPs are included in your Snowflake Network Policy's `ALLOWED_IP_LIST`.

## Related

* [AI in Omni](/ai)
* [AI settings](/administration/ai-hub)
* [Alternative model providers][model-providers]

[model-providers]: /ai/settings/model-providers


# Managing AI credit usage
Source: https://docs.omni.co/ai/settings/usage

View and manage AI credit usage for your Omni organization.

<Note>
  This guide is not applicable if your organization is using a [custom model provider](/ai/settings/model-providers).
</Note>

Omni's AI features consume credits each time they process a request. You can control this usage at two levels: across your entire organization, or for individual users. In this guide, you'll learn what credits are, what drives consumption, how to set limits at both levels, and how to monitor usage across your account.

## Requirements

**Organization Admin** permissions are required to access Omni's AI credit controls and monitoring tools.

## What are credits?

Credits are the unit of measurement for AI usage. Every interaction with an AI feature in Omni — such as asking a question, generating a summary, asking AI to make data model changes, or using the [MCP Server](/ai/mcp) — consumes tokens from an LLM provider. Omni rolls those up into credits.

Credit usage varies depending on several factors:

* **Task complexity** — More complex questions, multi-step analysis, or larger datasets use more credits than basic lookups. Each message in a session carries prior context, so long-running sessions can compound.
* **Data model and context size** — Omni sends context from the data model to the LLM to improve answer accuracy (field descriptions, `ai_context`, synonyms, etc.). Larger data models use more credits.
* **LLM model** — More capable models (e.g., Sonnet-class) consume more credits per request than lighter models (e.g., Haiku-class). See [AI model settings](/modeling/models/parameters/ai-settings) to configure tiers.

## Organization-level credit controls

The **Credits** tab in **AI Hub > General** includes settings that allow you to limit AI credit consumption at the organization level. The settings can be used individually or combined.

<Note>
  **Credits and multiple Omni organizations.** Your Omni **account** represents your company — for example, Blobs R Us. Each account contains one or more **organizations** (also called instances), the individual Omni deployments you sign in to, such as `blobsrus-usa` and `blobsrus-eu`. AI credits are pooled at the account level, but managed per organization.
</Note>

### Set a hard cap on AI usage

Disables AI features when the specified credit threshold is reached. Using AI beyond the included amount shown requires enabling overage billing.

<Note>
  Requests that are processing when the cap is met will complete, but subsequent requests will be blocked. This means that the hard cap limit may be slightly exceeded to account for in-process requests.
</Note>

#### Enabling overage billing

Some accounts may have AI usage automatically capped at their included credit allotment. If your account is hard-capped, Organization Admins will see a **Review & accept** banner on the **Credits** tab to enable overage billing.

To enable overage billing, check the authorization box and click **Agree & enable overage billing**. This removes the usage cap for all organizations sharing the same billing account, allowing AI usage to continue beyond the included allotment.

### Downgrade to a less expensive model

Switches AI features to a less expensive model (Claude Haiku) when the specified credit threshold is reached, reducing credit consumption.

### Defining credit usage thresholds

<Tip>
  To create a tiered approach, enable both the hard cap and downgrade settings. Set **Downgrade to a less expensive model** at a lower threshold than **Set a hard cap on AI usage**. As consumption rises, AI features switch to a less expensive model first, then stop entirely once the hard cap is reached.
</Tip>

To set a hard cap or less expensive model:

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **AI Hub > General**.
    2. Click the **Credits** tab.
    3. Toggle the setting to **on**.
    4. In the credits field, enter the number of credits where usage should be hard-capped or downgraded.
    5. Click **Save**.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update AI credit limits](/api/ai-credit-controls/update-ai-credit-controls) endpoint and include the `downgradeCredits` and `shutoffCredits` parameters in the request body:

    ```http wrap highlight={7,8} theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "downgradeCredits": 800,
      "shutoffCredits": 1200
    }
    '
    ```
  </Tab>
</Tabs>

### Threshold notifications

When a hard cap or less expensive model is set, all Organization Admins will receive email notifications when usage passes 75% and 100% of the defined threshold for each setting.

For example, when only a hard cap is defined, each Organization Admin could receive up to two notifications: one when 75% of the threshold is used, and another when usage passes 100%.

## User-level credit controls

By default, users in your organization don't have credit limits. Overall usage will be capped based on any [organization-level controls you have defined](#organization-level-credit-controls), but limits for individual users are only enforced if you enable user-level credit limits.

User-level credit limits are defined in the **Credit usage** tab and can be set in two ways:

| Method                                          | What it does                                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [Per-user default limit](#per-user-default)     | Applies a default limit to all users in the organization without defined individual limits |
| [Individual user limit](#individual-user-limit) | Defines a limit for an individual user; overrides the per-user default limit when set      |

### Per-user default limit

A default limit sets a credit limit for each individual user in your organization. When defined, the default applies to all users in the organization that don't have an [individual AI credit limit configured](#individual-user-limit).

Default credit limits work alongside organization-level [downgrade](#downgrade) and [hard cap](#hard-cap) thresholds. For example, you can set a per-user default of 10,000 credits while also configuring an organization-level hard cap of 500,000 credits to control total organizational usage.

To define the per-user default credit limit:

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **AI Hub > General**.
    2. Click the **Credits** tab.
    3. Scroll to the **User settings** section.
    4. Enter the number of credits in the **Cap each user at** field to set the organization-wide per-user default, or leave it empty to allow unlimited credits by default.
    5. Click **Save**.

    You can also set the per-user default credit limit in your organization's [Attributes page](/administration/users/attributes#param-omni-ai-credit-limit-ai-credit-limit).
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update AI credit limits](/api/ai-credit-controls/update-ai-credit-controls) endpoint and include the `userDefaultCredits` parameter in the request body:

    ```http wrap highlight={9} theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "downgradeCredits": 800,
      "shutoffCredits": 1200,
      "userDefaultCredits": 100
    }
    '
    ```
  </Tab>
</Tabs>

### Individual user credit limits

Setting credit limits for individual users allows you to control how many credits specific users can consume. For example, you might set a higher limit for power users who rely heavily on AI features, or a lower limit for users who primarily work with static content.

User-level limits are set using `omni_ai_credit_limit` user attribute. When a user-level limit is not set, the user inherits the [organization's per-user default limit](#per-user-default). See [User settings](/administration/users/settings#ai-credit-limit) for more information.

To configure a credit limit for a user:

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **AI Hub > General**.
    2. Click the **Credit usage** tab.
    3. Click the **By user** toggle to display a list of users.
    4. In the row for the user, click the **Edit limit** button.
    5. In the dialog that displays, configure the user's credit limit:
       * **To set a cap**, enter a whole number (ex: `40`) in the **Credit limit** field
       * **To allow unrestricted usage**, click the **Unlimited** toggle
       * **To remove the user's current settings**, click **Unset**. The user will inherit the [organization's per-user default limit](#per-user-default) on save.
    6. Click **Save**.

    You can also set a credit limit for an individual user in their [user settings](/administration/users/settings#ai-credit-limit).
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Set individual users' AI credit limits](/api/ai-credit-controls/set-individual-users-ai-credit-limits) endpoint:

    ```bash wrap theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls/users \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "users": [
        {
          "userId": "f4a2b3c8-0d1e-4f5a-9b6c-7d8e9f0a1b2c",
          "creditLimit": 540
        }
      ]
    }
    '
    ```
  </Tab>

  <Tab title="Embed" icon="chart-column">
    Include the `omni_ai_credit_limit` attribute in the embed [`userAttributes` URL parameter](/embed/setup/url-parameters/userAttributes):

    ```json wrap theme={null}
    userAttributes={"omni_ai_credit_limit":40}
    ```
  </Tab>
</Tabs>

## Embed entity group credit controls

<Note>
  Embed entity group controls only apply when [embedding Omni](/embed).
</Note>

If you're embedding Omni, you can also set limits for entity groups in addition to organization and user-level settings. This allows you to control AI usage on a per-entity basis when embedding Omni for multiple customers or tenants.

See [Managing AI credits for embed entity groups](/embed/admin/ai-credits) for more information.

## Monitoring credit usage

There are a few ways to monitor AI credit usage in Omni:

* [**Overall organization usage**](#simple-usage) against your thresholds
* [**Usage for users and entities**](#user-entity-usage) against their limits, if defined
* [**Detailed breakdowns**](#detailed-usage) of usage over time, by feature, and by user

### Check overall organization usage

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    The **Credits** tab in **AI Hub > General** displays your total credit usage for the current month. The visualization behavior depends on whether your account has a single organization or multiple. Click the tabs below for more information.

    <Tabs>
      <Tab title="Single organization" icon="user">
        For accounts with only one organization, the usage chart always appears and displays your current usage plotted against your included credit allotment and any thresholds you've configured. This gives you a quick way to see how close you are to downgrading or reaching your hard cap.

        <Frame>
          <img alt="Usage visualization for an Omni account with a single organization" />
        </Frame>

        The chart includes:

        * **Included** — The credit allotment included with your plan
        * **Downgrade** and **Cap** — The thresholds you've set, if any
        * **Credits used this month** — The organization's current usage, with color-coded bars that transition from green when you're within limits to red as usage approaches the cap
      </Tab>

      <Tab title="Multiple organizations" icon="users">
        For accounts with multiple organizations, the chart only displays when the organization has a defined downgrade threshold or hard cap.

        When thresholds are configured, the chart displays the current organization's usage plotted against the **Downgrade** and **Cap** thresholds you've set, with the same color-coded bars as the single organization view.

        <Frame>
          <img alt="Usage visualization for accounts with multiple organizations and thresholds configured" />
        </Frame>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Get AI credit controls](/api/ai-credit-controls/get-ai-credit-controls) endpoint to get high-level information about the current period's usage and your current AI control settings:

    ```http wrap theme={null}
    curl --request GET \
      --url https://<your-omni-instance>.omniapp.co/api/v1/ai/credit-controls \
      --header 'Authorization: Bearer <token>'
    ```

    Usage-related fields are highlighted in the following example response. See the [API documentation](/api/ai-credit-controls/get-ai-credit-controls) for more information about this endpoint:

    ```json highlight={3,6,7} theme={null}
    {
      "accountCreditLimit": 2000,
      "creditsUsed": 450,
      "downgradeCredits": 800,
      "entityGroupDefaultCredits": 100,
      "periodEnd": 1,
      "periodStart": 1,
      "shutoffCredits": 1200,
      "userDefaultCredits": 100
    }
    ```
  </Tab>
</Tabs>

### Check usage for users and entities

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    Use the **AI Hub > General > Credit usage** tab to view AI credit usage for users (and entities, if using embed) against their configured limit for the current billing period.

    To allow embed users to view their own credit usage on their profile page, enable the [**Show AI credit usage on profile**](/embed/admin/security#user-credit-usage) embed setting.

    <Note>
      The **By entity** view only displays if your organization has embedding enabled. See [Managing AI credits for embed entity groups](/embed/admin/ai-credits) for information about entities and AI usage.
    </Note>
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Read individual users' AI credit usage API](/api/ai-credit-usage/read-individual-users-ai-credit-usage) to get users' credit usage for the current billing period:

    ```http theme={null}
    curl --request POST \
      --url https://<your-omni-instance>.omniapp.co/api/v1/ai/credit-usage/users \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "userIds": [
        "f4a2b3c8-0d1e-4f5a-9b6c-7d8e9f0a1b2c"
      ]
    }
    '
    ```
  </Tab>
</Tabs>

### Analyze usage in detail

The **Credit Tracking** dashboard helps you understand how credits are being used in greater detail. You can access it:

* **In the [AI Hub](/administration/ai-hub)** — Select **Credit tracking** in the sidebar. Note that unlike the other AI Hub dashboards, this dashboard is not filterable by the shared model selector, since credit usage reflects activity across all models.
* **In Analytics** — Click **Analytics** in the [sidebar](/administration/settings/sidebar) and select the **Credit Tracking** dashboard.

The dashboard displays credit consumption over time and can break down usage in various ways, such as by feature and user.

## Optimizing credit usage

* **Adjust the LLM model tier**. See [AI model settings](/modeling/models/parameters/ai-settings).
* **Trim unused fields, descriptions, or `ai_context` from the data model**. Reducing context may lower per-call credit counts, but can increase the number of turns needed to get a good answer. The goal is optimizing efficiency overall.
* **If using Claude**, use the [`ai_settings.conversation_prune_length` parameter](/modeling/models/parameters/ai-settings/conversation-prune-length) to control how aggressively conversation context is managed. When conversation context reaches the specified token threshold, older messages are automatically pruned from the conversation history to stay within limits.

<Tip>
  See [Tuning Omni AI for cost and quality](/guides/ai/tuning-cost-quality) for additional credit usage optimization tips.
</Tip>

## Common questions

<AccordionGroup>
  <Accordion title="When does AI usage reset?">
    AI usage is calculated on a monthly basis and resets on the first of the month at 12AM UTC.
  </Accordion>

  <Accordion title="Why does a single prompt generate multiple rows in the tracking data?">
    Omni's AI is an agentic system. For a given prompt or request, it may fire off multiple tool calls to get the answer or complete the task.

    For example, asking *"show me revenue by region"* might involve the AI searching the data model for the right fields, building the query, creating a visualization, and summarizing results — each as a separate step. Each of these steps is logged individually in the tracking data, which is why a single user prompt can appear as several rows.
  </Accordion>

  <Accordion title="What are the blank prompts with credit usage?">
    These are "tool calls" — intermediate steps where the AI determines which action to take next. They don't have a user-facing prompt because they are part of the AI's internal reasoning as it works through a request. See the question above for more context on why these occur.
  </Accordion>

  <Accordion title="Why does the same question sometimes use different amounts of credits?">
    Credit usage can vary between identical prompts due to differences in conversation context (earlier messages in the session) or the AI choosing a different path to arrive at the answer.
  </Accordion>

  <Accordion title="Do AI summary tiles/sub-titles/descriptions on dashboards use credits on every refresh of the dashboard?">
    Omni caches AI summaries/sub-titles/descriptions so they will only recompute and use credits any time the data changes underneath (e.g., when a filter changes or it's refreshed without cache).
  </Accordion>

  <Accordion title="Why am I seeing a banner about enabling overage billing?">
    This banner appears when your account has reached its included credit allotment and AI usage has been automatically capped. To continue using AI features beyond the included amount, an Organization Admin needs to review and accept the overage billing amendment. Once accepted, AI usage can continue and your organization will be billed at \$1.00 per credit for usage beyond the included allotment.
  </Accordion>
</AccordionGroup>

## Next steps

* [AI features](/ai/settings/features) — Configure which AI features are enabled in your organization
* [Custom AI model providers](/ai/settings/model-providers) — Use a different model than the Omni default
* [Tune Omni AI for cost and quality](/guides/ai/tuning-cost-quality) — Use model settings to tune AI behavior based on your query and cost needs
* [Usage analytics](/administration/analytics) — Explore other pre-built analytics dashboards


# Skills
Source: https://docs.omni.co/ai/skills

Build reusable, AI-powered processes that your team can trigger with a single click or mention.

A skill is a set of instructions you save once and reuse with the [Omni Agent](/ai/chat). You write the instructions one time, and everyone on your team gets the same result instead of writing their own prompt.

Skills are more than saved prompts. The person who writes a skill decides which data to use, which numbers matter, and how to present the result. A skill can also do work that a single question cannot: ask you for input, run a series of queries, and bring the results together. Anyone who runs the skill gets the benefit of those decisions without having to make them.

## How skills work

When you run a skill, the Omni Agent reads the instructions and works through them in chat. Skills work well for:

* **Standardized reports** — Generate a weekly sales summary with specific metrics, groupings, and comparisons, formatted the same way every time.
* **Guided lookup** — Ask the user for an account name, then pull relevant records and summarize the findings.
* **Data quality checks** — Run a series of queries to find anomalies, missing values, or threshold breaches, then summarize the results.
* **Onboarding helpers** — Walk a new user through a dataset by querying key metrics and explaining what each one means.

### Skills versus sample queries

Both skills and [sample queries](/modeling/models/sample-queries) can help you get started with the Omni Agent, but they do different things:

|                      | Skills                                                                   | Sample queries                                                            |
| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| **Purpose**          | Give the agent instructions to follow                                    | Show example questions and train the agent on how to answer key questions |
| **How they work**    | Send a prompt, single- or multi-step, to the agent                       | Run a predefined query with specific field selections                     |
| **Best for**         | Repeatable processes, guided analysis, structured output                 | Showing what data is available and which questions are common             |
| **Who creates them** | Anyone with chat access, by asking the agent or from the **Skills** page | Modelers, in the model file (to be deprecated)                            |

Use both together. Sample queries are helpful for finding what data exists; skills package a repeated task into something you can run by name.

### Skill properties

Skills have the following properties:

| Property         | Required              | Description                                                                                                                                                                     | Maximum<br />characters |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **Name**         | <CheckIcon /> **yes** | The display name for the skill                                                                                                                                                  | 48 characters           |
| **Identifier**   | <CheckIcon /> **yes** | The handle you type to run the skill in chat, shown with a leading slash (`/quarterly-report`). Use lowercase letters, numbers, and dashes. Must start with a letter or number. | 48 characters           |
| **Description**  | <CheckIcon /> **yes** | A short summary of what the skill does                                                                                                                                          | 1,024 characters        |
| **Instructions** | <CheckIcon /> **yes** | What the agent does when the skill runs, written in Markdown                                                                                                                    | 20,000 characters       |

## Requirements

To create and run skills, your organization must have the following settings enabled in **AI Hub > General > Features**:

* [Enable AI](/ai/settings/features#enable-ai) - Required to use AI features
* [Omni Agent](/ai/settings/features#workbook-agent) - Required to use the Omni Agent
* [Omni Agent > Skills](/ai/settings/features#skills) - Required to create and run skills. **Applicable to skills created using the Omni Agent or the Skills page.** <Tooltip href="#ide-create-skill">Model-defined skills</Tooltip> are not affected by this setting.

## Creating skills

<Note>
  Access to the [Omni Agent](/ai/chat) is required to create and run skills.
</Note>

You can create skills by asking the Omni Agent or manually creating a skill on the **Skills** page. You can also add them to a model using the model IDE, but note that this method will be deprecated in the near future. See [Common questions](#common-questions) for more information about the differences between agent/UI-created skills and model-defined skills.

<Tabs>
  <Tab title="Omni Agent" icon="comment">
    Ask the agent to save a way of working and it writes the skill for you:

    ```text wrap theme={null}
    turn this into a skill

    create a skill that pulls last quarter's revenue by product category and formats it as a table
    ```

    The agent picks the **Name**, **Identifier**, and **Description**, and writes the **Instructions** — distilling them from the conversation when you're turning an existing thread into a skill, or from your request when you're starting fresh.
  </Tab>

  <Tab title="Omni UI" icon="window-maximize">
    To create a skill from the **Skills** page:

    1. Click **Skills** in the [sidebar](/administration/settings/sidebar).

       <Note>
         The  sidebar item may display differently or not at all if your organization uses a [custom sidebar](/administration/settings/sidebar).&#x20;
       </Note>
    2. Click **New skill** and select an option:
       * **Write skill instructions** - Fill in the [skill's properties](#skill-properties) yourself.
       * **Upload a skill** - Paste or upload an existing skill Markdown file, which Omni uses to fill in the [skill properties](#skill-properties) for you.

         Omni expects a Markdown file (frontmatter optional) like the following. Click `skill-template.md` for a copy-and-pasteable blank template.

         <CodeGroup>
           ```markdown quarterly-report.md wrap theme={null}
           ---
           identifier: /quarterly-report
           name: Quarterly Report
           description: Summarizes revenue, orders, and average order value for the current quarter.
           ---

           Generate a summary of revenue for the current quarter compared to the previous quarter.

           Include total revenue, order count, and average order value, broken down by product category.
           ```

           ```markdown skill-template.md theme={null}
           ---
           identifier: 
           name: 
           description: 
           ---

           ```
         </CodeGroup>

         Omni reads `name`, `identifier`, and `description` from the frontmatter and uses everything after it as the instructions. If the file doesn't have any frontmatter, Omni uses the whole file as the instructions, and you fill in the **Name**, **Identifier**, and **Description** fields in the form yourself.
    3. Fill in the skill fields.
    4. Click **Create skill**.
  </Tab>

  <Tab title="IDE" icon="code">
    <Note>
      Model-defined skills will be deprecated in the near future. Create skills using the Omni Agent or **Skills** page instead.
    </Note>

    Users with **Modeler** permissions or higher on a model can define skills in the model IDE. Unlike skills created through the Omni Agent or **Skills** page, properties for model-defined skills are set using the `skills` parameter in a [model file](/modeling/models/skills) or [topic](/modeling/topics/parameters/skills). These skills display as buttons above the text input in the chat interface.
  </Tab>
</Tabs>

## Running skills

Run skills in a chat with the Omni Agent or from the **Skills** page.

<Tabs>
  <Tab title="Omni Agent" icon="comment">
    You can run a skill in chat by:

    * **Typing `/` in the chat to open the quick skill menu.** Keep typing to narrow the list by skill name and identifier.
    * **Selecting the skill from the actions menu.** Click the <Icon icon="plus" /> icon in the bottom left corner of the chat input, then select **Skills**.
    * **Directly invoking the skill.** Anywhere in a message, type the skill's identifier with a leading slash:

      ```text wrap theme={null}
      Check last week's numbers, then run /churn-cut broken out by region
      ```

      What you type stays as the prompt. The skill's instructions are attached as context, so the agent sees your request and the instructions together and applies one to the other. This means you can add conditions, filters, or follow-up questions to a skill without editing it.

    For [model-defined skills only](#ide-create-skill), a button for the skill will display above the chat input if you have the required model permissions and access grants. Click the button to run the skill.
  </Tab>

  <Tab title="Omni UI" icon="window-maximize">
    To run a skill manually:

    1. In the **Skills** page, click the skill you want to run.
    2. Click **Run**. Omni opens the Omni Agent and runs the instructions immediately.

    <Tip>
      Use this method to quickly test a skill you're building.
    </Tip>
  </Tab>
</Tabs>

## Adding files to skill conversations

<Note>
  The **Omni Agent > File uploads** [AI setting](/ai/settings/features#file-uploads) must be enabled to attach files in a chat.
</Note>

Adding a file to a skill conversation gives the Omni Agent more information to work with. For example, a skill can ask you to upload a CSV of target accounts, then compare that list against data in Omni:

```markdown title="Example skill instructions" expandable wrap theme={null}
Upload a CSV of target accounts and I'll compare them against our existing customer data.

The user will upload a CSV file containing a list of target accounts. For each account in the file:

1. Check if the account exists in our customer database.
2. If it exists, pull the current status, lifetime revenue, and most recent activity date.
3. If it doesn't exist, flag it as a new prospect.

Summarize findings as:

- Count of existing customers vs new prospects
- Table of all accounts with match status and key metrics
- Any accounts with high revenue potential to prioritize
```

See [Uploading files in AI chat](/ai/chat#uploading-files) for information about supported file types and processing.

## Sharing and accessing skills

<Note>
  Sharing is in development. You'll be able to share a skill with specific users and groups, or with everyone in your organization, the same way you share a dashboard.
</Note>

Currently, you can see and edit the skills you created on the **Skills** page. Organization Admins are able to view and edit all skills in the organization, regardless of who created them.

## Writing effective skills

<Steps>
  <Step title="Keep the name short" icon="id-card">
    Pick two to four words that describe the task.
  </Step>

  <Step title="Be specific" icon="clipboard-list">
    The more detail you give, the more consistent the result. Name the fields, time ranges, groupings, metrics, and output format you want. For example:

    ```markdown wrap theme={null}
    Find the top 20 customers by total lifetime revenue. Include customer name, total revenue, order count, and date of most recent order. Sort by revenue descending.
    ```
  </Step>

  <Step title="Start by asking for what you need" icon="question">
    If the skill needs information only the user has, such as an account name or a date range, open the instructions by telling the agent to ask for it. For example:

    ```markdown wrap expandable theme={null}
    Ask the user for the name of the account they want to look up before proceeding.

    Look up information for the account the user specified.

    1. Find all records matching the account name. Pull back key fields: account value, status, owner, and created date.
    2. Find their recent product usage trends.
    3. Find their recent support tickets.
    4. Summarize findings in an easily consumable format, including:
        - Top-level overview (value, status, owner)
        - Activity history
        - Any risks
        - Any notable patterns
    ```
  </Step>

  <Step title="Number the steps" icon="list-ol">
    For a multi-step process, numbered steps help the agent follow the sequence you intended. For example:

    ```markdown expandable wrap theme={null}
    Run a data quality audit on the orders dataset.

    Step 1: Query for orders with missing customer IDs in the last 30 days. Output a count and percentage of total orders.

    Step 2: Query for duplicate order IDs. Output any duplicates found with their timestamps.

    Step 3: Check for orders where the total is negative or zero.
    ```
  </Step>

  <Step title="Describe how to present the results" icon="eye">
    Tables, summaries, sections with headers, health scores — tell the agent the format to get consistent results. For example:

    ```markdown theme={null}
    Summarize findings in this format:

    - Overall health score (Good / Needs Attention / Critical)
    - Table of issues found with counts
    - Recommended next steps for each issue
    ```
  </Step>

  <Step title="Name the topic when it matters" icon="location-dot">
    If the skill should use a specific [topic](/modeling/topics), include it in the instructions:

    ```markdown wrap expandable highlight={4} theme={null}
    [Available Knowledge Sources]

    ## 1. GitHub Issues
    Location: GitHub Issues Topic in Omni
    Search Strategy: Title-based search + Body-based search (contains filters)
    Key Fields: 
      - Title, Body, Status (Open/Closed)
      - Assignee (indicates active development)
      - Labels (bug, enhancement, feature-request)
    Purpose: Bug identification, feature requests, product roadmap alignment
    Query Pattern: Semantic search on keywords/error messages from user issue
    ```
  </Step>

  <Step title="Test and iterate" icon="arrow-rotate-right">
    Run the skill from its page, see how the agent reads the instructions, then edit and run it again.
  </Step>
</Steps>

## Examples

<Tip>
  **Need some inspiration?** Check out the [Library](/library?type=Skill) for ideas and skills you can add right in your Omni organization!
</Tip>

### Product roadmap answers

Answer questions internal teams ask often by searching [Google Drive](/integrations/ai/google-drive) and [Slack](/integrations/ai/slack). As with topics for queries, naming specific Slack channels or Google Drive files and folders helps increase answer quality.

```markdown title="Product roadmap answers" wrap expandable theme={null}
Greet the user by their first name and offer help with a product question.

OPERATING CONTEXT
  
  You are an internal Omni Product Intelligence Bot.
  
  You operate inside Omni's internal skill and have read-only access to:
  - Slack messages (especially #product channels)
  - Google Drive (Product roadmap spreadsheet)
  - GitHub Issues topic (bugs and feature requests)
  - Demos topic (engineering demos of new features)
  
  Your purpose is to assist Omni field team members by:
  - Answering questions about roadmap status and feature timelines
  - Surfacing recent discussions and decisions about features
  - Finding relevant engineering demos that showcase upcoming/recent work
  - Reducing back-and-forth with product team for common questions

SUCCESS CRITERIA

A successful response:
- Clearly answers whether something is on the roadmap and its current status
- Shows the most recent information available (prioritizing recency)
- Always includes direct links to sources (Slack messages, Google Docs, GitHub issues, demos)
- Identifies if the question needs follow-up in #product channel
- ALWAYS completes the full synthesis step with a definitive answer

EXECUTION STEPS

1) Search Slack Messages
- Search Slack for messages relevant to the current query.
- Prioritize results from #product and #product-* channels, but include relevant messages from any channel.
- Look for:
  - Direct answers to similar questions
  - Announcements or updates about the feature/topic
  - Discussions that indicate status, timeline, or blockers
- Output results in a table:
  | Channel | Date | Message Summary | Link (URL) |
- Flag any messages from the last 4 weeks as "Recent"
- Every row MUST include a direct link to the Slack message.

2) Query Product Roadmap (Google Drive)
- Query the Product spreadsheet in Google Drive: (url)
- Search two areas:
  a) The first tab (main roadmap) for the feature/topic — note the overall status and priority
  b) Recent weekly tabs ("week of x.x.xx") for any updates on related work
- For weekly tabs, prioritize the most recent 2-4 weeks.
- Output results in a table:
  | Source (Main Roadmap / Week of X.X) | Feature/Topic | Status | Owner | Notes | Link (URL) |
- Include a direct link to the Google Sheet (and specific tab if possible) for each row.

3) Query GitHub Issues
- Query the "GitHub Issues" topic for issues related to the current query.
- Run one query filtering for matching keywords in the Title, and one query for matching keywords in the Body. When filtering, prefer 'contains' filter conditions.
- Look for both feature requests and bugs related to the topic.
- Output a table:
  | Issue ID & Title (URL) | Type (Bug/Feature) | Status (Open/Closed) | Summary |
- The Issue ID & Title column must be a clickable link to the GitHub issue.
- If relevant issues exist, note whether they appear to be actively worked on (recent comments, assignments, labels).

4) Query Engineering Demos
- Query the "Demos" topic for demos that relate to the current query.
- Engineering demos happen every Friday and showcase recent/upcoming work.
- Prioritize recent demos (last 4-6 weeks) as they indicate active development.
- Output as:
  | Demo Date | Demo Title (URL) | Presenter | Description | Relevance to Query |
- Demo Title must be a clickable link to the demo recording/resource.

5) Feature Flags 
- If it appears the feature is in development or available in beta, check if there is an associated feature flag using the Feature Flag topic

6) Synthesize + Answer (REQUIRED — MUST ALWAYS COMPLETE)

THIS STEP IS MANDATORY. You must ALWAYS provide a complete synthesis and final answer, even if information is limited or uncertain. Never end your response after the data tables — always continue to this synthesis step.

Combine findings from Steps 1–4 to provide a clear, definitive answer:

  **Bottom Line Answer:** 
  Start with a direct answer to the user's question. Use one of these formats:
  - "Yes, [feature] is on the roadmap. Here's what I found..."
  - "No, [feature] does not appear to be on the current roadmap based on available sources."
  - "Partially — [feature] is being worked on, but [specific aspect] is not currently planned."
  - "Unknown — I couldn't find clear information, but here's what's related..."
  
  Do NOT skip this section. Do NOT leave the answer ambiguous. Take a position based on available evidence.
  
  **Roadmap Status:** Is this on the roadmap? What's the current priority/timeline?
  
  **Recent Activity:** What's the most recent work or discussion on this topic?
  
  **Key Sources:** List the most relevant sources WITH LINKS. Example:
  - [Slack: #product discussion from 1/10](url)
  - [Kaizeng: Week of 1.6.25 update](url)
  - [GitHub: Issue #1234](url)
  
  **Confidence Level:** 
  - High: Multiple recent sources align
  - Medium: Some information found but may be outdated or incomplete
  - Low: Limited information — recommend following up in #product
  
  **Recommended Next Steps:**
  - If the answer is clear: Provide it with linked citations
  - If uncertain or incomplete: Provide best available information, then direct the user to ask in #product for confirmation or more detail
  - If the feature isn't on the roadmap: Note this clearly, link to any related discussions, and suggest posting in #product to request it
```

### Triage bug reports

Use Omni documentation, feature progress, [GitHub](/integrations/ai/github), [Slack](/integrations/ai/slack), and [Google Drive](/integrations/ai/google-drive) to decide whether a new bug report is needed or an existing issue can be updated.

````markdown title="Bug intake" wrap expandable theme={null}
Bug Intake - Help the user determine whether a bug should be drafted and generate a high-quality GitHub issue draft using the canonical bug template.

OPERATING CONTEXT

  You are an internal Omni Bug Drafting Intelligence Bot.

  You operate inside Omni’s internal skills and have read-only access to:
  - GitHub Issues
  - Support Ticket Issues
  - Google Drive documentation (including bug templates)
  - Slack message history
  - Internal Product Demos
  - Omni Documentation Search (SearchOmniDocs)

  You do NOT create or modify GitHub issues.

  Your purpose is to:
  - determine whether observed behavior qualifies as a bug
  - prevent duplicate or low-signal issues
  - generate a complete, well-structured bug report draft
  - recommend priority and routing for human review

SUCCESS CRITERIA

  A successful execution:
  - Clearly distinguishes known behavior vs unexpected behavior
  - Identifies existing related issues before drafting a new one
  - Produces a draft that meets Omni’s canonical bug template
  - Recommends priority and team routing with clear rationale
  - Makes next human action obvious and low-effort

WORKFLOW EXECUTION PATTERN

  Step 0 (Initial Response): Acknowledge readiness to draft a bug.
  Steps 1–10 (Execution): Run only after the user states intent to draft a bug.

  The skill should stop early if drafting is not justified.

KEY CLARIFICATIONS FOR THE AI

  - "Current query" = the user’s message requesting to draft a bug.
  - "Current session context" includes all prior conversation in this thread.
  - Do not assume behavior is a bug without qualification.
  - Do not output speculative drafts if behavior is unclear.
  - All searches must use concrete signals from the session (links, error messages, feature names).

EXECUTION STEPS

Step 0) Initial Response

  Acknowledge intent to draft a bug.

  State that the skill will first check for known issues and confirm qualification.

Step 1) Assemble Session Context

  Sources
    - Current session messages
    - Slack thread

  Extract
    - Conversation permalink
    - Artifact links (workbooks, dashboards, pages)
    - Error messages
    - Stack trace
    - Repro descriptions
    - Environment clues (prod, playground, staging)
    - Customer / org name

  Output (internal only)
    - Normalized context summary

Step 2) Search for Existing Issues

  2.1 Query GitHub Issues

    Search Context
      Use the current session context assembled in Step 1 as the canonical query input.

    Primary signals to extract and prioritize:
      - Feature names
      - Error messages (exact strings)
      - Artifact identifiers (workbook IDs, dashboard names, query names)
      - Surface area (workbook / dashboard / query / platform)

    Querying Rules
      Run two GitHub Issues queries:
        - Title contains extracted keywords
        - Body contains extracted keywords

      Prefer contains / semantic match over exact match.
      Search both Open and Closed issues.
      Do not assume an issue being Closed means it is irrelevant.

    Output (required)
      Markdown table:
        | Issue ID & Title (URL) | Status (Open/Closed) | Brief Summary (problem + current resolution status) |

    Negative Case
      If no relevant issues are found, explicitly state:
        No related GitHub issues identified.

  2.2 Query Support Ticket Issues

    Search Context
      Reuse the same extracted signals from Step 2.1.

    Querying Rules
      Run two Support Ticket Issues queries:
        - Title contains extracted keywords
        - Body contains extracted keywords

      Do not filter by Account Name.

      Cross-reference:
        - Assignee
        - Collaborators
        - Linked GitHub Issue numbers (if present)

      Ownership Signal
        Explicitly flag whether the current user is:
          - Primary owner
          - Collaborator
          - Not involved

    Output (required)
      Markdown table:
        | Support Ticket Link | Customer Name | Issue Summary | Owner/Collab Flag | Related GitHub Issue |

    Negative Case
      If no relevant support ticket issues are found, explicitly state:
        No related support ticket issues identified.

  2.3 Query linked GitHub Issues
    If matching support ticket issues are found with linked GitHub issues, query for the linked GitHub issues.

Step 3) SearchOmniDocs

  Tool
    - SearchOmniDocs

  Search Context
    Use normalized session context from Step 1.

  Prioritize queries using:
    - Exact error messages
    - Feature / surface-area names
    - Customer-visible behavior descriptions
    - Known semantic concepts (permissions, embeddings, caching, execution, freshness, joins)

  Purpose
    - Determine whether behavior is documented, expected, or caveated
    - Identify known limitations, flags, rollout states, or required configuration
    - Reduce false-positive bug filings

  Output (required)
    Table:
      | Doc/Page Title | Key Takeaway | Link/Reference |

  Negative Case
    If no relevant documentation is found, explicitly state:
      No relevant Omni docs identified.

Step 4) Known-Issue Evaluation (HARD GATE)

  Produce internal classification:

    known_issue_evaluation:
      is_known: yes | no | unclear
      related_issue_links: []
      rationale: ""

  Rules
    If is_known = yes:
      - Point to existing issue(s)
      - Break skill execution and output the following to the user:
        ```
        +1 [link-to-slack-thread]

        > [description of the customer-specific issue from this thread]

        org_name: [one-word-org-name]
        ```

    If is_known = unclear:
      - Ask one clarifying question

    If is_known = no:
      - Proceed to Step 5

Step 5) Bug Qualification (HARD GATE)

  Determine whether behavior qualifies as a bug.

  bug_qualification:
    qualifies_as_bug: yes | no | unclear
    confidence: high | medium | low
    rationale: ""

  Qualification criteria
    - Observable behavior
    - Unexpected given product semantics
    - Reproducible or plausibly deterministic

  Rules
    - no → stop and explain why
    - unclear → request missing info (logs, repro, environment)
    - yes → proceed

Step 6) Load Canonical Bug Template

  Tool: Google Drive

  Fetch:
    - “Bug Filing For LLMs”

  Treat the template as an immutable formatting contract.

Step 7) Construct Structured BugDraft (internal only)

  Produce structured data (no markdown):

  BugDraft:
    title: ""

    description:
      slack_link: ""
      artifact_links: []
      required_user_attributes: []
      observed_behavior: ""

    to_reproduce: []
    stack_trace: ""
    expected_behavior: ""

    other_considerations:
      cc_team: ""
      regression: "unknown | yes | no"
      notes: ""

    reported_by:
      org_name: ""   # one word, don't hyperlink

    routing:
      suggested_team: ""
      routing_confidence: high | medium | low

    impact:
      user_scope: single | few | many | all
      surface_area: workbook | dashboard | query | platform
      data_integrity_risk: yes | no

Step 7.5) Normalize for GitHub URL (internal only)

  Produce (no markdown):

  GitHubPrefill:
    repo_new_issue_base: "[url]"
    title_raw: "[BugDraft.title]"
    constraints:
      max_url_length_chars: 7500

Step 8) Validate Draft Completeness

  Minimum requirements to produce a draft
    - Title present
    - Title length sanity (e.g., < 200 chars)
    - Trigger step present (in To Reproduce)
    - Observed result present (in description.observed_behavior)
    - Expected behavior present
    - Example workbook/dashboard/page link AND/OR concrete repro steps
    - Reporter org_name is one word

  GitHub URL readiness checks
    - Body contains required sections per canonical template (as rendered in Step 10)
    - Soft URL size gate: estimate encoded URL length; if it exceeds threshold, fall back to “body omitted link” strategy (see Step 10.3)

  If missing:
    - Ask only for missing fields
    - Do not proceed until resolved

Step 9) Recommend Priority (P-value)

  Based on impact assessment:

    priority_recommendation:
      suggested: P0 | P1 | P2 | P3
      rationale: ""

  This is advisory only.

Step 10) Render Draft GitHub Issue

  10.1 Render final GitHub issue body (canonical template verbatim)

    Output (required to user):
      - Fully rendered GitHub issue body using the canonical template verbatim
      - Separate Draft Metadata Summary containing:
        - Suggested priority
        - Suggested team (@team-name)
        - Routing confidence
        - Links to related issues (if any)

    Do NOT:
      - Create GitHub issues
      - Mention team mapping JSON
      - Include internal classifications in the draft body

  10.2 Generate new_issue_url (internal then shown to user)

    Base:
      https://github.com/github-org-name/issues/new

    Query params:
      - title=[urlencode(title)]
      - body=[urlencode(body_markdown)]

    Encoding rules:
      - Use RFC 3986-ish percent encoding for query values.
      - Newlines in body become %0A.

  10.3 If encoded URL exceeds threshold (constraints.max_url_length_chars):

    Produce two links:
      - “Prefilled title” URL (omit body param)
      - Provide body in copy/paste block as usual

    Rationale shown to user:
      - “Body omitted from link due to length; paste body below.”

  Final Output to User (required)
    - New Issue Link (prefilled) OR fallback links (title only)
    - Draft GitHub Issue (copy/paste ready)
    - Recommendations:
      - Priority
      - Team to CC
      - Related existing issues (if any)
    - Suggested Next Action:
      - “Click the link to open a prefilled GitHub issue, then submit”
      - If fallback: “Click the link, then paste the body below”
````

### Support agent

Accelerate support issue resolution by systematically querying existing knowledge sources like [Google Drive](/integrations/ai/google-drive) and [Slack](/integrations/ai/slack) and identifying overlaps, duplicates, and relevant precedents.

```markdown title="Support agent" wrap expandable theme={null}
Support Agent - Greet the user by their first name and offer help with a support issue.

# Omni Support Agent Workflow Index
# Purpose: Internal support intelligence system for rapid issue triage and knowledge discovery

[Metadata]
Version: 1.0
Last Updated: 2026
Purpose: Index and discovery guide for support skill automation
Audience: Internal LLMs, support agents, triage systems

[Overview]
This skill accelerates support issue resolution by systematically querying existing knowledge sources and identifying overlaps, duplicates, and relevant precedents. It operates on a read-only basis across multiple internal systems.

[Available Knowledge Sources]

## 1. GitHub Issues
Location: GitHub Issues Topic in Omni
Search Strategy: Title-based search + Body-based search (contains filters)
Key Fields: 
  - Title, Body, Status (Open/Closed)
  - Assignee (indicates active development)
  - Labels (bug, enhancement, feature-request)
Purpose: Bug identification, feature requests, product roadmap alignment
Query Pattern: Semantic search on keywords/error messages from user issue

## 2. Support Ticket Issues
Location: Support Ticket Issues Topic in Omni
Search Strategy: Title-based search + Body-based search (contains filters)
Key Fields:
  - Title, Body, Customer Name, Assignee
  - GitHub Number (cross-reference to GitHub Issues)
  - Status, Created Date, Last Updated
Purpose: Support ticket history, customer-specific issues, recurring themes
Special Handling: Flag issues where current user is assignee or collaborator
Query Pattern: Search by customer, error message, or technical theme

## 3. Google Drive Documentation
Location: Google Drive (shared drives accessible to Omni)
Subcategories:
  - Omni Technical Setup Guides - Core Configuration Topics
    This internal document provides technical guides for configuring various aspects of the Omni platform for customers and prospects.
    **Configuration Topics Covered:**
    *   Configuring a Vanity Domain (Web)
    *   Configuring a Custom Email Sender/Domain (Email)
    *   Configuring AWS Private Link
    *   Configuring an SSH Tunnel (including scenarios for updates and existing connections)
    *   Configuring Audit Logs (Covers AWS S3 and Google Cloud Storage options, plus replication)
    *   Turning on Feature Flags (General process for multi-tenant environments)
    *   IP Whitelisting
  - PE Product Expert Resource Hub - This internal document provides an overview of the Product Expert role, team processes, troubleshooting resources, Service Level Agreements (SLAs), and the broader Post Sales organization.
    **Configuration Topics Covered:**
    Customer Support Scope (Prospects, Customers, Partners)
    Support Tooling (support ticket, Atlassian Status Page, Squadcast, Internal Environments like Playground and Demo)
    Communications (Slack, Email, Microsoft Teams, Roam, Google Meet)
    Troubleshooting Playbook Needs (Model, Connection Errors, Embed, Performance, Calcs)
    Support & Escalation Process (Resource Rings, Where and How to Ask for Help, Getting help from customer facing positions)
    Filing Bugs & Feature Requests (Etiquette, Lifecycle, Communication with Customers)
    Post Sales Organization Roles (Support, Solutions/Professional Services, Success/Account Management)
Purpose: Internal process guidance, training, roadmap context
Query Pattern: Search by process name, feature name, or role-specific resources

## 4. SearchOmniDocs
Location: Official Omni Documentation (docs.omni.co)
Search Strategy: Keyword search prioritizing exact error messages, feature names
Key Areas:
  - Embedding, Semantic Model, Dashboards
  - Permissions, Connectors, Configuration
  - Troubleshooting, API Reference
Purpose: Official product documentation, customer-facing guidance
Query Pattern: Error messages, feature names, product areas

## 5. Slack Message History
Location: Omni Slack Workspace
Search Strategy: Keyword-based search across channels and threads
Purpose: Team conversations, precedent discussions, informal triage decisions
Query Pattern: Error messages, feature discussions, known workarounds
Special Handling: Include thread permalinks for full context

## 6. Product Demos
Location: Demos Topic in Omni
Key Fields:
  - Demo Title, Description, Feature Labels
  - Status, Created Date
Purpose: Visual/interactive reference for feature capabilities and skills
Query Pattern: Search by feature name or use case

## 7. Internal System Context
Current User: Accessible via system context (name, email, role)
Use For:
  - Flagging issues assigned to current user
  - Routing recommendations to appropriate teams
  - Personalizing skill recommendations

[Query Execution Rules]

1. Multi-Source Queries
   - Execute queries in parallel where possible (Steps 1–6)
   - Use consistent keywords across all sources
   - Cross-reference related findings (e.g., GitHub issue ↔ support ticket)

2. Search Strategies
   - Always run TWO searches for support ticket/GitHub: one for Title, one for Body
   - Use "contains" filters for flexible keyword matching
   - Prioritize exact error messages > feature names > general themes

3. Result Filtering
   - Flag relevance: High (exact match), Medium (thematic), Low (marginal)
   - For support ticket: Highlight current user involvement
   - For GitHub: Note assignment status (assigned = likely in development)

4. Cross-Reference Logic
   - GitHub Number (support ticket) → GitHub Issue lookup
   - Customer Name (support ticket) → Related Opportunity lookup if needed
   - Slack threads → Link to full context

[Output Structure]

Standard response format:
1. Issue Summary & Context
2. Related Issues (GitHub + support ticket tables)
3. Documentation Findings (Drive + Docs tables)
4. Slack Precedents (if any)
5. Demo References (if applicable)
6. Synthesis + Recommended Next Steps
   - What is known vs. unknown
   - Data/artifacts needed to proceed
   - Owner/team routing if applicable

[Common Query Types & Routing]

Query Type: Bug Report / Error Message
→ Search: GitHub Issues (Body), support ticket Issues, SearchOmniDocs (error message)

Query Type: Feature Request / Capability Question
→ Search: GitHub Issues (Title), Product Roadmap, SearchOmniDocs, Demos

Query Type: How-To / Setup / Configuration
→ Search: Google Drive (Technical Guides, PE Hub), SearchOmniDocs, Slack

Query Type: Customer-Specific Issue
→ Search: support ticket Issues (Customer Name), GitHub (related feature), Slack

Query Type: Performance / System Behavior
→ Search: GitHub Issues (Status), support ticket Issues (recent), Slack (recent discussions)

[Success Indicators]

A successful response includes:
- ✓ Identification of existing similar issues (prevents duplication)
- ✓ Clear indication of what is/isn't in development
- ✓ Pointer to most relevant documentation or precedent
- ✓ Explicit next steps (e.g., "needs logs from customer" or "route to @owner")
- ✓ Reduced time-to-triage for support agents

[Rate Limiting & Performance]

- GitHub/support ticket queries: Prefer filtered, semantic searches over full-table scans
- Google Drive/Docs: Use caching for common queries (roadmap, onboarding guides)
- Slack: Limit to recent 30-90 days unless historical precedent is critical
- SearchOmniDocs: Use cached/indexed results where available

[Maintenance Notes]

- Update this index when new knowledge sources are added
- Review query patterns quarterly for optimization
- Capture common recurring issues for runbook creation
- Archive resolved issues and link to post-mortems if applicable
```

## Common questions

<AccordionGroup>
  <Accordion title="What are model-defined skills?">
    Model-defined skills are created using the `skills` parameter in a [model file](/modeling/models/skills) or [topic](/modeling/topics/parameters/skills). Users with **Modeler** permissions or higher can create and edit these skills through the model IDE.
  </Accordion>

  <Accordion title="How do model-defined skills differ from chat and UI-created skills?">
    |                                                                             | **Agent or<br />UI skills**                                                                                  | **Model-defined<br />skills**                                                        |
    | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
    | **Can be created by**                                                       | Any user with Omni Agent access                                                                              | **Modelers** and higher                                                              |
    | **Runnable by**                                                             | Any user with Omni Agent access                                                                              | Users with Omni Agent access, required model permissions, and access grants (if set) |
    | **Impacted by [Omni Agent > Skills](/ai/settings/features#skills) setting** | <CheckIcon /> **Yes**                                                                                        | <XCircleIcon /> **No**                                                               |
    | **Create in chat**                                                          | <CheckIcon /> **Yes**                                                                                        | <XCircleIcon /> **No**                                                               |
    | **Create/edit on Skills page**                                              | <CheckIcon /> **Yes**                                                                                        | <XCircleIcon /> **No**                                                               |
    | **View on Skills page**                                                     | <CheckIcon /> **Yes**. Non-admins can only see skills they created. Organization Admins can view all skills. | <XCircleIcon /> **No**. Visible in model IDE only.                                   |
    | **Create/edit/view in model IDE**                                           | <XCircleIcon /> **No**                                                                                       | <CheckIcon /> **Yes**                                                                |
    | **Run from Skills page**                                                    | <CheckIcon /> **Yes**                                                                                        | <XCircleIcon /> **No**                                                               |
    | **Run with `/` in chat**                                                    | <CheckIcon /> **Yes**                                                                                        | <XCircleIcon /> **No**                                                               |
    | **Run directly in chat**                                                    | <CheckIcon /> **Yes**                                                                                        | <XCircleIcon /> **No**                                                               |
    | **Run from chat actions menu**                                              | <CheckIcon /> **Yes**                                                                                        | <CheckIcon /> **Yes**                                                                |
    | **Run by clicking skill button in chat**                                    | <XCircleIcon /> **No**                                                                                       | <CheckIcon /> **Yes**                                                                |
    | **Accepts file uploads in chat**                                            | <CheckIcon /> **Yes**                                                                                        | <CheckIcon /> **Yes**                                                                |
  </Accordion>

  <Accordion title="Will model-defined skills be replaced?">
    Yes. In the near future, Omni will deprecate model-defined skills in favor of managing skills through the Omni Agent or **Skills** page.
  </Accordion>

  <Accordion title="Will my model-defined skills still run?">
    Yes, but going forward, create skills through the Omni Agent or **Skills** page.
  </Accordion>
</AccordionGroup>

## Next steps

* [Routines](/ai/routines) — Run AI prompts on a schedule
* [AI settings](/ai/settings/features) — Turn AI features on and off for your organization
* [Library](/library) — Browse ready-made skills, apps, and routines


# Suggestions
Source: https://docs.omni.co/ai/suggestions

Apply prioritized recommendations to improve your model's AI context, based on user feedback.

**Suggestions** turn user feedback on AI-generated queries into a prioritized list of recommended improvements to your shared model. For example, a suggestion might add `ai_context` to a field that confused the AI, or refine `synonyms` on a measure users call by another name.

Suggestions live in the [**AI Hub**](/administration/ai-hub). Each suggestion targets one object in your model (a topic, a view, or a field) and includes a rationale plus the chat sessions that motivated it.

## What suggestions can change

Suggestions only recommend changes to **AI-context fields**:

* `ai_context` on the model, a topic, a view, or a field
* `description`, `synonyms`, or `sample_values` on a field

Suggestions never create, rename, or restructure model objects, and they don't touch joins, relationships, or schema.

## Requirements

* **Organization Admin** permissions (required for the AI Hub).
* Omni AI enabled in [**AI Hub > General > Features**](/administration/ai-hub) for your organization.
* A **shared model** with at least one prompt that shows signal. Signals include explicit feedback (a thumbs up/down or a comment) and automatically-detected signals in the user's prompt (positive or negative sentiment, frustrated tone, or mild or strong profanity).

## Open the suggestions page

1. Click **AI Hub** in the [sidebar](/administration/settings/sidebar).
2. Click **Suggestions** in the AI Hub sidebar.
3. Choose a shared model from the model selector.

If suggestions have been generated for the model, you'll see a prioritized list of cards. Otherwise, see [Generate suggestions](#generate-suggestions) below.

## Read a suggestion

Each card collapses to a **title** and a **priority badge**. Expand a card to see:

* **Rationale** — why this change would help, written against the feedback patterns that motivated it.
* **Suggested change** — what the AI is recommending, in plain language (for example, *"Set AI Context on Net New ARR in Opportunity"*).
* **Proposed diff** — a preview of the change to your model YAML. The actual edit is drafted by the Modeling Agent and may differ.
* **Sources** — the chat sessions whose feedback drove this suggestion. Click a source to open the chat.

Suggestions are bucketed into three priority tiers:

| Priority | What it means                                                                 |
| -------- | ----------------------------------------------------------------------------- |
| **P1**   | Highest impact. Strong, repeated signal in feedback or a clear quality issue. |
| **P2**   | Medium impact. Useful improvement supported by some feedback.                 |
| **P3**   | Lower impact. Worth considering but less urgent.                              |

Use the **All / P1 / P2 / P3 / Ignored** tabs above the list to filter by priority or view ignored suggestions.

## Generate suggestions

Suggestions are generated on a schedule.

Once you enable a schedule for a model, Omni regenerates suggestions automatically **once per day at 2:00 AM**. The timezone is captured from the browser you used to enable the schedule. The list refreshes the next time you open the AI Hub Suggestions page.

To enable a schedule:

1. Open **AI Hub > Suggestions** and select the model.
2. Click **Schedule AI suggestions…** in the empty state, or open the **⋮ Suggestion options** menu and select it.
3. Confirm the timezone shown in the dialog and click **Enable**.

<Note>
  To change a schedule's timezone, open the dialog and click **Turn off**, then re-enable it from a browser in the desired timezone. To turn scheduling off entirely, open the dialog and click **Turn off**.
</Note>

## Implement a suggestion

To apply a suggestion to your model:

1. Open the suggestion card.
2. Click **Implement in IDE chat**.
3. Omni opens the Model IDE for that shared model, with the suggestion pre-filled in the **Modeling Agent** chat panel.
4. Review the proposed change, then let the Modeling Agent draft the YAML edit.

The Modeling Agent treats the suggestion as a starting point. It may rewrite the suggested text for concision or skip a description that restates the field name. Review the edit before applying, just like any other Modeling Agent change.

Applying a suggestion does not remove it from the list — it stays until the next generation run detects the change and clears it. See [Lifecycle](#lifecycle).

## Ignore a suggestion

If a suggestion isn't relevant, you can ignore it to remove it from the main list. Ignored suggestions are moved to the **Ignored** tab, where you can review or restore them later.

To ignore a suggestion:

1. Open the suggestion card.
2. Click **Ignore** next to the **Implement in IDE chat** button, or open the **⋮** menu and select **Ignore** or **Ignore with reason…**.
3. If you selected **Ignore with reason…**, enter a note explaining why you're ignoring this suggestion, then click **Ignore**.

Ignored suggestions remain in the **Ignored** tab until you restore them. They persist across generation runs.

## Restore an ignored suggestion

To restore a suggestion you previously ignored:

1. Select the **Ignored** tab above the suggestions list.
2. Open the suggestion card.
3. Click the **⋮** menu and select **Restore**.

The suggestion returns to the main list with its original priority.

## Manage suggestions in bulk

To handle several suggestions at once, use select mode:

1. Click **Select** to the right of the tabs.
2. Check the suggestions you want to act on. The **select-all** checkbox in the bulk-action row selects or clears every suggestion in the current tab.
3. Click a bulk action:
   * On an active tab (**All / P1 / P2 / P3**): **Implement** or **Ignore**.
   * On the **Ignored** tab: **Restore**.

A live **N selected** count appears next to **Cancel**. Click **Cancel** to leave select mode without making changes.

Selection is scoped to the active tab:

* Actions apply only to the suggestions visible under the current filter.
* Switching between an active tab and the **Ignored** tab clears your selection.

Select mode closes once an action completes.

Bulk **Implement** combines the selected suggestions into a single Modeling Agent prompt and opens the Model IDE chat with every selected suggestion included.

## Ask about suggestions in the Modeling Agent

You can also browse suggestions conversationally from the Model IDE. Open the [Modeling Agent](/ai/model-assistant) chat panel and ask:

```txt theme={null}
What AI suggestions do we have for this model?
```

The agent fetches the current list, summarizes the highest-priority items, and includes links to the chat sessions that motivated each one.

## Lifecycle

Each time suggestions are generated, Omni reviews the existing list against the current state of your model and the latest feedback:

| Outcome                                                               | What happens                                             |
| --------------------------------------------------------------------- | -------------------------------------------------------- |
| Suggestion is still valid and unchanged                               | Kept as-is                                               |
| Suggestion's recommendation needs to be revised based on new feedback | Updated in place; previous source sessions are preserved |
| Suggestion's target field no longer exists in the model               | Removed                                                  |
| Suggestion is already implemented in the model                        | Removed                                                  |
| Suggestion is ignored                                                 | Remains in the **Ignored** tab until you restore it      |
| New patterns appear in feedback                                       | Added as new suggestions                                 |

Ignored suggestions persist across generation runs and are not automatically removed — they stay in the **Ignored** tab until you restore them.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I don't see a Suggestions tab in the AI Hub.">
    Verify the following:

    * You have **Organization Admin** permissions.
    * Omni AI is enabled in [**AI Hub > General > Features**](/administration/ai-hub) for your organization.
  </Accordion>

  <Accordion title="I generated suggestions but the page is empty.">
    Generation runs in the background and typically takes one to three minutes. Reload the page after a minute or two.

    If the page is still empty after several minutes, there may not be any recent prompts that meet the [signal requirements](#requirements).
  </Accordion>

  <Accordion title="I applied a suggestion but it's still in the list.">
    Applied suggestions remain in the list until the next generation run detects the change in your model. The next scheduled run, or a manual regenerate, will clear it.
  </Accordion>

  <Accordion title="A suggestion's target field no longer exists.">
    Suggestions whose target field has been renamed or removed are dropped from the list on the next generation run. You don't need to manage these manually.
  </Accordion>
</AccordionGroup>

## Next steps

* [AI Hub](/administration/ai-hub) — Monitor AI adoption, quality, and credit usage.
* [Modeling Agent](/ai/model-assistant) — Apply suggestions and edit your model from chat.
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Add the metadata that makes the AI answer better.


# Generating visualizations with AI
Source: https://docs.omni.co/ai/visualizations

Create and configure charts, tables, and KPIs using natural language prompts.

The Omni Agent can automatically suggest and configure visualizations based on your query results, including charts, KPIs, and tables. To learn about building queries with AI, refer to [Building queries & filters with AI](/ai/queries).

## Requirements

This feature requires enabling the **Omni Agent** setting in [AI settings](/ai/settings/features#workbook-agent).

## Getting started

After running a query, you can generate a visualization by directly prompting the Omni Agent. Describe the visualization you want (e.g., "Show this as a bar chart" or "Create a table with conditional formatting").

Once the Omni Agent generates a visualization, you can use the chat to refine it further. For example, you can ask the Omni Agent to change the chart type, adjust colors, or modify formatting.

## Supported visualization types

The Omni Agent can create and configure the following visualization types:

* **Charts**: Bar, line, area, pie, scatterplot, heatmap, sankey, and other chart types
* **KPIs**: Single-value metrics with formatting and comparison values
* **Tables**: Data tables with formatting, conditional styling, and display options
* **Funnels**: Visualizations showing sequential stages in a process
* **Maps**: Region maps (choropleths) and point maps for geographic and location-based data
* **Markdown**: Custom HTML/CSS layouts that combine text, images, data, and visual components like sparklines

## Example prompts

The following examples demonstrate the types of prompts you can use to create and refine visualizations with the Omni Agent.

### Creating and changing visualizations

* "Show this as a bar chart"
* "Convert this to a table"
* "Create a KPI showing total revenue"
* "Show this as a sankey diagram"
* "Create a flow chart from source to target"

### Table formatting

* "Add bars to the revenue column"
* "Show the image URLs as pictures"
* "Make the website column clickable"
* "Highlight values over 1000 in red"
* "Add a green to red color scale for the score column"

### Table styling and options

* "Add row banding"
* "Make the header dark blue with white text"
* "Freeze the first column"
* "Add pagination with 50 rows per page"
* "Group by region"

### Chart customization

* "Change the colors to blue and green"
* "Add data labels to the bars"
* "Move the legend to the bottom"

### Pie and donut charts

* "Show this as a pie chart"
* "Create a donut chart of revenue by category"
* "Make this a pie chart with percentages"
* "Show product distribution as a donut chart"

### Heatmap charts

* "Show this as a heatmap"
* "Create a heatmap of sales by day and hour"
* "Display this data as a heatmap with a custom color range"
* "Make a heatmap showing activity by week and day of week"

### Map visualizations

* "Show orders by state on a map"
* "Create a region map of sales by country"
* "Show customer locations on a point map"
* "Map revenue by region"

### Markdown visualizations

* "Create a custom HTML layout for this data"
* "Show this as a formatted text display with sparklines"
* "Create a rich card layout for these results"
* "Build a custom dashboard tile with this data"

## Next steps

* [Generating forecasts with AI](/ai/forecasting): Create statistical forecasts for time-series data
* [Markdown visualizations](/visualize-present/visualizations/types/markdown): Learn about creating custom layouts with HTML, CSS, and data
* [AI summary visualization](/visualize-present/visualizations/types/ai-summary): Generate AI summaries of query results
* [Optimizing your models for AI](/modeling/develop/ai-optimization): Improve AI results with model context


# Supported AI functions
Source: https://docs.omni.co/analyze-explore/calculations/ai

Reference for AI-powered table calculation functions in Omni for text analysis and generation, using Snowflake and Databricks.

Omni supports AI functions for text analysis and generation, powered by your warehouse's native AI capabilities. This reference details the AI functions supported by Omni.

<Note>
  This feature is currently in beta and only supported for Snowflake and Databricks databases. Reach out to Omni support to have this feature enabled.
</Note>

AI functions are translated to native SQL functions in your warehouse.

## AI\_CLASSIFY

Classifies text into one of the provided categories. Equivalent to `SNOWFLAKE.CORTEX.CLASSIFY_TEXT` in Snowflake and `ai_classify` in Databricks.

This function accepts two arguments:

* `text` - The text content to classify
* `categories` - The list of categories to classify into. A minimum of two categories are required.

```text title="Syntax" theme={null}
AI_CLASSIFY(text, category1, category2, ...)
```

```text title="Example" theme={null}
AI_CLASSIFY("I love this product!", "positive", "negative", "neutral")
```

## AI\_COMPLETE

Generates a text completion from a prompt. The model is selected automatically by the warehouse. Equivalent to `SNOWFLAKE.CORTEX.COMPLETE` in Snowflake and `ai_gen` in Databricks.

This function accepts one argument:

* `prompt` - The text prompt to generate a completion for

```text title="Syntax" theme={null}
AI_COMPLETE(prompt)
```

```text title="Example" theme={null}
AI_COMPLETE("Write a one-sentence summary of this quarter's revenue trends")
```

## AI\_EXTRACT

Extracts structured data from text based on specified labels. Equivalent to `ai_extract` in Databricks. Not currently available for Snowflake.

This function accepts two arguments:

* `text` - The text content to extract data from
* `labels` - The labels or questions defining what information to extract

Returns a JSON object containing the extracted information.

```text title="Syntax" theme={null}
AI_EXTRACT(text, labels)
```

```text title="Example" wrap theme={null}
AI_EXTRACT("John Smith lives in San Francisco and works for Snowflake", {"name": "What is the name?", "city": "What is the city?"})
```

## AI\_SENTIMENT

Analyzes the sentiment of text, returning a score indicating positive, negative, or neutral sentiment. Equivalent to `SNOWFLAKE.CORTEX.SENTIMENT` in Snowflake and `ai_analyze_sentiment` in Databricks.

This function accepts one argument:

* `text` - The text content to analyze

```text title="Syntax" theme={null}
AI_SENTIMENT(text)
```

```text title="Example" theme={null}
AI_SENTIMENT("This product exceeded my expectations!")
```

## AI\_SUMMARIZE

Summarizes text content into a shorter form. Equivalent to `SNOWFLAKE.CORTEX.SUMMARIZE` in Snowflake and `ai_summarize` in Databricks.

This function accepts one argument:

* `text` - The text content to summarize

```text title="Syntax" theme={null}
AI_SUMMARIZE(text)
```

```text title="Example" theme={null}
AI_SUMMARIZE("Omni is a business intelligence platform that connects to your data warehouse...")
```


# Supported table calculation functions
Source: https://docs.omni.co/analyze-explore/calculations/all

Learn more about the functions Omni supports for creating table calculations.

For general information about table calculations, such as how they work and how you can create them, refer to [Using table calculations](/analyze-explore/calculations).

## AI functions

<Note>
  This feature is currently in beta and only supported for Snowflake and Databricks databases. Reach out to Omni support to have this feature enabled.
</Note>

| Name                                                           | Description                                                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [AI\_CLASSIFY](/analyze-explore/calculations/ai#ai_classify)   | Classifies text into one of the provided categories.                                                   |
| [AI\_COMPLETE](/analyze-explore/calculations/ai#ai_complete)   | Generates a text completion from a prompt. The model is selected automatically by the warehouse.       |
| [AI\_EXTRACT](/analyze-explore/calculations/ai#ai_extract)     | Extracts structured data from text based on specified labels.                                          |
| [AI\_SENTIMENT](/analyze-explore/calculations/ai#ai_sentiment) | Analyzes the sentiment of text, returning a score indicating positive, negative, or neutral sentiment. |
| [AI\_SUMMARIZE](/analyze-explore/calculations/ai#ai_summarize) | Summarizes text content into a shorter form.                                                           |

## Date and time functions

| Name                                                               | Description                                                                              |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| [DATE](/analyze-explore/calculations/date-time#date)               | Creates a date from day, month, and year components.                                     |
| [DATEDIF](/analyze-explore/calculations/date-time#datedif)         | Finds the difference between two dates in specified units, such as days.                 |
| [DAY](/analyze-explore/calculations/date-time#day)                 | Returns the day of the month from a date.                                                |
| [DAYS](/analyze-explore/calculations/date-time#days)               | Finds the difference in days between two dates.                                          |
| [EOMONTH](/analyze-explore/calculations/date-time#eomonth)         | Returns the date of the last day of a month from a date or datetime value.               |
| [HOUR](/analyze-explore/calculations/date-time#hour)               | Returns the hour as a number from 0 to 23.                                               |
| [MINUTE](/analyze-explore/calculations/date-time#minute)           | Returns the minute as a number from 0 to 59.                                             |
| [MONTH](/analyze-explore/calculations/date-time#month)             | Returns the month (1-12) from a date.                                                    |
| [NETWORKDAYS](/analyze-explore/calculations/date-time#networkdays) | Returns the number of whole working days between a start and end date.                   |
| [NOW](/analyze-explore/calculations/date-time#now)                 | Returns the current date and time as a date-time value.                                  |
| [SECOND](/analyze-explore/calculations/date-time#second)           | Returns the second as a number from 0 to 59.                                             |
| [TODAY](/analyze-explore/calculations/date-time#today)             | Returns the current date as a date value.                                                |
| [WEEKDAY](/analyze-explore/calculations/date-time#weekday)         | Returns the day of the week as a number from `1` to `7`, where `1` is equal to `Sunday`. |
| [WEEKNUM](/analyze-explore/calculations/date-time#weeknum)         | Returns a number representing the week of the year where the provided date falls.        |
| [YEAR](/analyze-explore/calculations/date-time#year)               | Returns the year from a date.                                                            |

## Logic functions

| Name                                                       | Description                                                                                                                                                                       |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AND](/analyze-explore/calculations/logic#and)             | Returns true if all of the provided arguments are logically true.                                                                                                                 |
| [BITAND](/analyze-explore/calculations/logic#bitand)       | Returns the bitwise boolean AND of two numbers.                                                                                                                                   |
| [BITOR](/analyze-explore/calculations/logic#bitor)         | Returns the bitwise boolean OR of two numbers.                                                                                                                                    |
| [BITRSHIFT](/analyze-explore/calculations/logic#bitrshift) | Shifts the bits of the input a certain number of places to the right.                                                                                                             |
| [BITXOR](/analyze-explore/calculations/logic#bitxor)       | Returns a number that's the result of performing an `XOR` function at each bit of the two numbers given as arguments.                                                             |
| [IF](/analyze-explore/calculations/logic#if)               | Returns the second argument if a logical expression is true and the third argument if the expression is false.                                                                    |
| [IFERROR](/analyze-explore/calculations/logic#iferror)     | Returns the specified value if the formula returns null due to an error; otherwise returns the result of the formula. If the second argument is absent, a blank will be returned. |
| [IFNA](/analyze-explore/calculations/logic#ifna)           | Returns the specified value if the formula returns null; otherwise returns the result of the formula.                                                                             |
| [IFS](/analyze-explore/calculations/logic#ifs)             | Evaluates multiple conditions and returns a value that corresponds to the first true condition.                                                                                   |
| [ISBLANK](/analyze-explore/calculations/logic#isblank)     | Returns true if a value is blank.                                                                                                                                                 |
| [ISNUMBER](/analyze-explore/calculations/logic#isnumber)   | Returns true if a value is a number.                                                                                                                                              |
| [NOT](/analyze-explore/calculations/logic#not)             | Returns the opposite of a logical value.                                                                                                                                          |
| [OR](/analyze-explore/calculations/logic#or)               | Returns true if any of the provided arguments are logically true, and false if all of the provided arguments are logically false.                                                 |

## Math and number functions

| Name                                                                   | Description                                                                                                                           |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [ABS](/analyze-explore/calculations/math-number#abs)                   | Returns the absolute value of a number.                                                                                               |
| [ACOS](/analyze-explore/calculations/math-number#acos)                 | Returns the arccosine of a number.                                                                                                    |
| [ATAN](/analyze-explore/calculations/math-number#atan)                 | Returns the arctangent of a number. Specifically, this function returns the angle whose tangent is the specified number.              |
| [AVERAGE](/analyze-explore/calculations/math-number#average)           | Averages a list of numbers.                                                                                                           |
| [AVERAGEIFS](/analyze-explore/calculations/math-number#averageifs)     | Returns the average of a range depending on specified criteria.                                                                       |
| [CEILING](/analyze-explore/calculations/math-number#ceiling)           | Rounds numbers up to the nearest integer multiple of (optional) specified significance.                                               |
| [CORREL](/analyze-explore/calculations/math-number#correl)             | Returns the correlation coefficient of the `array1` and `array2` cell ranges.                                                         |
| [COS](/analyze-explore/calculations/math-number#cos)                   | Returns the cosine of an angle, in radians.                                                                                           |
| [COT](/analyze-explore/calculations/math-number#cot)                   | Returns the cotangent of an angle, in radians.                                                                                        |
| [COUNT](/analyze-explore/calculations/math-number#count)               | Counts the number of cells that contain values in the column. When used, the formula will be applied to the entire column.            |
| [COUNTA](/analyze-explore/calculations/math-number#counta)             | Counts the number of cells that are not empty. The value can be a reference to a cell (`E1`), a range (`B4:B9`), or a column (`C:C`). |
| [COUNTIF](/analyze-explore/calculations/math-number#countif)           | Counts the number of cells that contain values that meet a given criteria.                                                            |
| [COUNTIFS](/analyze-explore/calculations/math-number#countifs)         | Counts the number of cells that contain values that meet given criteria.                                                              |
| [COVAR](/analyze-explore/calculations/math-number#covar)               | Returns covariance, the average of the products of deviations. Equivalent to `COVAR.S`.                                               |
| [COVARIANCE.P](/analyze-explore/calculations/math-number#covariance-p) | Returns covariance, the average of the products of deviations of a population.                                                        |
| [DEGREES](/analyze-explore/calculations/math-number#degrees)           | Converts radians to degrees.                                                                                                          |
| [EXP](/analyze-explore/calculations/math-number#exp)                   | Returns `e` raised to the power of a given number.                                                                                    |
| [FLOOR](/analyze-explore/calculations/math-number#floor)               | Rounds a number down to the nearest integer multiple of specified significance.                                                       |
| [INT](/analyze-explore/calculations/math-number#int)                   | Rounds a number down to the nearest integer that is less than or equal to it. Alias for `FLOOR`.                                      |
| [INTERCEPT](/analyze-explore/calculations/math-number#intercept)       | Returns the intercept of the linear regression line through data points in X and Y data points.                                       |
| [LARGE](/analyze-explore/calculations/math-number#large)               | Returns the `nth` largest value in a data set.                                                                                        |
| [LN](/analyze-explore/calculations/math-number#ln)                     | Returns the natural logarithm of a number.                                                                                            |
| [LOG](/analyze-explore/calculations/math-number#log)                   | Returns the logarithm of a number to the specified base.                                                                              |
| [LOG10](/analyze-explore/calculations/math-number#log10)               | Returns the base-10 logarithm of a number.                                                                                            |
| [MAX](/analyze-explore/calculations/math-number#max)                   | Returns the maximum value in a data set.                                                                                              |
| [MAXIFS](/analyze-explore/calculations/math-number#maxifs)             | Returns the maximum value in a range of cells, filtered by a list of criteria.                                                        |
| [MEDIAN](/analyze-explore/calculations/math-number#median)             | Returns the median number in a set.                                                                                                   |
| [MIN](/analyze-explore/calculations/math-number#min)                   | Returns the minimum value in a data set.                                                                                              |
| [MINIFS](/analyze-explore/calculations/math-number#minifs)             | Returns the minimum value in a range of cells, filtered by a list of criteria.                                                        |
| [MOD](/analyze-explore/calculations/math-number#mod)                   | Returns the remainder of a division.                                                                                                  |
| [OMNI\_RANK](/analyze-explore/calculations/math-number#omni_rank)      | Returns the rank of a number in a list of numbers, with row or column direction.                                                      |
| [MODE](/analyze-explore/calculations/math-number#mode)                 | Returns the most common number in a set.                                                                                              |
| [RAND](/analyze-explore/calculations/math-number#rand)                 | Generates a random number between 0 and 1.                                                                                            |
| [RANK](/analyze-explore/calculations/math-number#rank)                 | Returns the rank of a number in a list of numbers.                                                                                    |
| [ROUND](/analyze-explore/calculations/math-number#round)               | Rounds a number to a specified number of digits.                                                                                      |
| [ROUNDDOWN](/analyze-explore/calculations/math-number#rounddown)       | Rounds a number down, towards zero, to a specified number of digits.                                                                  |
| [ROUNDUP](/analyze-explore/calculations/math-number#roundup)           | Rounds a number up, away from zero, to a specified number of digits.                                                                  |
| [SLOPE](/analyze-explore/calculations/math-number#slope)               | Returns the slope of the linear regression line through data points in Ys and Xs.                                                     |
| [SMALL](/analyze-explore/calculations/math-number#small)               | Returns the nth smallest value in a data set.                                                                                         |
| [SQRT](/analyze-explore/calculations/math-number#sqrt)                 | Returns a positive square root.                                                                                                       |
| [STDEV](/analyze-explore/calculations/math-number#stdev)               | Estimates the standard deviation based on a population of values.                                                                     |
| [STDEV.P](/analyze-explore/calculations/math-number#stdev-p)           | Estimates the standard deviation based on an entire population.                                                                       |
| [SUM](/analyze-explore/calculations/math-number#sum)                   | Adds all the numbers in a range of cells.                                                                                             |
| [SUMIF](/analyze-explore/calculations/math-number#sumif)               | Adds the cells specified by a given criteria.                                                                                         |
| [SUMIFS](/analyze-explore/calculations/math-number#sumifs)             | Adds the cells specified by multiple criteria.                                                                                        |
| [SUMPRODUCT](/analyze-explore/calculations/math-number#sumproduct)     | Returns the sum of the products of corresponding array components.                                                                    |
| [TRUNC](/analyze-explore/calculations/math-number#trunc)               | Truncates a number to an integer by removing the decimal portion of a number.                                                         |
| [VALUE](/analyze-explore/calculations/math-number#value)               | Converts a text argument to a number.                                                                                                 |
| [VAR](/analyze-explore/calculations/math-number#var)                   | Calculates the variance based on a sample of values.                                                                                  |
| [VAR.P](/analyze-explore/calculations/math-number#var-p)               | Returns the variance of a population.                                                                                                 |

## Position functions

| Name                                                              | Description                                                                                                        |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [INDEX](/analyze-explore/calculations/position#index)             | Returns the content of a cell, specified by row and column offset.                                                 |
| [MATCH](/analyze-explore/calculations/position#match)             | Returns the relative position of an item in a range that matches a specified value.                                |
| [PIVOT](/analyze-explore/calculations/position#pivot)             | Returns a value from a specific pivot in the results table.                                                        |
| [PIVOTINDEX](/analyze-explore/calculations/position#pivotindex)   | Returns the index of the current pivot.                                                                            |
| [PIVOTOFFSET](/analyze-explore/calculations/position#pivotoffset) | Returns a pivot value offset from the current pivot column.                                                        |
| [PIVOTROW](/analyze-explore/calculations/position#pivotrow)       | Returns the values of a specified row in a pivot.                                                                  |
| [ROW](/analyze-explore/calculations/position#row)                 | Returns the current row number.                                                                                    |
| [SWITCH](/analyze-explore/calculations/position#switch)           | Evaluates an expression against a list of values and returns the result corresponding to the first matching value. |
| [VLOOKUP](/analyze-explore/calculations/position#vlookup)         | Searches for a value in a range and returns the value in the specified column.                                     |
| [XLOOKUP](/analyze-explore/calculations/position#xlookup)         | Searches for a value in a specified range in another query/tab and returns the corresponding value from the range. |

## Text functions

| Name                                                          | Description                                                                                                            |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [CHAR](/analyze-explore/calculations/text#char)               | Returns the character specified by a number.                                                                           |
| [CONCAT](/analyze-explore/calculations/text#concat)           | Concatenates (combines) any number of strings into a single string.                                                    |
| [CONCATENATE](/analyze-explore/calculations/text#concatenate) | Concatenates (combines) any number of strings into a single string. Alias for `CONCAT`.                                |
| [CLEAN](/analyze-explore/calculations/text#clean)             | Returns text with the non-printable ASCII characters removed. Unicode characters that aren't in ASCII are not removed. |
| [EXACT](/analyze-explore/calculations/text#exact)             | Tests whether two text strings are exactly the same.                                                                   |
| [FIND](/analyze-explore/calculations/text#find)               | Returns the position of one string inside another.                                                                     |
| [LEFT](/analyze-explore/calculations/text#left)               | Returns the specified number of characters from the start of a text string.                                            |
| [LEN](/analyze-explore/calculations/text#len)                 | Returns the length (number of characters) of a string.                                                                 |
| [LOWER](/analyze-explore/calculations/text#lower)             | Converts text to lowercase.                                                                                            |
| [MID](/analyze-explore/calculations/text#mid)                 | Returns a specific number of characters from a text string starting at the specified position.                         |
| [PROPER](/analyze-explore/calculations/text#proper)           | Capitalizes the first letter of each word in a text string.                                                            |
| [REPLACE](/analyze-explore/calculations/text#replace)         | Replaces characters in a string with new text.                                                                         |
| [RIGHT](/analyze-explore/calculations/text#right)             | Returns the specified number of characters from the end of a text string.                                              |
| [SEARCH](/analyze-explore/calculations/text#search)           | Finds one text value within another, ignoring case.                                                                    |
| [SUBSTITUTE](/analyze-explore/calculations/text#substitute)   | Substitutes new text for old text in a string.                                                                         |
| [TRIM](/analyze-explore/calculations/text#trim)               | Removes leading, trailing, and repeated spaces from text.                                                              |
| [T](/analyze-explore/calculations/text#t)                     | Returns arguments as text.                                                                                             |
| [TEXT](/analyze-explore/calculations/text#text)               | Converts a number into text according to a specified format.                                                           |
| [UPPER](/analyze-explore/calculations/text#upper)             | Converts text to uppercase.                                                                                            |


# Supported date & time functions
Source: https://docs.omni.co/analyze-explore/calculations/date-time

Omni supports functions typically found in most spreadsheet applications such as Google Sheets. This reference details the date and time functions supported by Omni.

## DATE

Creates a date from day, month, and year components. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3092969).

```
DATE(year, month, day)
```

```
DATE(2022, 12, 22)
```

## DATEDIF

Finds the difference between two dates in specified units, such as days.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/6055612).

```
DATEDIF(start_date, end_date, "unit")
```

**Example**

```
DATEDIF(A1, B1, "M")
```

## DAY

Returns the day of the month from a date.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093040).

```
DAY(date)
```

**Example**

```
DAY("2022-12-22")
```

## DAYS

Finds the difference in days between two dates. Similar to [`DATEDIF`](#datedif).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9061296).

```
DAYS(end_date, start_date)
```

**Example**

```
DAYS(“2/28/2017”, “2/28/2016”)
```

## EOMONTH

Returns the date of the last day of a month from a date or datetime value. This function takes two arguments:

* `date_value` - The date from which to calculate the result
* `offset_months` - The number of months before (negative) or after (positive) the `date_value` to consider

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093044).

```
EOMONTH(date_value, offset_months)
```

**Example**

```
EOMONTH("3/1/2024", 0)
```

## HOUR

Returns the hour as a number from `0` (`12:00 A.M.`) to `23` (`11:00 P.M.`).

For more examples, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093045).

```
HOUR(time)
```

**Example**

```
HOUR(A1)
HOUR("15:30")
HOUR("20:49:59")
```

## MINUTE

Returns the minute as a number from `0` to `59`.

For more examples, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093048).

```
MINUTE(time)
```

**Example**

```
MINUTE(A1)
MINUTE("15:30")
MINUTE("20:49:59")
```

## MONTH

Returns the month (`1`-`12`) from a date.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093052).

```text theme={null}
MONTH(date)
```

**Example**

```text theme={null}
MONTH("2022-12-22")
```

## NETWORKDAYS

Returns the number of whole working days between `start_date` and `end_date`. Weekend days are excluded. **Note**: While similar to Excel, Omni's implementation of this function does not support the third `holidays` argument.

```
NETWORKDAYS(start_date,end_date)
```

<Info>
  Date arguments used in this function must be specified using one of the following methods:

  * The [DATE](#date) function, for example: `DATE(2025, 1, 1)`
  * As the result of another formula or function
  * As cell references (`A1`)
</Info>

**Example**

```
NETWORKDAYS(DATE(2025, 1, 1), DATE(2025, 2, 1))
NETWORKDAYS(A1,B1)
```

## NOW

Returns the current date and time as a date-time value. To create a date without the current time, use [`TODAY`](#today).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3092981).

```
NOW()
```

**Example**

```
NOW()
```

## SECOND

Returns the second as a number from `0` to `59`.

For more examples, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093054).

```
SECOND(time)
```

**Example**

```
SECOND(A1)
SECOND("20:49:59")
```

## TODAY

Returns the current date as a date value. Does not accept arguments. To create a date with the current time, use [`NOW`](#now).

For more examples, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3092984).

```
TODAY()
```

**Example**

```
TODAY()
```

## WEEKDAY

Returns the day of the week as a number from `1` to `7`, where `1` is equal to `Sunday`. The optional `return_type` argument controls the numbering scheme.

```
WEEKDAY(date, [return_type])
```

**Example**

```
WEEKDAY("2022-12-22")
WEEKDAY("2022-12-22", 2)
```

## WEEKNUM

Returns a number representing the week of the year where the provided date falls. This function accepts two arguments:

* `date` - The date for which to calculate the week number. Must be a date, a function returning a date type, or a number.
* `type` - **Optional**. A number representing the day that a week starts on. Defaults to `1` (Sunday).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3294949).

```
WEEKNUM(date, [type])
```

**Example**

```
WEEKNUM("2022-12-22", 2)
```

## YEAR

Returns the year from a date.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093061).

```
YEAR(date)
```

**Example**

```
YEAR("2022-12-22")
```


# Using Excel-style functions to create table calculations
Source: https://docs.omni.co/analyze-explore/calculations/index

Create formulas that manipulate and calculate data with Excel-style functions.

Table calculations create ad hoc metrics that are performed post query processing on the result set, similar to Excel or Google Sheets. They can build contextual metrics like percent of row or column, period over period changes, or other calculations to customize analyses or visualizations.

## Table calculations in Omni

<AccordionGroup>
  <Accordion title="What are functions?">
    Functions are predefined formulas designed to make calculations on values easier. For example:

    ```text theme={null}
    NOW()           # Returns the current date and time, ex: 2025-05-09 18:23:30.521
    TODAY()         # Returns the current date, ex: 2025-05-09
    ```
  </Accordion>

  <Accordion title="What are arguments?">
    Some functions can accept **arguments**, which is the input or information provided to the function. In the following example, the arguments are `1, 2, 3`:

    ```text theme={null}
    SUM(1,2,3)         # Returns 6
    ```

    Arguments can be several types, which can be thought of as the compositional building blocks of calculations:

    * **String literals** - Strings of text, which must be wrapped in double quotes. For example: `"Hello, Blobby!"`
    * **Number literals** - Numbers, such as `1` or `14`. Can be used alone or as arguments.
    * **Logical literals** - Boolean values (`TRUE`, `FALSE`). **Note**: Must be all caps or the values will be interpreted as a cell reference.
    * **Unary Operators / Negation** - Negates (`-`) or adds (`+`) a value. Can be thought of as operators with only a right operand. For example:

      ```text theme={null}
      -daily_budget     # Returns the negative value of daily_budget, ex: -500
      ```

      **Note**: The `+` operator can also be used as a unary. However, Omni typically ignores it because `+1` and `1` are logically equivalent.
    * **Cell references** - Points to a specific cell in a dataset. The row can be omitted to reference only the column.

      Omni interprets cell references relative to the first row of data. Calculations will be applied to all following rows with the number changed to offset how many rows down you are.

      ```text theme={null}
      C1                    # Reference column C in row 1C2 + 10               # Reference column C in row 2users.count + 10      # Reference users.count column
      ```
    * **Cell range references** - Compound cell reference that describes a span between one cell and another. Can be used to reference an entire column or a subset of the column's data. **Note**: Cell ranges are inclusive.

      ```text theme={null}
      C1:C5                 # Include cells C1,C2,C3,C4,C5C:C                   # Include all of column C
      ```
  </Accordion>

  <Accordion title="What functions does Omni support?">
    Refer to the [Omni supported functions reference](/analyze-explore/calculations/all) for a list of the functions Omni currently supports.
  </Accordion>

  <Accordion title="Are Omni functions the same as Excel or Google Sheets?">
    Omni aims to be compatible with Excel or Google Sheets wherever possible. The Google Sheets documentation included in the [Omni supported functions reference](/analyze-explore/calculations/all) is useful for enhancing your understanding of Omni's functions.

    **Note**: For some functions, there are some differences between Omni's implementation and Google Sheets'. Refer to the reference for the specific Omni function for more information.
  </Accordion>

  <Accordion title="What are the OMNI_PIVOT functions in the query's SQL?">
    There are some other functions you may see in the SQL that are not meant for end-user use, but help make the SQL blocks easier to parse in normal usage:

    <img alt="" />

    The `OMNI_PIVOT_ROW(dimensions)` and `OMNI_PIVOT(column_limit, pivots)` structure the pivot table experience.

    * `OMNI_PIVOT_ROW` sets the query columns outside the pivot
    * `OMNI_PIVOT` sets the query columns to pivot, along with a limit on columns
  </Accordion>
</AccordionGroup>

## Create table calculations

There are a few ways to create calculations in Omni:

* [**Quick calculations**](#quick-calculations), which allow you to create calculations like a running total or % of previous with just a few clicks
* [**Using AI**](#ai-generated), which can help you get started quickly
* [**Manually**](#manually-created-calculations), which allows you to iterate and build at your own pace

Each approach can use all of [Omni's supported functions](/analyze-explore/calculations/all). Additionally, regardless of how the calculation is created, calculations can be [renamed, formatted](#rename-and-format-calculations), and [added to the workbook](#promote-table-calculations).

<Note>
  Before you get started:

  * Make sure that the query includes the fields you want to use in the calculation
  * Keep in mind that all alphabetic characters must be wrapped in double quotes (`"`) unless referring to a specific cell or column. For example: `"Hello, Blobby!"`. Single quotes are not valid for wrapping strings in Omni.
</Note>

### Quick calculations

Quick calculations, such as percent of total, can be used on **numeric** data in a workbook results table in the query builder or SQL editor. They can also be used across pivots. For example, a running total for a row.

To create a quick calculation:

<Steps>
  <Step>
    Click the <Icon icon="ellipsis-vertical" /> icon in the header of a numeric column in the results table, then **Calculations**:

    <img alt="" />
  </Step>

  <Step>
    Select an option from the **Calculations** menu. A new column will be created in the table:

    <img alt="" />
  </Step>
</Steps>

The new column will be named using the convention `<column_name> + <quick_calculation>`, but you can [rename it](#rename-and-format-calculations) if needed.

### AI-generated

With Omni's AI, you can write complex, Excel-like formulas using natural language. Having AI create calculated fields for you reduces the time you'd otherwise spend searching for the right syntax and iterating to get it just right.

<Steps>
  <Step title="Open the calculation prompt">
    In a workbook, click the <Icon icon="sparkles" /> icon in the calculations bar. This opens a small textbox:

    <img alt="Workbook AI formula button" />

    You can also use the chat interface to write calculations. How you access the agent differs depending on whether you're using an embedded Omni instance or not:

    * **Embedded** - Click the <Icon icon="sparkles" /> icon in the workbook's sidebar
    * **Non-embedded Omni** - Click the floating avatar to open the chat panel
  </Step>

  <Step title="Describe the formula">
    In the chat or calculation text box, describe the formula you'd like to create. You can include the function to use if you know it, but otherwise, it's helpful to be specific about what you're trying to achieve. Refer to the [Examples](#examples) section to get some inspiration.

    If you're not sure where to begin, click **Get suggestions** in the formula prompt window to generate a list of potential starting points:

    <img alt="Formula suggestions list" />
  </Step>

  <Step title="Submit the prompt">
    When finished, click **->** to submit the prompt to AI.

    If you need to [rename the column](#rename-and-format-calculations), you can do so using the column header's options menu or the table options.
  </Step>
</Steps>

Check out the [Examples](#examples) section to see some example prompts you can use to create calculations.

### Manually-created calculations

You can also manually create calculations in the results table of a query:

<Steps>
  <Step>
    Click the **Add a column icon** to first add a new column to the table. **Note**: The new column will be named `Calculation` by default, but you can [rename it](#rename-and-format-calculations).

    <img alt="" />
  </Step>

  <Step>
    In a cell or the function editor, enter `=` to start building the calculation. **Note**: The calculation must start with an equals sign (`=`).
  </Step>

  <Step>
    Build the calculation using Omni's [supported functions](/analyze-explore/calculations/all). The following image shows an example of a [`DATEDIF`](/analyze-explore/calculations/date-time#datedif) calculation, which was used to calculate the number of days between the `Created At` and `Delivered At` columns:

    <img alt="" />
  </Step>
</Steps>

Check out the [Examples](#examples) section to see some of what's possible, such as how to return nulls or reference column totals.

## Evaluating calculations before or after row limits

When you create a calculation with a range reference like `=SUM(B:B)` in a query with a row limit, the calculation by default evaluates only on the rows returned - specifically, rows visible in the table - after the limit is applied. Calculation pushdown allows these calculations to run against the full underlying dataset before the row limit is applied.

For example, without pushdown, a `=SUM(B:B)` calculation in a query limited to 1,000 rows would sum only those 1,000 rows. With pushdown enabled, the calculation sums all rows in the dataset, then the row limit is applied to the final result.

Calculations are eligible for pushdown when they reference ranges (like `B:B`, `A1:A100`, or `B1:B`) rather than individual cells.

Examples of eligible calculations:

* `=SUM(B:B)` - Sum all values in column B
* `=RANK(B1, B:B, 0)` - Rank current row within all values in column B
* `=AVERAGE(C:C)` - Average of all values in column C

### Toggling evaluation behavior

When a calculation references a range and rows have been limited (either by offset or by reaching the row limit), Omni displays a <Icon icon="circle-info" /> icon in the calculation's column header:

<Frame>
  <img alt="Alt text" />
</Frame>

You can toggle pushdown for a compatible calculation using the column actions menu:

1. Click the column header for the calculation.
2. Select **Apply before row limit** from the menu.
3. The calculation will be re-evaluated.

To disable this behavior, click the column header menu and select **Apply after row limit**.

<Tip>
  Use the model-level [`calcs_default_pushdown`](/modeling/models/calcs-default-pushdown) to define default pushdown behavior for all calculations in the model.
</Tip>

### Limitations

Pushdown isn't currently supported for calculations in pivoted queries.

## Rename and format calculations

In the **Options** for the **Results** table, you can rename or change the formatting for calculations.

You can also rename a calculation by double-clicking the column header and entering a new name:

<img alt="" />

## Promote table calculations

To reuse a calculation in a workbook, you can promote it to the workbook model. Click the <Icon icon="ellipsis-vertical" /> icon in the calculation column's header, then **Add to workbook**:

<img alt="" />

Once added to the workbook model, you can then promote the calculation to the [shared model](/modeling/develop/model-management#shared-model-promotion).

<Note>
  Some limitations do exist depending on the type of calculation, such as calculations based on other calculations or those that include a range. This is because some calculations depend on the shape of a specific result set.

  For example, a seven-day moving average that works when data is grouped by day, but not if the grouping is by month.
</Note>

## Duplicate calculations

To create a copy of an existing calculation, click the <Icon icon="ellipsis-vertical" /> icon in the calculation column's header, then **Duplicate**.

This creates a new column with a copy of the calculation, which you can then modify. This is useful when you want to create variations of an existing calculation, such as testing a formula change or creating similar calculations for different fields.

## Drill from calculated fields

Calculated fields can surface drill options from the modeled fields they reference. When a calculation references fields that have drill metadata defined in your model, you can drill into those underlying fields directly from the calculation column.

For example, if you have a calculation that divides one measure by another (like `=B1 / C1`), you can drill into either of those measures to see the underlying detail rows that make up the calculated value.

### How drilling works for calculations

Drilling is automatically enabled for calculations that reference drillable fields. No additional configuration is required—the calculation inherits the drill behavior from the modeled fields it references.

When you click on a calculated field value or open its context menu, you'll see drill options for each of the drillable fields the calculation uses. If a referenced measure has named drill queries defined via the [`drill_fields` parameter](/modeling/measures/parameters/drill-fields), those drill queries will also appear in the menu.

### Enable or disable drilling

Drilling is enabled by default for calculations, but you can disable it for specific calculations:

1. Click the <Icon icon="ellipsis-vertical" /> icon in the calculation column's header
2. Toggle **Enable drill** or **Disable drill** to change the setting for that calculation

### Limitations

Drilling from calculated fields only works for calculations that reference plain field values. The following types of references do not support drilling:

* Offset references (like `=B1 / B0` for period-over-period calculations)
* Range references (like `=SUM(B1:B7)` for moving averages)
* Cross-query lookups using functions like `XLOOKUP` that reference fields from other queries

These limitations exist because these calculation types don't directly use the field values from the current row, so there's no clear drill target.

## Examples

<AccordionGroup>
  <Accordion title="Return null values">
    To return a `null` value, use `1/0` as the calculation. Nulls will display as blanks.

    <img alt="" />
  </Accordion>

  <Accordion title="Total references">
    Using row and column totals can be effective for more complex calculations across rows or columns independently. These aggregates can be referenced in calculations when they are activated for queries, which you can do in the **Options** menu for the **Results** table.

    <img alt="" />

    This example references:

    * **Column total** `${users.count:column_total}`
    * **Row total** - `${users.count:row_total}`
    * **Grand total (columns and rows, lower right**) - `${users.count:grand_total}`

    These can also be chained with other functions. For example:

    ```markdown theme={null}
    # Percent of row

    ${users.count} * 100.0 / ${users.count:row_total}`.
    ```

    To reference these totals within table calculations:

    * **Column total** `<ROW_LETTER>_TOTAL`
    * **Row total** `<ROW_LETTER>_ROW_TOTAL`
    * **Grand total** `<ROW_LETTER>GRAND_TOTAL`
  </Accordion>

  <Accordion title="Free text values">
    Calculations can also contain free text - just leave out the equals sign when creating the calculation. When you don't include the equals sign, Omni will not treat the cell's value as a formula.

    To create this type of calculation, add a new column to the table and then enter text in the cells.

    Free-text values can be used to cross-reference columns or cells in other workbook tabs. To do this, create a new column, enter an equal sign, and \` (backtick) to pull up the tab names in the cell:

    <img alt="" />
  </Accordion>

  <Accordion title="AI-generated: two letter abbreviations for US states" icon="robot">
    <Prompt description="Using IFS, create a formula that uses the standard two letter abbreviations for US states. For District of Columbia, use DC as the abbreviation.">
      Using IFS, create a formula that uses the standard two letter abbreviations for US states. For District of Columbia, use DC as the abbreviation.
    </Prompt>

    In the example query, the `A` column contains the full name of the state. For example, `California` or `Pennsylvania`.

    ```sql title="Generated formula" wrap expandable theme={null}
    =IFS(A1 = "Alabama", "AL", A1 = "Alaska", "AK", A1 = "Arizona", "AZ", A1 = "Arkansas", "AR", A1 = "California", "CA", A1 = "Colorado", "CO", A1 = "Connecticut", "CT", A1 = "Delaware", "DE", A1 = "Florida", "FL", A1 = "Georgia", "GA", A1 = "Hawaii", "HI", A1 = "Idaho", "ID", A1 = "Illinois", "IL", A1 = "Indiana", "IN", A1 = "Iowa", "IA", A1 = "Kansas", "KS", A1 = "Kentucky", "KY", A1 = "Louisiana", "LA", A1 = "Maine", "ME", A1 = "Maryland", "MD", A1 = "Massachusetts", "MA", A1 = "Michigan", "MI", A1 = "Minnesota", "MN", A1 = "Mississippi", "MS", A1 = "Missouri", "MO", A1 = "Montana", "MT", A1 = "Nebraska", "NE", A1 = "Nevada", "NV", A1 = "New Hampshire", "NH", A1 = "New Jersey", "NJ", A1 = "New Mexico", "NM", A1 = "New York", "NY", A1 = "North Carolina", "NC", A1 = "North Dakota", "ND", A1 = "Ohio", "OH", A1 = "Oklahoma", "OK", A1 = "Oregon", "OR", A1 = "Pennsylvania", "PA", A1 = "Rhode Island", "RI", A1 = "South Carolina", "SC", A1 = "South Dakota", "SD", A1 = "Tennessee", "TN", A1 = "Texas", "TX", A1 = "Utah", "UT", A1 = "Vermont", "VT", A1 = "Virginia", "VA", A1 = "Washington", "WA", A1 = "West Virginia", "WV", A1 = "Wisconsin", "WI", A1 = "Wyoming", "WY", A1 = "District of Columbia", "DC")
    ```

    **Results table**

    | State    | State Abbreviation |
    | -------- | ------------------ |
    | Alabama  | AL                 |
    | Alaska   | AK                 |
    | Arizona  | AZ                 |
    | Arkansas | AR                 |
    | ...      | ...                |
  </Accordion>

  <Accordion title="AI-generated: extract domain from email" icon="robot">
    <Prompt description="Give me the domain from the email column.">
      Give me the domain from the email column.
    </Prompt>

    In the example query, the `A` column contains an email address. For example, `blobby@blobsrus.com`.

    ```sql title="Generated formula" theme={null}
    =RIGHT(A1, LEN(A1) - FIND("@", A1))
    ```

    **Results table**

    | Email                        | Email Domain   |
    | ---------------------------- | -------------- |
    | `blobby@blobsrus.com`        | blobsrus.com   |
    | `blobross@gmail.com`         | gmail.com      |
    | `bobbyparton@blobbyworld.co` | blobbyworld.co |
  </Accordion>

  <Accordion title="AI-generated: identify a date as a weekday or a weekend" icon="robot">
    <Prompt description="Tell me if COLUMN_A is a weekday or a weekend.">
      Tell me if COLUMN\_A is a weekday or a weekend.
    </Prompt>

    If you receive an error for the above prompt, try this instead:

    <Prompt description="Tell me if COLUMN_A is a weekday or a weekend. If using WEEKDAY, only provide a date as an argument.">
      Tell me if COLUMN\_A is a weekday or a weekend. If using WEEKDAY, only provide a date as an argument.
    </Prompt>

    In the example query, the `A` column contains a timestamp.

    ```sql title="Generated formula" theme={null}
    =IF(OR(WEEKDAY(A1)=1,WEEKDAY(A1)=7),"Weekend","Weekday")
    ```

    **Results table**

    | Date                    | Weekday or Weekend |
    | ----------------------- | ------------------ |
    | 2024-12-27 00:25:19.000 | Weekday            |
    | 2024-09-30 13:11:47.000 | Weekend            |
    | 2023-04-27 18:59:25.000 | Weekday            |
    | 2022-05-15 18:02:33.000 | Weekday            |
  </Accordion>
</AccordionGroup>


# Supported logic functions
Source: https://docs.omni.co/analyze-explore/calculations/logic

Omni supports functions typically found in most spreadsheet applications such as Google Sheets. This reference details the logic functions supported by Omni.

## AND

Returns `true` if all of the provided arguments are logically true. Returns `false` if any of the provided arguments are false. Can be combined with other functions like [`IF`](#if) to create advanced logical statements.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093301).

```
AND(condition1, condition2, ...)
```

**Example**

```
AND(A1 > 5, B1 < 10)         # Returns true if both conditions are true
```

## BITAND

Returns the bitwise boolean `AND` of two numbers.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9061440).

```
BITAND(value1, value2)
```

**Example**

```
BITAND(6, 3)
```

## BITOR

Returns the bitwise boolean `OR` of two numbers.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9083934).

```
BITOR(value1, value2)
```

**Example**

```
BITOR(6, 3)
```

## BITRSHIFT

Shifts the bits of the input a certain number of places to the right. Bits on the left are filled with zeroes. This function accepts two arguments:

* `value` - The number to be shifted
* `shift_amount` - The number of places to shift the given value

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9084100).

```
BITRSHIFT(value, shift_amount)
```

**Example**

```
BITRSHIFT(8, 2)
```

## BITXOR

Returns a number that's the result of performing an `XOR` function at each bit of the two numbers given as arguments. This function is a bitwise XOR (exclusive or) of 2 numbers that returns a bit of `“1”` if 2 bits are different, and a bit of `“0”` otherwise.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9083935).

```
BITXOR(value1, value2)
```

**Example**

```
BITXOR(5, 3)
```

## IF

Returns the second argument if a logical expression is `TRUE` and the third argument if the expression is `FALSE`. To evaluate multiple conditions, use [`IFS`](#ifs).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093364).

```
IF(condition, true_value, false_value)
```

**Example**

```
IF(A1 > 10, "big", "small")
```

## IFERROR

Returns the specified value (`optional_value_if_error`) if the formula returns null due to an error; otherwise returns the result of the formula (`value`). If the second argument is absent, a blank will be returned.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093304)

```
IFERROR(value, [optional_value_if_error])
```

**Example**

```
IFERROR(A1, "Error in cell A1")
```

## IFNA

Returns the specified value if the formula returns null; otherwise returns the result of the formula.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9365944).

```
IFNA(value, default_value)
```

**Example**

```
IFNA(VLOOKUP("X", A1:B10, 2, FALSE), "Not Found")
```

## IFS

Evaluates multiple conditions and returns a value that corresponds to the first true condition. Similar to [`IF`](#if).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/7014145).

```
IFS(condition1, value1, condition2, value2, ..., [default_value])
```

**Example**

```
IFS(A1 > 90, "A", A1 > 80, "B", A1 > 70, "C", TRUE, "F")
```

## ISBLANK

Returns `TRUE` if a value is blank.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093290).

```
ISBLANK(value)
```

**Example**

```
ISBLANK(A1)
```

## ISNUMBER

Returns `TRUE` if a value is a number.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093296?hl=en)

```
ISNUMBER(value)
```

**Example**

```
ISNUMBER(10)
```

## NOT

Returns the opposite of a logical value:

* `NOT(TRUE)` returns `FALSE`
* `NOT(FALSE)` returns `TRUE`

Because `0` has a logical value of `FALSE` and any non-zero numeric value has a logical value of `TRUE`, `NOT(0)` returns `TRUE` and `NOT(6)` returns `FALSE`. However, when non-numeric values are input into `NOT`, the function returns the error `#VALUE!`.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093305?hl=en#).

```
NOT(logical_expression)
```

**Example**

```
NOT(1+1=2)        # FALSE
NOT(1+4=3)        # TRUE
```

## OR

Returns `true` if any of the provided arguments are logically true, and `false` if all of the provided arguments are logically false. Can be combined with other functions like [`IF`](#if) to create advanced logical statements.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093306).

```
OR(condition1, condition2)
```

**Example**

```
OR(A1 < 1, A1 > 3)
```


# Supported math and number functions
Source: https://docs.omni.co/analyze-explore/calculations/math-number

Omni supports functions typically found in most spreadsheet applications such as Google Sheets. This reference details the math and number functions supported by Omni.

## Working with math functions

Some math expressions will contain binary operators. These are operators that take both a left and right operand. For example, in `1 + 2`:

* `1` is the left operand
* `+` is the binary operator
* `2` is the right operand

When working with expressions, note that they will follow the standard order of operations. This means the expression will multiply and divide before addition and subtraction. Use parenthesis to clarify the expression or alter the order.

## Supported operators

| Name                     | Operator |
| :----------------------- | :------- |
| Concatenate              | `&`      |
| Plus                     | `+`      |
| Minus                    | `-`      |
| Multiply                 | `*`      |
| Divide                   | `/`      |
| Exponentiate             | `^`      |
| Greater than             | `>`      |
| Greater than or equal to | `>=`     |
| Equal to                 | `=`      |
| Less than                | `<`      |
| Less than or equal to    | `<=`     |

## ABS

Returns the absolute value of a number. The `value` argument can be a numeric value (`3`) or a reference to a cell, range, or column containing numeric data.

For more information, refer to the [Google Sheets documentation](https://support.google.com/appsheet/answer/10107329?hl=en\&sjid=7987109666653796078-NC).

```
ABS(value)
```

**Example**

```
ABS(-14)
```

## ACOS

Returns the arccosine of a number. This function returns the angle whose cosine is the specified number.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093582?hl=en).

```
ACOS(number)
```

**Example**

```
ACOS(0.5)
```

## ATAN

Returns the arctangent of a number. Specifically, this function returns the angle whose tangent is the specified number.

For additional information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093395?hl=en).

```
ATAN(number)
```

**Example**

```
ATAN(0.5)
```

## AVERAGE

Averages a list of numbers. The list can be composed of number literals (`10`), cell references (`A1`), cell ranges (`B4:B9`), and column references (`C:C`).

When used, the function will apply to all values in the column.

For more details, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093615?hl=en).

```
AVERAGE(value1, value2, ...)
```

**Example**

```
AVERAGE(1, 2, 3, 4)
```

## AVERAGEIFS

Returns the average of a range depending on specified criteria.

For more details, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3256534?hl=en).

```
AVERAGEIFS(range_to_average, criteria_range1, criterion1, [criteria_range2, criterion2, ...])
```

**Example**

```
AVERAGEIFS(A1:A10, B1:B10, ">20")
```

## CEILING

Rounds numbers up to the nearest integer multiple of (optional) specified significance. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093471?hl=en).

```
CEILING(value, <significance-optional>)
```

**Example**

```
CEILING(A1, .05)
```

## CORREL

Returns the correlation coefficient of the `array1` and `array2` cell ranges. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093990?hl=en).

```
CORREL(array1, array2)
```

**Example**

```
CORREL(A1:A3, B1:B3)
```

## COS

Returns the cosine of an angle, in radians. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093476?hl=en\&ref_topic=3105474\&sjid=7436250830009921699-NA).

```
COS(number)
```

**Example**

```
COS(45)
```

## COT

Returns the cotangent of an angle, in radians. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/9084169?hl=en\&ref_topic=3105474\&sjid=7436250830009921699-NA).

```
COT(number)
```

**Example**

```
COT(45)
```

## COUNT

Counts the number of cells that contain values in the column. When used, the formula will be applied to the entire column. For more information, refer to the see the [Google Sheets documentation](https://support.google.com/docs/answer/3093620?sjid=7436250830009921699-NA).

The value can be a reference to a cell (`E1`), a range (`B4:B9`), or a column (`C:C`).

```
COUNT(value)
```

**Example**

```
COUNT(A1)
COUNT(A1:A12)
COUNT(D:D)
```

## COUNTA

Counts the number of cells that are not empty. The value can be a reference to a cell (`E1`), a range (`B4:B9`), or a column (`C:C`). For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093991?hl=en).

```
COUNTA(value)
```

**Example**

```
COUNTA(A1)
```

## COUNTIF

Counts the number of cells that contain values that meet a given criteria. This function takes two arguments:

* `cell_range` – The range the `criteria` argument is applied to
* `criteria` – The condition applied to the specified `cell_range`. **Note**: Criteria arguments are not case sensitive.

```
COUNTIF(cell_range, criteria)
```

**Example**

```
COUNTIF(A2:A5, A1 >= 2)
```

**Limitations**

* `string` data types are not supported for `COUNTIF`
* Only works with conditional counts with a single criterion. To use multiple criteria, use [`COUNTIFS`](#countifs).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093480?hl=en).

## COUNTIFS

Counts the number of cells that contain values that meet given criteria.

* `cell_range` – The range the `criteria` argument is applied to
* `criteria` – The condition - which can include multiple arguments - applied to the specified `cell_range`. **Note**: Criteria arguments are not case sensitive.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3256550?hl=en).

```
COUNTIFS(cell_range, criteria1, [criteria2-optional])
```

**Example**

```
COUNTIFS(A1:A5, A1 > 2, B3:B10, B1 > A1)
```

**Limitations**

`string` data types are not supported for `COUNTIF`

## COVAR

Returns covariance, the average of the products of deviations. Equivalent to `COVAR.S`.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093993?hl=en\&sjid=10665742387146177313-NC).

```
COVAR(array1, array2)
```

**Example**

```
COVAR(A1:A10, B1:B10)
```

## COVARIANCE.P

Returns covariance, the average of the products of deviations of a population.

```
COVARIANCE.P(array1, array2)
```

**Example**

```
COVARIANCE.P(A1:A3, B1:B3)
```

## DEGREES

Converts radians to degrees. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093481?hl=en).

```
DEGREES(radians)
```

**Example**

```
DEGREES(1.047)
```

## EXP

Returns `e` raised to the power of a given number.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093411?hl=en).

```
EXP(number)
```

**Example**

```
EXP(2)
```

## FLOOR

Rounds a number down to the nearest integer multiple of specified significance.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093487?hl=en\&ref_topic=3105474\&sjid=5673436338131149083-NA).

```
FLOOR(value, <significance-optional>)
```

**Example**

```
FLOOR(A1, .05)
```

## INT

Rounds a number down to the nearest integer that is less than or equal to it. Alias for `FLOOR`.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093490?hl=en\&ref_topic=3105474\&sjid=5673436338131149083-NA).

```
INT(value)
```

**Example**

```
INT(8.9)
```

## INTERCEPT

Returns the intercept of the linear regression line through data points in Y and X data points. This function takes two arguments:

* `known_y_range` - Range of values representing the dependent (y) data
* `known_x_range` - Range of values representing the independent (x) data

**Note**: Any text of type `string` encountered in the value arguments will return null values.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093632?hl=en).

```
INTERCEPT(known_y_range, known_x_range)
```

**Example**

```
INTERCEPT(A1:A100, B1:B100)
```

## LARGE

Returns the `nth` largest value in a data set. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094008?hl=en\&ref_topic=3105600\&sjid=5673436338131149083-NA).

```
LARGE(array, k)
```

**Example**

```
LARGE(A1:A100, 4)
```

## LN

Returns the natural logarithm of a number. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093422?hl=en).

```
LN(number)
```

**Example**

```
LN(100)
```

## LOG

Returns the logarithm of a number to the specified base. If `base` isn't specified, the default of `10` will be used.

For more information, refer to the [Google Sheets LOG() function documentation](https://support.google.com/docs/answer/3093495?hl=en\&ref_topic=3105474\&sjid=5673436338131149083-NA).

```
LOG(number, [base-optional])
```

**Example**

```
LOG(100, 10)
```

## LOG10

Returns the base-10 logarithm of a number. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093423?sjid=5673436338131149083-NA).

```
LOG10(number)
```

**Example**

```
LOG10(100)
```

## MAX

Returns the largest number in a set. Only a single column or range may be provided as an argument.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094013?hl=en).

```
MAX(range)
```

**Example**

```
MAX(A1:A5)
```

## MAXIFS

Returns the maximum value in a range of cells, filtered by a list of criteria.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/7013817).

```
MAXIFS(max_range, criteria_range1, criteria1, [criteria_range2, criteria2], ... )
```

**Example**

```
MAXIFS(D4:E5, F4:G5, “>5”, F6:G7, “<10”)
```

## MEDIAN

Returns the median number in a set. Only a single column or range may be provided as an argument.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094025?sjid=5673436338131149083-NA).

```
MEDIAN(range)
```

**Example**

```
MEDIAN(B2:B8)
```

## MIN

Returns the smallest number in a set. Only a single column or range may be provided as an argument.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094017?sjid=5673436338131149083-NA).

```
MIN(range)
```

**Example**

```
MIN(C1:C10)
```

## MINIFS

Returns the minimum value in a range of cells, filtered by a list of criteria.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/7014063).

```text theme={null}
MINIFS(min_range, criteria_range1, criteria1, [criteria_range2, criteria2], ... )
```

**Example**

```text theme={null}
MINIFS(D4:E5, F4:G5, ">5", F6:G7, "<10")
```

## MOD

Returns the remainder from division. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093497?hl=en).

```
MOD(dividend, divisor)
```

**Example**

```
MOD(10, 3)
```

## MODE

Returns the most common number in a set. Only a single column or range may be provided as an argument.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094029?hl=en).

```
MODE(range)
```

**Example**

```
MODE(A1:A5)
```

## OMNI\_RANK

Returns the rank of a number in a list of numbers. Similar to [`RANK`](#rank), but the third argument indicates whether ranking is performed over rows or columns instead of specifying sort direction.

```text theme={null}
OMNI_RANK(number, range, [is_in_row_direction])
```

* `number` - The value to rank
* `range` - The range of values to rank against
* `is_in_row_direction` - **Optional**. If `TRUE`, ranks across rows. If `FALSE` or omitted, ranks across columns.

**Example**

```text theme={null}
OMNI_RANK(A1, A1:A10)
OMNI_RANK(A1, A1:E1, TRUE)
```

## RAND

Generates a random number between 0 and 1. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093438).

```
RAND()
```

**Example**

```
RAND()
```

## RANK

Returns the rank of a number in a list of numbers. The `direction` argument is optional, and if omitted will default to `descending`.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094098?hl=en).

```
RANK(number, ref, [direction])
```

**Example**

```
RANK(number, ref, [direction])
```

<Check>
  Use in combination with a [filter](/visualize-present/dashboards/filters) on this calculation to get a top `N` list. For example, `calc <= 5`
</Check>

## ROUND

Rounds a number to a specified number of digits. The `num_digits` argument is optional and will default to `0` if not provided.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093440?hl=en).

```
ROUND(number, [num_digits])
```

**Example**

```
ROUND(100.1234, 2)
```

## ROUNDDOWN

Rounds a number down, towards zero, to a specified number of digits. The `num_digits` argument is optional and will default to `0` if not provided.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093442).

```
ROUNDDOWN(number, [num_digits])
```

**Example**

```
ROUNDDOWN(100.1234, 2)
```

## ROUNDUP

Rounds a number up, away from zero, to a specified number of digits. The `num_digits` argument is optional and will default to `0` if not provided.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093443).

```
ROUNDUP(number, [num_digits])
```

**Example**

```
ROUNDUP(100.1234, 2)
```

## SLOPE

Returns the slope of the linear regression line through data points in Ys and Xs. This function accepts two arguments:

* `known_y_range` - The range representing the array or matrix of dependent data
* `known_x_range` - The range representing the array or matrix of independent data

**Note**: Any text of type `string` encountered in the value arguments will return null values.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094048?hl=en).

```
SLOPE(known_y_range, known_x_range)
```

**Example**

```
SLOPE(A1:A100, D1:D100)
```

## SMALL

Returns the nth smallest value in a data set. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094050).

```
SMALL(array, n)
```

**Example**

```
SMALL(A1:A100, 4)
```

## SQRT

Returns a positive square root. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093577?hl=en).

```
SQRT(number)
```

**Example**

```
SQRT(100)
```

## STDEV

Estimates the standard deviation based on a population of values. This function accepts a single argument:

* `value` - Can be a reference to a cell (`E1`), a range (`B4:B9`), or a column (`C:C`). **Note**: If the value contains references to text values, the calculation will be returned as `null`.

```
STDEV(value)
```

**Examples**

```
STDEV(A1)
STDEV(A1:A5)
```

**Limitations**

There is not full parity of functionality between the `STDEV` function in Google Sheets and Omni. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094054?hl=en).

## STDEV.P

Estimates the standard deviation based on an entire population. This function accepts a single argument:

* `value` - Can be a reference to a cell (`E1`), a range (`B4:B9`), or a column (`C:C`). **Note**: If the value contains references to text values, the calculation will be returned as `null`.

```
STDEV.P(value)
```

**Examples**

```
STDEV.P(A1)
STDEV.P(A1:A5)
```

**Limitations**

There is not full parity of functionality between the `STDEV.P` function in Google Sheets and Omni. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094054?hl=en).

## SUM

Adds all the numbers in a range of cells. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093669?hl=en).

```
SUM(range)
```

**Example**

```
SUM(A1:A5)
```

## SUMIF

Adds the cells specified by a given criteria. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093583?sjid=7647925112231655710-NA).

```
SUMIF(range, criteria, [sum_range-optional])
```

**Example**

```
SUMIF(B2:B8, B2 > 5, C2:C8)
```

**Limitations**

Text (`string`) criteria is not supported.

## SUMIFS

Adds the cells specified by multiple criteria. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3238496?hl=en).

```
SUMIFS(sum_range, criteria_range1, criteria1, [criteria_range2, criteria2], ... )
```

**Example**

```
SUMIFS(B2:B8, C2:C8, B2 > 5)
```

**Limitations**

Text (`string`) criteria is not supported.

## SUMPRODUCT

Returns the sum of the products of corresponding array components. For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094294?hl=en).

```
SUMPRODUCT(range1, range2, ...)
```

**Example**

```
SUMPRODUCT(A1:A5, B1:B5)
```

## TRUNC

Truncates a number to an integer by removing the decimal portion of a number. Alias for `FLOOR`.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093588?hl=en).

```
TRUNC(number)
```

**Example**

```
TRUNC(8.9)
```

## VALUE

Converts a text argument to a number. For more information, refer to the [Google Sheets VALUE() function documentation](https://support.google.com/docs/answer/3094220?hl=en).

```
VALUE(text)
```

**Example**

```
VALUE("123")
```

## VAR

Calculates the variance based on a sample of values. This function accepts a single argument, `value`. The `value` can be a number or a range of numbers.

```
VAR(value)
```

**Examples**

```
VAR(1)
VAR(A1)
VAR(A2:A25)
```

**Limitations**

There is not full parity of functionality between the `VAR` function in Google Sheets and Omni. For additional information, see the [Google Sheets documentation](https://support.google.com/docs/answer/3094063?hl=en).

## VAR.P

Returns the variance of a population. The value can be a number (`3`), a reference to a cell (`E1`), a range (`B4:B9`), or a column (`C:C`).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094113?sjid=7647925112231655710-NA).

```
VAR.P(value)
```

**Examples**

```
VAR.P(1)
VAR.P(A1)
VAR.P(A2:A25)
```


# Supported position functions
Source: https://docs.omni.co/analyze-explore/calculations/position

Reference for position functions like INDEX, MATCH, and OFFSET in Omni table calculations, similar to Google Sheets and Excel.

Omni supports position functions typically found in most spreadsheet applications such as Google Sheets. This reference details the position functions supported by Omni, which can be used to return data from specified points in a result table.

## INDEX

Returns the content of a cell, specified by row and column offset. This function accepts three arguments:

* `reference` - The range of cells from which values are returned
* `row` - **Optional**. The index of the row to be returned from within the `reference`. If set to `0`, values for the entire row will be returned.
* `column` - **Optional**. The index of the column to be returned from within the `reference`. If set to `0`, values for the entire column will be returned.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3098242).

```
INDEX(range, row, column)
```

**Example**

```
INDEX(A2:A25, 1, 2)
```

**Limitations**

There is not full parity of functionality between this function in Google Sheets and Omni. Refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3098242) for more information.

## MATCH

Returns the relative position of an item in a range that matches a specified value. **Note**: This function will not return the matched value.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093378).

```
MATCH(search_key, range)
```

**Example**

```
MATCH("Jane", A10:A25)
```

**Limitations**

There is not full parity of functionality between this function in Google Sheets and Omni. Refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093378) for more information.

## PIVOT

<Check>
  In a workbook results table, add a static `PIVOT()` function by entering `"="` and selecting `CMD + click` (or `Control + click`) on the reference cell.
</Check>

Returns a value from a specific pivot in the results table. This function accepts two arguments:

* `ref` - The reference to the range of data that includes the column from which to extract values. This only accepts a single column reference.
* `column_index` - The index number of the column within the referenced range from which to retrieve values.

```
PIVOT(ref, column_index)
```

**Example**

```
PIVOT(A2, 3)
```

## PIVOTINDEX

Returns the index of the current pivot. This function does not require any arguments.

The values returned for this function are based on the position the pivoted column is on the table. For example, `"Cancelled"` = index `1`, `"Complete"` = index `2`, etc.

```
PIVOTINDEX()
```

**Example**

```
PIVOTINDEX()
```

## PIVOTOFFSET

Returns a pivot value offset from the current pivot column. This function accepts the following arguments:

* `value_ref` - Reference to the starting cell or range
* `row_offset` - Number of rows to move. Positive = down, negative = up.
* `column_offset` - Number of columns to move. Positive = down, negative = up.
* `num_rows` - **Optional**. Number of rows in the returned range. Default is `1`.
* `num_cols` - **Optional**. Number of columns in the returned range. Default is `1`.

```
PIVOTOFFSET(value_ref, row_offset, column_offset, num_rows, num_cols)
```

**Example**

```
# Returns the value located 2 rows down and 1 column to the left from cell A1
PIVOTOFFSET(A1, 2, -1)
```

## PIVOTROW

Returns the values of a specified row in a pivot. Can be used to aggregate the values in a row, such as summing all values in the row.

```
PIVOTROW()
```

**Example**

```
PIVOTROW(A1)               # Returns values in row A1
SUM(PIVOTROW(A1))          # Sums all values in row A1
```

## SWITCH

Evaluates an expression against a list of values and returns the result corresponding to the first matching value. Values and results are provided in pairs, and the first matching pair is returned.

An optional `default` argument can be provided as the last argument, which will be used if no matches are found.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/7013690).

```
SWITCH(expression, case1, result1, [case2, result2, ...], [default] )
```

**Example**

```
SWITCH(A1, "apple", "fruit", "banana", "fruit", "carrot", "vegetable", "unknown")
```

The following table contains what the result would be for each `case` (ex: `apple`) argument:

| **Value**       | **Result** |
| :-------------- | :--------- |
| apple           | fruit      |
| banana          | fruit      |
| carrot          | vegetable  |
| Any other value | unknown    |

## ROW

Returns the current row number. Arguments are not supported.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093316?hl=en).

```
ROW()
```

**Example**

```
ROW()
```

## VLOOKUP

Searches for a value in a range and returns the value in the specified column.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3093318).

```
VLOOKUP(lookup_value, lookup_range, column_number)
```

**Example**

```
VLOOKUP(C1,'State Mottos'!A:A, 2)
```

## XLOOKUP

Searches for a value in a specified range in another query and returns the corresponding value from the range. If multiple rows match the lookup value, the minimum of the return value will be selected. Can be used to perform cross-query analysis on queries in the same workbook. For example, fact look ups or joining time series across workbook tabs. Note XLOOKUP does not work with pivoted data sets, with the exception of period-over-period results, where it will always select the current period.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/12405947).

```
XLOOKUP(lookup_value, <query_tab_name>!<lookup_range>, <query_tab_name>!<return_range>)
```

The `lookup_range` argument must reference a **full, single column**. For example, `'State Mottos'!A:A` but not `'State Mottos'!A:C` or `'State Mottos'!A1:A4`.

<Check>
  Use the **Copy XLookup Reference** option in the column header's menu options to quickly copy an `XLOOKUP` reference.
</Check>

**Example**

```
XLOOKUP(C1,'State Mottos'!A:A,'State Mottos'!B:B)
```

<Accordion title="View example details">
  This example has two tabs:

  * `State Mottos`, which contains `State` and `State Motto` columns
  * `Query`, which contains a few columns, including `State` and a column for the `XLOOKUP` calculation

  In this example, the calculation uses the `State` column in the `Query` tab as the lookup. It uses the values in the lookup column to search the `State` column in the `State Mottos` tab and find matches. When there's a match, the value in the `Mottos` column is returned.

  Check out the video for a step-by-step walkthrough:

  [xlookup-example](https://player.vimeo.com/video/944933124?badge=0\&autopause=0\&player_id=0\&app_id=58479)
</Accordion>


# Supported text functions
Source: https://docs.omni.co/analyze-explore/calculations/text

Omni supports functions typically found in most spreadsheet applications such as Google Sheets. This reference details the text functions supported by Omni.

## CHAR

Returns the character specified by a number. Char values follow the ASCII value mapping.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094123?hl=en).

```
CHAR(number)
```

**Example**

```
CHAR(10)
```

## CONCAT

Concatenates (combines) any number of strings into a single string.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094123?hl=en).

```
CONCAT(string1, string2, ...)
```

**Example**

```
CONCAT("Hello", " ", "World")       # Results in "Hello World"
```

## CONCATENATE

Concatenates (combines) any number of strings into a single string. Alias for [`CONCAT`](#concat).

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094123?hl=en).

```text theme={null}
CONCATENATE(string1, string2, ...)
```

**Example**

```text theme={null}
CONCATENATE("Hello", " ", "World")
```

## CLEAN

Returns text with the non-printable ASCII characters removed. Unicode characters that aren't in ASCII are not removed.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3267340?hl=en).

```
CLEAN(text)
```

**Example**

```
CLEAN("Hello"&CHAR(31))
```

## EXACT

Tests whether two text strings are exactly the same. Returns `TRUE` if the strings match, `FALSE` otherwise. This function is case-sensitive.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094073).

```text theme={null}
EXACT(string1, string2)
```

**Example**

```text theme={null}
EXACT("hello", "Hello")
```

## FIND

Returns the position of one string inside another.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094161?hl=en).

```
FIND(find_text, within_text)
```

**Example**

```
FIND("n", "Omni")
```

**Limitations**

Unlike Google Sheets or Excel, Omni's `FIND` does not accept a third argument for `start number/index`.

## LEFT

Returns the specified number of characters from the start of a text string.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094151?hl=en).

```
LEFT(text, [num_chars])
```

**Example**

```
LEFT("Hello", 3)
```

## LEN

Returns the length (number of characters) of a string.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094153?hl=en).

```
LEN(text)
```

**Example**

```
LEN("Hello")
```

## LOWER

Converts text to lowercase.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094157?hl=en).

```
LOWER(text)
```

**Example**

```
LOWER("Hello")
```

## MID

Returns a specific number of characters from a text string starting at the specified position.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094163?hl=en).

```
MID(text, start_num, num_chars)
```

**Example**

```
MID("Hello", 2, 3)
```

## PROPER

Capitalizes the first letter of each word in a text string.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094133?hl=en).

```
PROPER(text)
```

**Example**

```
PROPER("hello world")       # Results in "Hello World"
```

## REPLACE

Replaces characters in a string with new text.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3098247?hl=en).

```
REPLACE(old_text, start_num, num_chars, new_text)
```

**Example**

```
REPLACE("Hello", 2, 3, "i")
```

## RIGHT

Returns the specified number of characters from the end of a text string.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094087?hl=en).

```
RIGHT(text, [num_chars])
```

**Example**

```
RIGHT("Hello", 3)
```

## SEARCH

Finds one text value within another, ignoring case.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094154).

```
SEARCH(find_text, within_text)
```

**Example**

```
SEARCH("blobs", "The happiest place on earth is Blobs R Us")
```

**Limitations**

Unlike Google Sheets or Excel, Omni's `SEARCH` does not accept a third argument for `start number/index`.

## SUBSTITUTE

Substitutes new text for old text in a string.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094215).

```text theme={null}
SUBSTITUTE(text, old_text, new_text)
```

**Example**

```text theme={null}
SUBSTITUTE("Hello World", "World", "Omni")
```

Unlike Google Sheets or Excel, Omni's `SUBSTITUTE` does not accept a fourth argument for `instance_num`.

## TRIM

Removes leading, trailing, and repeated spaces from text, leaving only single spaces between words.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094140).

```text theme={null}
TRIM(text)
```

**Example**

```text theme={null}
TRIM("  Hello   World  ")
```

## T

Returns string arguments as text.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094138?hl=en).

```text theme={null}
T(value)
```

**Example**

```text theme={null}
T(A1)
T("2025-01-01")
```

## TEXT

Converts a number into text according to a specified format.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094139?hl=en).

```text theme={null}
TEXT(value, "format")
```

**Example**

```text theme={null}
TEXT(1.23,"$0.00")
TEXT(DATE(1969,7,20),"yyyy-MM")
```

## UPPER

Converts text to uppercase.

For more information, refer to the [Google Sheets documentation](https://support.google.com/docs/answer/3094219).

```text theme={null}
UPPER(text)
```

**Example**

```text theme={null}
UPPER("hello")
```


# Cross model tabs
Source: https://docs.omni.co/analyze-explore/cross-model-tabs

Query a different shared model from a tab in your workbook, and build dashboards that span multiple models and connections.

<Note>
  Cross model tabs are currently in beta and enabled on request. To try them, contact Omni support through your usual support channel, or email [support@omni.co](mailto:support@omni.co).
</Note>

A cross model tab is a workbook tab that queries a different [shared model](/modeling) than the rest of the workbook. Add one when the answer you need lives in another model — often on another database connection — and you want it alongside the work you're already doing.

Because each tab carries its own model, a single dashboard can present tiles from several models and connections at once.

## Requirements

To create a cross model tab, you'll need:

* Cross model tabs enabled for your organization
* Permission to edit the workbook
* **Restricted Querier**, **Querier**, **Modeler**, or **Connection Admin** [permissions](/administration/users/permissions) on the connection of the model you want to query

## Create a cross model tab

How you create a cross model tab depends on where you're starting from:

* **Starting a new query?** [Switch model from a new workbook tab](#switch-model-from-a-new-workbook-tab) or [add a new tab from the Edit menu](#add-a-new-tab-from-the-edit-menu). Both open the same list of models, grouped by connection when more than one is available.
* **The query already exists in another workbook?** [Import that tab](#import-a-tab-from-a-workbook-on-another-model) instead of rebuilding it.

Whichever way you create it, once a tab is pointed at another model the field browser shows a **Cross model** label naming that model, and the starting points, topics, views, and fields all come from it.

### Switch model from a new workbook tab

<Steps>
  <Step>
    Click **+** to add a tab.
  </Step>

  <Step>
    Click **Switch model**, then select the model you want to query.
  </Step>

  <Step>
    Choose a starting point — a topic or view from that model — the same way you would on any new tab.
  </Step>
</Steps>

While the tab is still empty, **Switch model** stays available. Use it to try a different model, or to return the tab to your workbook's own model by selecting the entry marked **(default)**. Choosing a starting point makes the tab a cross model tab, and **Switch model** no longer applies.

### Add a new tab from the Edit menu

When you're already working in a tab and want data from another model alongside it, add a cross model tab without leaving what you're doing.

<Steps>
  <Step>
    In your workbook, click **Edit > New cross model tab**.
  </Step>

  <Step>
    Select the model you want to query. Omni adds a new tab pointed at that model.
  </Step>

  <Step>
    Choose a starting point from that model.
  </Step>
</Steps>

### Import a tab from a workbook on another model

If the query you want already exists in a workbook on another model, you can import the tab into your current workbook.

You can import a tab when:

* It's a point-and-click query tab. SQL, spreadsheet, and blank table tabs can't be imported.
* It doesn't reference other tabs in its workbook, such as a filter by another tab's query.
* Its source workbook has no workbook model changes. Promote those changes to the shared model, or remove them, and try again.

A tab that is already a cross model tab imports as-is, and stays pointed at the model it queries.

Follow the steps in [Copy a tab to an existing workbook](/analyze-explore/workbook-basics#copy-a-tab-to-an-existing-workbook) to import the tab into your current workbook. When prompted, confirm that the tab queries a different model by clicking **Import**.

## Work in a cross model tab

A cross model tab behaves like any other query tab. You can:

* Build queries point-and-click, run them, and visualize the results
* Save the tab to a dashboard alongside tiles from your workbook's own model
* Duplicate, rename, and reorder the tab
* Create a linked tab from it
* Preview a view from the model it queries
* Ask the [workbook agent](/ai/queries) questions — it answers from the model the tab queries

Cross model tabs support point-and-click queries. SQL, blank table, and spreadsheet tabs use your workbook's own model, so create those on a regular tab.

## Add fields

You can create fields on a cross model tab:

* [Custom fields](/analyze-explore/custom-fields) and [calculations](/analyze-explore/calculations)
* Bins, groups, and level of detail calculations
* A duplicate of an existing field

These land in the tab as **Tab-only fields**, and you can edit them in place.

The fields that come from the model itself stay as that model defines them. Select **View field definition** on any of them to see how it's built, or **Go to definition** to open it in that model's IDE, where it can be edited and shared with everyone using it.

## Use cross model tiles on a dashboard

Save the workbook as usual. Each tab becomes a dashboard tile, regardless of which model it queries.

### Filters

A dashboard filter applies to a cross model tile once you map it. Open the filter's settings and choose the field on that tile to map to — see [mapping filters to tiles](/visualize-present/dashboards/filters#mapping). Explicit mapping keeps a filter built for one model from landing on a field it wasn't meant for.

### Chat with Content

[Chat with Content](/ai/dashboard-assistant) works across a mixed dashboard, querying each tile against that tile's own model.

### Scheduled deliveries and downloads

Deliveries and downloads include cross model tiles. Each tile is checked against its own model for the person the delivery runs as, so a delivery sends the tiles that person can query.

## Preview branch changes from another model

A cross model tab follows your own branch on the model it queries, so you can preview in-progress changes to that model from inside your workbook. The branch picker follows whichever tab you have open, and switching branches there leaves your workbook's own branch untouched.

Your branch selection is part of your session rather than part of the saved document. Two people opening the same dashboard see it through their own branch selections, so publish model changes to the shared model when everyone should see the same result. See [Branch Mode](/content/develop/branch-mode).

## Limitations

* **Embedded Omni.** Cross model tabs aren't supported in embedded workbooks, which continue to use a single model.
* **Cross model analysis.** Filtering one tab by another tab's query and [`XLOOKUP`](/analyze-explore/calculations/position#xlookup) aren't available on a cross model tab.
* **Promoting fields.** Fields you add stay in the tab. To share a field with other users, add it in that model's IDE.

<Tip>
  Tell us which of these matters most for your use case — through your usual support channel, or at [support@omni.co](mailto:support@omni.co). That feedback shapes what we build next.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="A model you expect isn't in the list">
    The list shows models you can build workbooks on, minus the one your workbook already uses. If a model is missing, ask your admin for access to it — see [permissions](/administration/users/permissions).
  </Accordion>

  <Accordion title="A tile shows an access error on a dashboard">
    Access is checked per tile against the model that tile queries. Someone viewing the dashboard needs access to every model on it to see every tile; the tiles they can access still load.
  </Accordion>

  <Accordion title="A tile is empty in a delivered dashboard">
    Access is checked per tile for the person the delivery runs as. If that person can't query one of the models, the rest of the dashboard still delivers.
  </Accordion>

  <Accordion title="A filter isn't affecting a cross model tile">
    Map the filter to a field on that tile. See [mapping filters to tiles](/visualize-present/dashboards/filters#mapping).
  </Accordion>

  <Accordion title="The model list looks out of date">
    The list is loaded once per session. Refresh the page after your model access changes.
  </Accordion>
</AccordionGroup>

## Next steps

* Build queries with [point-and-click](/analyze-explore/point-click-queries) or [topics](/analyze-explore/queries/topics)
* [Map dashboard filters](/visualize-present/dashboards/filters) to your cross model tiles
* Preview model changes with [Branch Mode](/content/develop/branch-mode)


# Binning and grouping custom fields
Source: https://docs.omni.co/analyze-explore/custom-fields/bin-group

Bin and group custom fields with Omni's handy custom calculation accelerators.

Omni offers some accelerators for common custom calculations. To bin or group strings or values, select "Group" from the field picker menu. String values can be grouped into grouplets, including a left over bucket for remaining values:

<img alt="" />

Numbers can be binned using a comma delimited list of values. Omni will auto-generate bins based upon the max value and a proportional split, but the boundaries can also be applied by hand:

<img alt="" />

As with other custom fields, explicit names or views can be applied alongside descriptions.

## Binning and regrouping aggregates

A common workflow is looking at a distribution and then trying to understand patterns in the aggregation - percent of users by lifetime orders; distribution of brands by count of SKUs, distribution of sessions or activities by user.

For these analyses we can use saved views and binning to share distribution of aggregates. We got through the following multi-stage analysis to do this with UI, and we'll share an alternative in SQL.

### Setup

1. Build baseline query where we want to analyze distribution. Here we'll look at lifetime orders per user:

<img alt="" />

2. Save a [query view](/analyze-explore/saved-views). Note Omni will strip the limit from the query view in order to retain the full data set.
3. Navigate to All Views & Fields to find our new table
4. Bin our aggregate (per section above)
5. Query and visualize:

<img alt="" />

<img alt="" />

As alternative path involves simply wrapping our first query in SQL, and inserting our own case statements. This is quicker, but will be more rigid if we need to adjust the underlying query. It is also a very simple approach to single-level re-aggregation (ie. wrap a sub-query in parentheses and count the number of rows).

<img alt="" />

<img alt="" />


# Creating filtered measures from query results
Source: https://docs.omni.co/analyze-explore/custom-fields/filtered-measures

Create a custom field that selectively applies a filter to a measure in a query.

To apply a filter to one but not all measures in a given query, you can create a filtered measure directly from the workbook. There are three different ways to do this:

## Adding a filter to a new measure

You can create a new measure by picking a quick aggregation from an existing dimension (e.g. sum, average), or by duplicating an existing measure. When you go to edit the new measure, you will have the option to add filters.

The gif below shows duplicating a measure and adding a filter:

<img alt="gif showing how to duplicate a measure and add a filter" />

<Note>
  If the measure was created from custom SQL or a calculated field, the filter created in the UI will not populate.
</Note>

## Creating the measure from a pivot

Filtered measures can be created directly from pivots. Right clicking on the measure underneath a given pivot value and select **Create filtered measure**. This is a fast way to prototype and build filtered measures from existing fields, as the following gif shows:

<img alt="gif showing how to duplicate a measure and add a filter" />

## Flattening a pivot

If you have a pivoted results table and want to create multiple filtered measures, you can flatten the pivot via the pivot header menu. If you need to turn many of your pivot columns into filtered measure, this is a great way to do it in a single swoop.

<img alt="gif showing how to flatten an entire pivot into multiple filtered measures" />

Note that when you flatten the pivot you have some options:

* **Add an "other" bucket**: Checking this box allows you to create a filtered measure for any values of the pivoted dimension *not* flattened. This could include values that have been filtered out of the current query or values that may appear for that dimension yet.
* **Only create measures for the first N pivot columns**: If you've checked to create an "other" bucket, you can also choose to specify how many of the columns are flattened into filtered measures. The other columns will be grouped into the "other" bucket.

Initially you will see the flattened pivot measures in a section called "Query View" in the field picker available only in the tab you create them in. If you want to use them across the workbook, you can add them to the workbook from the field picker field menu under Model. If you want to remove all the flattened pivot measures from the field picker you can use the keyboard shortcut (Mac) command+option+shift+k or (PC) ctrl+option+shift+k


# Creating custom fields in Omni workbooks
Source: https://docs.omni.co/analyze-explore/custom-fields/index

Create new, reusable ad-hoc dimensions and measures with your own custom logic and calculations.

Most fields in the field picker come directly from your database schema. However, by using custom fields you can also create new ad-hoc dimensions and measures to define custom logic and calculations that can be reused.

Custom fields can use both SQL and modeled objects. Only users with **Querier** permissions and higher will be able to make SQL references in calculations (though any user that can touch the workbook page can create new fields from modeled objects). See more on permissions [here](/administration/users/permissions).

## Examples

**Custom Dimension**

```
CASE
    WHEN ${users.state} = 'California' THEN 'West'
    WHEN ${users.state} = 'New York' THEN 'East'
    ELSE 'Other'
END
```

```
concat(${users.first_name}, ' ', ${users.last_name})
```

**Custom Measure**

```
count(distinct ${users.full_name})
```

Note how this custom measure also references the previously created full\_name custom field. That logic is 'chained' together when expressed in the generated SQL.

<img alt="" />

## Creating a Custom Field

There are a few ways to create a new Custom Field. Once saved, the Custom Field will become available in the field picker.

1. Fields can be created from field picker, using the "+ Add Field" menu at the bottom of the field list. Field can also be adjusted by right-clicking on any existing field and selecting 'Edit.'

<img alt="" />

2. Right click on any existing dimension and choose an aggregation (e.g. count distinct, sum, average, min, max). This will automatically create a new custom measure that appears in the field picker.

<img alt="" />

3. Fields can be added from parsed SQL. When queries are run in SQL, Omni will extract valid snippets into associated potential dimensions. They'll be shown in a special section at the top of the field picker called **Tab-only fields**. To add these fields to the workbook, right-click a field and select **Add to Workbook**:

<img alt="" />

## Duration fields

Duration fields calculate the time difference between two timestamp fields in configurable intervals (days, hours, weeks, etc.). You can create duration fields directly from the workbook UI without writing YAML in the model IDE.

To create a duration field:

1. In the field picker, right-click on a timestamp field you want to use as the **start** timestamp.

2. Select **Duration** from the context menu.

3. In the duration configuration panel, select an **end** timestamp field.

4. Toggle the intervals you want to generate, such as days, hours, weeks, or months.

5. Click **Save** to create the field.

The new duration field will appear in the field picker with a sub-field for each selected interval.

To remove a specific interval from an existing duration field, right-click on the interval sub-field and select **Delete**. This removes only the selected interval from the parent duration field rather than deleting the entire field.

<Note>
  Duration fields can also be defined in the model IDE using YAML. Refer to the [duration parameter reference](/modeling/dimensions/parameters/duration) for syntax and examples.
</Note>

## Custom Field Syntax

You can think of a Custom Field as a snippet of SQL logic that gets injected into the generated SQL query whenever the field is brought into the analysis plane.

To create one, simply write a snippet of SQL inside the editor.

Optionally, you can leverage the substitution operator, `${view.field}`, to reference other fields. The substitution operator makes code more reusable and modular, enabling you to reference other objects. It's particularly beneficial when you want to chain together logic. For example, if you previously created a different custom field, you can reference it without having to repeat the calculation again. And, if in the future you change the definition for that field, the change will propagate to everything else that relies on it.

When you add the custom field to a query, you can see the logic applied in the SQL block.

<img alt="" />


# Ranking values with Top N fields
Source: https://docs.omni.co/analyze-explore/custom-fields/top-n

Create a custom field that ranks a text dimension by a measure, keeping only the top or bottom N values.

Top N fields rank the values of a text dimension by a measure and keep only the top (or bottom) N of them, grouping everything else into a remaining bucket. Use them for questions like "what are my 10 best-selling products" or "which 5 regions have the lowest churn."

<Note>
  Top N is a ranking mode of Omni's [Custom Groups](/analyze-explore/custom-fields/bin-group) feature. That page covers how the "remaining values" bucket works in more depth.
</Note>

## Creating a Top N field

Top N is available for **text-type dimensions only**. Numeric dimensions use [Bin](/analyze-explore/custom-fields/bin-group) instead, and timestamp dimensions use [Duration](/analyze-explore/custom-fields#duration-fields).

In the field picker, find the text field you want to rank, select the three-dot menu, and choose **Top N**.

<Frame>
  <img alt="Selecting Top N from a text field's context menu in the field picker" />
</Frame>

This opens the same configurator used for Custom Groups, pre-set to **Top N values** mode.

<Frame>
  <img alt="The Top N configurator, showing top/bottom, number of values, and by-measure options" />
</Frame>

Configure:

* **Top or bottom**: rank by the highest values (**Top**) or lowest values (**Bottom**).
* **Number of values**: how many values (N) to keep.
* **By measure**: the single measure to rank by. Top N ranks by exactly one measure at a time.
* **Filters**: optional field-level filters applied before ranking (e.g. only rank based on this year's orders). Period-over-period and "filter by query" aren't supported here.
* **Group remaining values**: on by default — every value outside the top/bottom N is grouped into one row, labeled "Other" (rename it under **Group remaining values as**). Turn this off to exclude those values from the result entirely instead of grouping them.

Once saved, the field behaves like any other dimension — add it to a query, chart it, filter by it, and so on.

<Frame>
  <img alt="A query result showing five ranked cities and an &#x22;Other&#x22; row for everything else" />
</Frame>

## Limitations

<Warning>
  If two values tie for the last spot in the ranking, Omni doesn't guarantee which one is included — ties don't have a deterministic secondary sort. If exact tie-breaking matters, add a secondary field to your query to disambiguate.
</Warning>

* Top N ranks by exactly one measure. To rank by a combination of measures, create a custom measure that combines them first, then rank by that.
* A Top N field can't have its own custom sort order, since it's already sorted by its ranking measure. Other fields can still sort by referencing a Top N field.
* Top N fields can't be created from another Top N field.

## Letting viewers change N on a dashboard

Map a [Top N limit control](/visualize-present/dashboards/controls#control-types) to the field so dashboard viewers can adjust N without editing the underlying query.


# Uploading CSVs with data input tables
Source: https://docs.omni.co/analyze-explore/data-input-csvs

Upload CSV or Excel files to Omni as data input tables for enrichment and ad-hoc analysis without modifying your data pipelines.

Sometimes you may want to utilize data in an analysis that isn't already in a [database](/connect-data/setup) schema, whether it's for data enrichment or an initial exploration. Creating a data input table allows you to add data to Omni, whether by manually entering data or uploading a CSV or XLSX, without needing to touch your data pipelines.

## Requirements

To add data input tables, you'll need:

* A configured Omni [connection](/connect-data/setup) that supports upload tables
* **Restricted Querier**, **Querier**, or **Connection Admin** permissions
* **To enable the [Upload data ability](/share#controlling-document-interactivity)**. This setting must be enabled for the [organization](/administration/content-permissions) and, if a document is shared with others, also in the [document's settings](/share#controlling-document-interactivity).

<Tip>
  We recommend creating a schema in your database where Omni can write the CSV files. See the [setup guide for your database](/connect-data/setup) for more instructions on write backs.
</Tip>

## Limitations

Currently, data input tables:

* **Must be added in a workbook**
* **Are limited to 500,000 rows**
* **Can't be used in joins unless the table is pushed to a database.** Setting the connection's **Schema for table upload** property enables this functionality. Refer to the [setup guide for your database](/connect-data/setup) for more information.
* **Data types for each column can't be explicitly selected in Omni.** column type will be inferred based on the values in the upload. Generally it is best to correct this in the source rather than casting/fixing in the model layer after saving. For dates especially getting the format right in the upload will save you time.

## Adding a data input table to a workbook

Data input tables can be added in the workbook of any document.

In a workbook, navigate to **Edit > New blank table**. A new tab with a blank data input table will display.

<img alt="" />

To get data into the table, you can manually enter it or upload a CSV or XLSX:

<AccordionGroup>
  <Accordion title="Manually enter data" icon="hand">
    <Steps>
      <Step>
        In the first row, add the names of the columns. The first row must be a header row to allow Omni to generate a schema for the table.
      </Step>

      <Step>
        Enter data into the cells. To add line breaks, use `Ctrl + Enter`.
      </Step>

      <Step>
        To add rows or columns, use the **Add Row** and **Add Column** options.
      </Step>

      <Step>
        When you're finished editing the table, click **Save CSV** near the top right corner of the page.
      </Step>

      <Step>
        Enter a name for the table and click **Save**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Upload a CSV or XLSX file" icon="upload">
    <Note>
      To upload a CSV or XLSX:

      * The first row must be a header row
      * The file can't exceed 500,000 rows

      Additionally, if the XLSX file contains multiple tabs, only the first sheet will be uploaded.
    </Note>

    <Steps>
      <Step>
        Click the **Upload CSV** option near the top right corner of the page.
      </Step>

      <Step>
        Browse for or drag the file you want to upload into the upload dialog.
      </Step>

      <Step>
        If you have [**Querier**, **Modeler**, or **Connection Admin** permissions](/administration/users/permissions), you'll see a **Create topic** checkbox. Checking this box will create a topic from the uploaded file. If you're a **Restricted Querier**, a topic will automatically be created from the file.
      </Step>

      <Step>
        Click **Upload** to upload the file.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

Once there's data in the table, click **Query CSV** to create a query using the data. The table will also become available in the field picker in other queries.

## Querying and joining data input tables

Data input tables can be queried like any other table, including using the field picker, [SQL editor](/analyze-explore/sql), or working with [calculations and formulas](/analyze-explore/calculations).

<img alt="" />

**Note**: To make the data available outside of the workbook, you'll need to [promote it to the shared model](#modeling-and-promoting-data-input-tables).

How you join data from a data input table to other data depends on whether table uploads are enabled for the database connection used by the workbook:

<details>
  <summary>
    <strong>Traditional joins (Requires database uploads)</strong>
  </summary>

  If database uploads are enabled for the connection, you can use [traditional joins](/analyze-explore/point-click-queries#joining-tables) - whether via the UI or in SQL - to create relationships between data input tables and other data.
</details>

<details>
  <summary>
    <strong>Workbook tab joins with XLOOKUP</strong>
  </summary>

  If database uploads aren't enabled for the connection, you won't be able to use traditional joins with data input tables. You can, however, use [`XLOOKUP`](/analyze-explore/calculations/position#xlookup) to perform cross-tab analysis in a workbook:

  ```
  =XLOOKUP(lookup_value, <query_tab_name>!<lookup_range>, <query_tab_name>!<return_range>)
  ```

  For example, you have a workbook with two tabs: `Sales`, which is backed by a topic, and `Products Upload`, which is a query on a data input table. You want to include the names of products purchased in an order alongside other sales data. To join the data in the `Products Upload` tab to your sales, you could use an `XLOOKUP` formula like the following to create a new calculation in the `Sales` tab:

  ```
  =XLOOKUP(A1,'Products Upload'!B:B, 'Products Upload'!C:C)
  ```
</details>

## Modeling and promoting data input tables

When a data input table is added to a workbook, a few things will happen in the [workbook model](/modeling/develop/promotion#reviewing-and-promoting-workbook-changes). To make the changes available outside of the workbook, [they must be promoted to the shared model](/modeling/develop/promotion).

* **A [view](/modeling/views) representing the data input table will be created**. These views can be identified by the presence of an `uploaded_table_name` parameter:

  ```yaml title="products.view" theme={null}
  # Reference this view as products
  uploaded_table_name: products.csv::1a3497f5-cba8-47c0-bab9-b2df84d1b141
  ```

* **A [topic](/modeling/topics) based on the view representing the data input table will be created if**:
  * **Create topic** was selected while uploading a CSV or XLSX, or
  * A Restricted Querier performed the upload

<Note>
  Topics created from CSV uploads automatically receive empty `required_access_grants`, meaning they don't inherit model-level `default_topic_required_access_grants` and are accessible to all users by default.
</Note>

Views and topics created from data input tables can be modeled like any other view or topic. However, if the data input table hasn't been pushed to the connection's database, attempting to use the data input table in a join in the IDE will result in the following content validation error:

```bash theme={null}
View "<view_name>" references an uploaded table. Uploaded tables cannot be used in joins.
```

If data from a data input table hasn't been pushed to a database, only `XLOOKUP` can be used to perform joins to other tabs in a workbook. Refer to the [Querying & joining data](#querying-and-joining-data-input-tables) section for more information and examples.

## Updating data input table data

When making updates to a data input table, keep the following in mind:

* **Changes must be promoted to the shared model to be accessible outside the workbook**. This is necessary even if the table was previously promoted to the shared model.
* **If table uploads (writebacks) are enabled for the connection**, Omni will create a new table in the database each time the table is saved. You can manage previous versions of the table in the [**Upload management** page](#managing-previous-table-versions).

To update a data input table's data:

1. In a workbook, locate the table in a query tab.

2. Click the options menu next to the table's name, then **Edit Table**:

   <img alt="" />

3. The data input table will open in a new tab where you can edit the data as needed.

4. Click **Save changes** when finished.

Upon a successful save, the updated table will immediately become available in the workbook. Omni will also log a new version of the table in the [**Upload management** page](#managing-previous-table-versions).

## Managing previous table versions

Every time you [create](#adding-a-data-input-table-to-a-workbook) or [update](#updating-data-input-table-data) a data input table, Omni adds an entry in the **Upload management** page. Each item in the list represents a version of the table. Entries are sorted by the time they were created, beginning with the most recent.

Navigate to **Settings > Uploads** to access this page:

<img alt="" />

### Querying previous table versions

To create a query using a specific version of a table, click the **Explore** button next to the table version. This will open a new workbook that uses the specified version of the table.

**Note**: If you promote the changes from an older version of the table, it will overwrite the data currently in the shared model.

### Deleting table versions

<Warning>
  **Deleting a table version can't be undone**. Before continuing, note that:

  * The version of the table will be permanently deleted from your Omni instance. If table uploads (writebacks) are enabled, the version of the table will also be deleted from the database.
  * Queries, views, and topics built on the version will result in an error after the deletion
</Warning>

The **Upload management** page can be used to delete previous versions of a data input table. **Note**: Table versions are listed in the order they were created, meaning that the most recent version of a table will be higher in the list.

1. Navigate to **Settings > Uploads**.
2. Locate the version you want to remove and click **Delete**.

After the deletion is complete, you'll also need to:

* Remove views and topics built on the version from the model
* Update or remove queries using the version


# Analyze & build in Omni
Source: https://docs.omni.co/analyze-explore/index

Explore data, build queries, create calculations, and optimize performance in Omni workbooks.

Omni's analysis tools are centered around [workbooks](/analyze-explore/workbook-basics) — flexible, multi-tab environments where you can query data, build calculations, and prepare results for visualization. This section covers everything you need to build analyses in Omni.

## Query data

Omni supports multiple paths for [querying your data](/analyze-explore/querying), from conversational AI to point-and-click to writing SQL directly. Every query is routed through the [semantic model](/modeling), so results respect your organization's definitions and permissions regardless of how you build them.

## Add data

Not all data lives in your data warehouse. Omni gives you two ways to bring in additional data:

* **[CSV & Excel uploads](/analyze-explore/data-input-csvs)** - Upload a file as a standalone table to use alongside your database queries, useful for data that hasn't made it into your warehouse yet or analyzing one-off spreadsheets.
* **[Input columns](/analyze-explore/input-columns)** <Badge>BETA</Badge> - Add editable columns directly to a query result to annotate rows inline, such as adding enrichments, scores, or notes.

## Spreadsheets

[Spreadsheet tabs](/analyze-explore/spreadsheet-tabs) bring an Excel-like environment into your workbooks. Connect spreadsheet tabs to your queries and use familiar formulas to format, reshape, and build on top of live data — without exporting or manually refreshing.

## Calculations and custom fields

Extend your queries with ad hoc logic:

* **[Table calculations](/analyze-explore/calculations)** — Use Excel-style functions to create post-query metrics like percent of total, running totals, and period-over-period comparisons.
* **[Custom fields](/analyze-explore/custom-fields)** — Create reusable dimensions and measures with custom SQL or modeled objects, including [bins and groups](/analyze-explore/custom-fields/bin-group) and [filtered measures](/analyze-explore/custom-fields/filtered-measures).

## Debug and optimize

* **[Workbook inspector](/analyze-explore/workbook-inspector)** — View the structure of your queries, copy them for use in the model, and debug issues by comparing query configuration to generated SQL.
* **[Performance optimization](/analyze-explore/performance/caching)** — Learn how Omni's caching layers and [aggregate awareness](/analyze-explore/performance/aggregate-awareness) reduce warehouse load and speed up your analyses.


# Input columns
Source: https://docs.omni.co/analyze-explore/input-columns

Add editable columns directly to query results to annotate and enrich data inline without modifying your data pipelines.

Input columns let you add editable columns directly to a query result. Instead of building a separate table or directly modifying your database, you can annotate rows inline — adding values that attach to specific rows and persist across query refreshes.

Input columns are a good fit when you need to layer human judgment or operational context on top of data that already lives in your database. For example:

* **Triage and review workflows** — Flag records as reviewed, escalated, or resolved directly in the query result (e.g., a table of support tickets or open orders)
* **Qualitative scoring** — Assign priority scores, confidence ratings, or categorical labels to rows (e.g., rating leads by quality after reviewing enriched account data)
* **Collaborative annotation** — Let a team of analysts or operators add notes to shared dashboards without needing to touch the database
* **Exception tracking** — Mark anomalies or outliers with a reason code as part of a data review process
* **Forecast overrides** — Layer human adjustments on top of forecasts (e.g., a sales manager overriding a rep's pipeline number, or ops adjusting an inventory projection

## Common questions

<AccordionGroup>
  <Accordion title="Are input columns written to my database?">
    Yes. Input columns use the same writeback mechanism as [data input tables](/analyze-explore/data-input-csvs): values are written as a table in your connection's scratch schema and joined back to your query results automatically.
  </Accordion>

  <Accordion title="How are input columns associated with a record?">
    When you add an input column to a query, you choose one or more [**key columns**](#key-columns) — dimensions from the query that uniquely identify each row, like a customer ID or order number. Omni uses these keys to match your entered values to the right rows, even as the underlying query data changes over time.

    **Note**: The column's **Key columns** setting can't be changed after the input column is created.
  </Accordion>

  <Accordion title="What data types are supported for input columns?">
    Input columns support the following data types:

    | Data type            | Notes                                                                                                                                                                             |
    | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Text                 |                                                                                                                                                                                   |
    | Number               | Only accepts numeric values and deicmals (ex: `10000`, `3.33`)                                                                                                                    |
    | True/false (boolean) | A value of `true`, `yes`, `y`, or `1` sets the column to `true`;  `false`, `no`, `n`, `0` sets it to `false`. <br /><br />Values display as literal `true` or `false` once saved. |

    **Note**: The column's **Data type** setting can't be changed after the input column is created.
  </Accordion>

  <Accordion title="Can I edit input columns on dashboards?">
    Yes. When creating the input column, set the [**Edit mode**](#edit-modes) to **Published**. End users will then be able to enter values on a live dashboard.
  </Accordion>

  <Accordion title="How do input columns interact with row-level security?">
    When a topic has access filters (row-level security), Omni automatically enforces that the filtered fields must be included in the input column's mapping key. This prevents data leakage across users or tenants.

    Fields from access filters are pre-selected in the input column dialog and cannot be deselected.

    If an access filter field is hidden or unavailable in the topic, input column creation will be blocked until the field is surfaced.
  </Accordion>
</AccordionGroup>

## Requirements

To use input columns, you'll need:

* A **scratch schema configured** on the connection. Unlike data input tables, input columns require database writebacks to be enabled. Refer to the [setup guide for your database](/connect-data/setup) for instructions.
* **Restricted Querier**, **Querier**, or **Connection Admin** permissions
* **To have the [Upload data ability](/share#controlling-document-interactivity) enabled.** This must be enabled for the [organization](/administration/content-permissions) and, if the document is shared with others, also in the [document's settings](/share#controlling-document-interactivity).

## Adding an input column

Input columns are added from within a query result in a workbook or dashboard.

<Steps>
  <Step>
    Open a query result in a workbook or dashboard.
  </Step>

  <Step>
    Click the <Icon icon="pencil" /> icon in the column header, then select **Add input column**.
  </Step>

  <Step>
    In the dialog, configure the input column:

    * **Column name** — A label for the column. Alphanumeric characters only.
    * **Data type** — Choose **Text**, **Number**, or **True/false**.
    * **Edit mode** — Choose when the column should be editable. Refer to [Edit modes](#edit-modes) for more information.
    * **Key columns** — Select one or more dimensions to use as the row identifier. Refer to [Choosing key columns](#key-columns) for more information.

      If the topic has [access filters](/modeling/topics/parameters/access-filters) configured, fields from those filters are automatically required in the mapping key. These fields are pre-selected and cannot be deselected.

    <Note>
      **Heads up!** Data types and key columns can't be changed after the column is created. To change them, you'll need to delete and then re-create the column.
    </Note>
  </Step>

  <Step>
    Click **Create**.
  </Step>
</Steps>

The input column will appear in the query result. To enter values, see [Editing values](#editing-values).

### Edit modes

When creating an input column, you choose an **edit mode** that controls when the column is editable:

| Mode          | Editable in         | Use case                                      |
| ------------- | ------------------- | --------------------------------------------- |
| **Draft**     | Draft documents     | Content creators annotate data while building |
| **Published** | Published documents | End users fill in values on a live dashboard  |

### Choosing key columns

Key columns are the dimensions Omni uses to match your input values to the right rows. When selecting key columns:

* **Choose columns that uniquely identify each row.** If the same combination of key values appears more than once, input values will apply to all matching rows.
* **Choose columns with stable values.** If a key value changes — for example, a product is renamed — previously entered values won't match the updated key.
* **Access filter fields are automatically included.** If the topic has [access filters](/modeling/topics/parameters/access-filters) configured, those fields are automatically required in the key and cannot be removed. This ensures input values are scoped to the correct user or tenant.

You can select multiple key columns to form a composite key. For example, if product IDs aren't unique across regions, combining `region` and `product_id` may be necessary to uniquely identify rows.

## Editing values

To edit the column's values:

<Steps>
  <Step>
    Click the <Icon icon="pencil" /> icon to unlock the column. The cells will become editable.
  </Step>

  <Step>
    Click a cell and type a value. Press **Enter** to move to the next row, or **Escape** to cancel the current edit.
  </Step>

  <Step>
    When you're done, click Save to save your changes.
  </Step>
</Steps>

Unsaved edits are shown as a preview until the column is saved. Values are written to the database's scratch schema when you re-save the column.

<Note>
  An input column is editable only when its key column(s) are present in the query. If you reuse the column in a query at a different grain, it becomes read-only in that query.
</Note>

## Editing an input column's configuration

<Note>
  Data types and key columns can't be changed after the input column is created. To change them, [delete the column](#delete-column) and then re-create it.
</Note>

To rename an input column or change its edit mode:

<Steps>
  <Step>
    Click the <Icon icon="ellipsis-vertical" /> icon in the input column's header.
  </Step>

  <Step>
    Select **Edit column**.
  </Step>

  <Step>
    Update the name or edit mode, then click **Save**.
  </Step>
</Steps>

## Deleting an input column

<Danger>
  Deleting an input column permanently removes the column and all values entered in it. **This action can't be undone.**
</Danger>

<Steps>
  <Step>
    Click the <Icon icon="ellipsis-vertical" /> icon in the input column's header.
  </Step>

  <Step>
    Select **Delete column**.
  </Step>

  <Step>
    When prompted, confirm the deletion.
  </Step>
</Steps>

## Limitations

Currently, input columns are scoped to the workbook and cannot be promoted to the shared model.


# Optimizing query performance with aggregate awareness
Source: https://docs.omni.co/analyze-explore/performance/aggregate-awareness

Optimize query performance by routing queries to pre-aggregated tables in your data warehouse.

Aggregate awareness lets you optimize query performance by routing queries to pre-aggregated tables in your data warehouse. End users can access data at different levels of granularity, as Omni will pick the most efficient table based on the query's structure.

## Requirements

To follow the steps in this guide, you'll need **Querier**, **Modeler**, or **Connection Admin** permissions.

## How it works

You build pre-aggregated (or rollup) tables in your preferred transformation tool, such as dbt, and register them with a [`materialized_query`](/modeling/views/parameters/materialized-query) parameter on the aggregate's view. This gives you full control over how the aggregation is defined and refreshed.

At query runtime, Omni inspects the requested fields and rewrites the SQL to use the aggregate table when it contains everything the query needs. Because the aggregate is smaller than the base table, the rewritten query runs faster and uses fewer warehouse resources. The rewrite is automatic, meaning end users don't need to choose which table to query.

Omni uses the aggregate:

* **For single-table queries** — All queried dimensions and measures are mapped in the aggregate's `materialized_query.fields`.
* **For joined queries within a topic** — All queried fields from the base view are mapped in the aggregate's `materialized_query.fields`, *and* the aggregate also includes the join keys to the other views. Omni then joins the aggregate to the dimension views instead of the base table.

If the aggregate is missing any required field, including a join key, Omni falls back to the base tables.

Omni can also roll up [sketch-based approximate aggregates](#using-sketch-based-approximate-aggregates), such as HyperLogLog distinct counts, from the grain stored in the aggregate table to the grain of the query.

## Setting up aggregate awareness

Once you've identified the query you'd like to optimize:

<Steps>
  <Step title="Build an aggregate or rollup table">
    Build an aggregate or rollup table within Omni or some other transformation layer such as dbt.

    If you do this outside of Omni and don't see your table, [refresh the schema](/modeling/develop/schema-refreshes) to have Omni build it.

    To demonstrate, let's say you have a table with the following definition and you want to optimize the performance of the daily aggregations:

    ```yaml order_items table wrap theme={null}
    dimensions:
      created_at: {}
      sale_price: {}
      user_id: {}

    measures:
      count:
        aggregate_type: count
      sale_price_sum:
        aggregate_type: sum
        sql: ${sale_price}
      user_id_count_distinct:
        aggregate_type: count_distinct
    ```

    In your transformation layer, you defined the following materialized table, which has pre-aggregated daily metrics:

    ```yaml Pre-aggregated table definition wrap theme={null}
    dimensions:
      date: {}
      total_sale_price: {}
      order_items_count: {}
      user_distinct_count: {}
    ```
  </Step>

  <Step title="Add a materialized_query parameter">
    In Omni's model IDE, add a [`materialized_query` parameter](/modeling/views/parameters/materialized-query) to the optimized view to enable Omni to match the aggregate table to the underlying base views:

    ```yaml Pre-aggregated table daily_sales wrap theme={null}
    materialized_query:
      fields:
        "order_items.created_at[date]": date
        order_items.sale_price_sum: total_sale_price
        order_items.count: order_items_count
        order_items.user_id_count_distinct: user_distinct_count
      base_view: order_items
    ```

    The `fields` parameter maps each field from the base view to the corresponding column name in the aggregate table. You can also use the [array format](/modeling/views/parameters/materialized-query#syntax), though the object format shown here is recommended for clarity.

    Time dimensions need a timeframe qualifier that matches the grain of the aggregate table, such as `created_at[date]` for a daily table. Quote the key, because the brackets are otherwise not valid YAML.

    <Tip>
      To apply aggregate awareness across joins in a topic, include the join keys to the other views in `fields`. See the [`materialized_query` reference](/modeling/views/parameters/materialized-query#examples) for an example.
    </Tip>
  </Step>

  <Step title="Verify the setup">
    Verify that aggregate awareness is working by inspecting the generated SQL using [Omni's SQL inspector](/analyze-explore/workbook-inspector). The inspector will show whether Omni is querying the aggregate table or the granular table.

    ```sql title="Query rewritten to use the aggregate table" wrap theme={null}
    -- Query rewritten to use materialized view "daily_sales".
    -- The original unoptimized SQL is commented-out below
    -- SELECT DATE_TRUNC('DAY', "created_at") AS "order_items.created_at[date]__raw",
    --     COALESCE(SUM("sale_price"), 0) AS "order_items.sale_price_sum",
    --     TO_CHAR(DATE_TRUNC('DAY', "created_at"), 'YYYY-MM-DD') AS "order_items.created_at[date]"
    -- FROM "order_items"
    -- GROUP BY 1
    -- ORDER BY 1 NULLS FIRST
    -- LIMIT 999

    SELECT 
        DATE_TRUNC('DAY', "date") AS "order_items.created_at[date]__raw",
        COALESCE(SUM(CAST("total_sale_price" AS DOUBLE PRECISION)), 0) AS "order_items.sale_price_sum",
        TO_CHAR(DATE_TRUNC('DAY', "date"), 'YYYY-MM-DD') AS "order_items.created_at[date]"
    FROM (  
      SELECT 
          date,
          total_sale_price,
          order_items_count,
          user_distinct_count
      FROM "daily_sales"
        ) AS "t"
    GROUP BY 1
    ORDER BY 1 NULLS FIRST
    LIMIT 999
    ```
  </Step>
</Steps>

## Using sketch-based approximate aggregates

Aggregate awareness also works with sketch-based approximate aggregates. A sketch is a compact binary summary of a column. Warehouses use sketches to calculate approximate results, such as distinct counts with HyperLogLog (HLL), approximate percentiles, and top-K values.

Sketches are additive, which is what makes them work with aggregate awareness. Omni can combine the daily sketches stored in an aggregate table into a weekly or monthly result, so queries at a coarser grain don't need the base table. This is the workaround for `count_distinct`, which can't be re-aggregated from pre-aggregated values.

These functions return estimates, not exact values. Use them where a small margin of error is an acceptable trade for faster queries.

### Supported sketch functions

Use a function from the **Sketch function** column in your sketch measure, and the matching **Estimate function** in your estimate measure. Omni applies the rollup function on its own when it combines sketches.

| Warehouse  | Sketch function                                               | Rollup function             | Estimate function            |
| ---------- | ------------------------------------------------------------- | --------------------------- | ---------------------------- |
| Snowflake  | `HLL_ACCUMULATE` or `HLL_COMBINE`                             | `HLL_COMBINE`               | `HLL_ESTIMATE`               |
| Snowflake  | `APPROX_PERCENTILE_ACCUMULATE` or `APPROX_PERCENTILE_COMBINE` | `APPROX_PERCENTILE_COMBINE` | `APPROX_PERCENTILE_ESTIMATE` |
| Snowflake  | `APPROX_TOP_K_ACCUMULATE` or `APPROX_TOP_K_COMBINE`           | `APPROX_TOP_K_COMBINE`      | `APPROX_TOP_K_ESTIMATE`      |
| Snowflake  | `MINHASH` or `MINHASH_COMBINE`                                | `MINHASH_COMBINE`           | `APPROXIMATE_SIMILARITY` \*  |
| BigQuery   | `HLL_COUNT.INIT` or `HLL_COUNT.MERGE_PARTIAL`                 | `HLL_COUNT.MERGE_PARTIAL`   | `HLL_COUNT.EXTRACT`          |
| Databricks | `HLL_SKETCH_AGG` or `HLL_UNION_AGG`                           | `HLL_UNION_AGG`             | `HLL_SKETCH_ESTIMATE`        |

\* `APPROXIMATE_SIMILARITY` compares two MINHASH sketches instead of estimating a single value.

On warehouses that aren't listed here, Omni can't roll up sketches and falls back to the base tables.

<Warning>
  Don't use BigQuery's `HLL_COUNT.MERGE` in a sketch measure. That function returns a final estimate, which Omni can't merge again. Use `HLL_COUNT.INIT` or `HLL_COUNT.MERGE_PARTIAL` instead.
</Warning>

### Setting up sketch-based aggregate awareness

A sketch needs two measures in the base view and one mapping in the aggregate view:

<Steps>
  <Step title="Define a sketch measure in the base view">
    In Snowflake, build the sketch with `HLL_ACCUMULATE`, which accepts a raw column. Use `HLL_COMBINE` only if the base table already stores a sketch column, because it accepts sketches rather than raw values.

    A sketch is binary data and isn't readable in query results, so set `hidden: true` to keep the measure out of the field picker.

    ```yaml title="order_items view" wrap theme={null}
    measures:
      user_sketch:
        sql: HLL_ACCUMULATE(${user_id})
        hidden: true
    ```
  </Step>

  <Step title="Define an estimate measure that reads the sketch">
    Add a second measure for the value your users query. This measure must reference the sketch measure, not the raw column.

    ```yaml title="order_items view" wrap theme={null}
    measures:
      user_approx_distinct_count:
        sql: HLL_ESTIMATE(${user_sketch})
    ```

    <Warning>
      Keep the sketch and the estimate in two separate measures. If you write the full expression in one measure, such as `HLL_ESTIMATE(HLL_ACCUMULATE(${user_id}))`, and then map that measure in `materialized_query`, Omni can't route the query. Omni routes the query only when the aggregate table stores the sketch and a separate estimate measure derives the value from it.
    </Warning>
  </Step>

  <Step title="Materialize the sketch in an aggregate table">
    In your transformation layer, build a table that calculates the sketch in advance. Aggregate at the finest grain you plan to query. This example builds a daily sketch, which Omni can roll up to weeks or months.

    ```sql title="daily_user_sketches aggregate table" wrap theme={null}
    SELECT
      DATE_TRUNC('DAY', created_at) AS date,
      HLL_ACCUMULATE(user_id) AS user_sketch
    FROM order_items
    GROUP BY 1
    ```
  </Step>

  <Step title="Map the sketch measure in materialized_query">
    In the aggregate view's definition, map the sketch measure in the `materialized_query.fields` parameter. Don't map the estimate measure — Omni derives that from the sketch at query time.

    ```yaml title="daily_user_sketches view" wrap theme={null}
    materialized_query:
      fields:
        "order_items.created_at[date]": date
        order_items.user_sketch: user_sketch
      base_view: order_items
    ```
  </Step>

  <Step title="Verify the setup">
    Query `order_items.user_approx_distinct_count` and check the generated SQL in the workbook. Omni reads the aggregate table and wraps the stored sketch in the rollup and estimate functions, as in `HLL_ESTIMATE(HLL_COMBINE(user_sketch))`.

    If the SQL reads from `order_items` instead, Omni didn't route the query. See [Troubleshooting](#troubleshooting).
  </Step>
</Steps>

### Importing Snowflake sketches

If your aggregate table stores sketches in Snowflake's object format — for example, sketches written by `HLL_EXPORT` or built outside Omni — the rollup functions can't read them. Add `HLL_IMPORT` to the aggregate view's `sql` statement to convert them to the binary format:

```yaml title="daily_user_sketches view" wrap theme={null}
name: daily_user_sketches
sql: |
  SELECT date, HLL_IMPORT(user_sketch) AS user_sketch
  FROM daily_user_sketches
```

Sketches built with `HLL_ACCUMULATE`, as in the steps above, are already binary and don't need `HLL_IMPORT`.

## Troubleshooting

If you expect Omni to use the aggregated table but it's not, consider the following:

* **Missing fields**: Ensure that all the fields being queried are present in the aggregated table and correctly mapped in the `materialized_query` parameter.

* **Missing join keys**: If your query joins the base view to other tables in a topic, the materialized view must include the join keys to those tables. Without the join keys, Omni cannot optimize queries that involve joins.

* **Incompatible queries**: `count_distinct` over a different level of aggregation than the aggregate table cannot use aggregate awareness, because the count cannot be re-aggregated from the pre-aggregated values. To get an approximate distinct count that can be re-aggregated, use a [sketch measure](#using-sketch-based-approximate-aggregates) instead.

* **Sketch measures**: If a sketch isn't routing, check that the sketch and the estimate are defined as two separate measures, and that `materialized_query` maps the sketch measure rather than the estimate measure.

* **Cache**: If the query results are being retrieved from the cache, Omni may not need to rewrite the SQL.

  * Try clearing the cache to test if aggregate awareness is working as expected.
  * You can also test by setting the [`cache_policy`](/modeling/topics/parameters/cache-policy) to `0` so that it never uses cache.

<Check>
  If a query cannot be answered entirely by the `materialized_query`, aggregate awareness is not likely to be used on that query.
</Check>

## Next steps

* Learn more about the [`materialized_query`](/modeling/views/parameters/materialized-query) parameter
* Define a [`cache_policy`](/modeling/topics/parameters/cache-policy)
* Bring Omni in sync with your database with [schema refreshes](/modeling/develop/schema-refreshes)
* Use the [Workbook inspector](/analyze-explore/workbook-inspector) to debug your queries


# Improving query performance with caching
Source: https://docs.omni.co/analyze-explore/performance/caching

Learn how Omni uses multi-layer caching and aggregate awareness to optimize query performance and reduce warehouse load.

Omni caches data at several layers to improve performance and reduce load on the underlying data warehouse.

In this guide, you'll learn about techniques like intelligent query routing and pre-aggregation to ensure consistently high performance.

## Query cache

Omni caches the results of individual queries to share between users observing the exact same data sets. Query results are cached for 6 hours by default, and shared between users with relevant permissions to the data set. The default can be configured using caching model parameters at a model or topic level, outlined [here](/modeling/models/cache-policies).

This means if one user queries a workbook or dashboard and shares the link with another user, the second user's results will frequently come from the query cache. This cache will only trigger for exact match of the query (all fields, pivots, filters, sorts).

The query cache can be cleared on an ad hoc basis:

* From the workbook: Tab > Run w/o Cache
* From the dashboard: View > Refresh Data

## Requeryable cache

In addition to the exact match cache, Omni will cache data for requery, offering acceleration to similar follow up queries, filtering, or sorting during a given session.

This cache is volume based and will hold the last 30 query results from a session. When data is returned without hitting the query limit, Omni will requery the data set when appropriate, offering much quicker query response times as the data is queried in the browser.

Let's take a look at some examples of the requeryable cache:

* **Re-sorting a data set** - Orders last 30 days, by day, sorted by day descending --> Invert to sort ascending
* **Filtering a result set** - Orders last 30 days, by day --> Orders last 7 days, by day
* **Regrouping a data set** - Orders by city (note query limit must not be hit) --> Order by state
* **Pivoting** - Orders by date, status --> Orders by date, pivoted by status

Here's a quick example where we aggregate users over a random selection of states in memory. We also quickly show the comparison to dropping back down to the database:

<img alt="" />

#### Utilizing the requeryable cache

Huge unlocks in performance are available when being thoughtful about caching. Whole dashboards can be brought in memory for instant slice and dice, rather than each filter permutation hitting the database. Over time this will be automated for dashboards, but to build requeryable dashboard caching, the filters can be appended to dashboard tiles to build cubes.

A simple example:

* This dashboard has one single-value tile counting total orders in the filtered set

* The table on the right shows the requeryable data set needed to cache each filter permutation

  * The underlying value: `orders.count`
  * The filters: `users.age`, `users.state`, `users.country`

This means when the table to the right is loaded, we have every permutation of the filters, and all requery will be in-memory in the browser. This technique can be refined for entire dashboards to create pseudo-instant query response times.

<img alt="" />

### Cache timing

Currently the exact-match cache has a 6 hour expiry window by default. As mentioned above, this is configurable using cache policy model parameters outlined [here](/modeling/models/cache-policies).

### Cache warming (preemptively caching data)

It's often a good idea to proactively warm the cache - if the first run can take a good bit and the dashboard will have heavy usage, it can be cached before the first user experiences the slower dashboard load. This can also sidestep having a stale cache entry (say someone loaded a dashboard yesterday and the cache was set to 24 hours to reduce cost).

We can take advantage of the fact that the scheduler will always skip the cache and run queries fresh. This means if we [schedule a dashboard](/share), we are also building a fresh cache entry that future users can rely upon.

A quick instructive example:

* 9pm: User runs a dashboard with data fresh as of 9pm. The model is caching data for 24 hours, and thus this dashboard cache will populate results tomorrow morning for any users that load the same dashboard.
* 6am: New data has come in overnight.
* 7:30am: Dashboard is scheduled to run. This busts the cache and replaces the cache with data fresh as of 7:30am.
* 8am: User loads the dashboard from the web browser, now with cached data as of 7:30am when the scheduler was run (rather than data from 9pm the day before if the scheduler was not run).

### Disabling caching

Caching can be turned off by setting the cache window to zero via a `cache_policy` ([more here](/modeling/models/cache-policies)). Example below:

```
cache_policies:
  dont_cache_at_all:
    max_cache_age: 0 seconds
```


# Building point-and-click queries
Source: https://docs.omni.co/analyze-explore/point-click-queries

To write queries using the pivot-table UI, select fields to query and Omni will automatically begin running queries in the database.

## Selecting fields

Dimensions and measures are divided into separate sections in the field picker, each nested under individual tables in your data warehouse.

* A **dimension** is a grouping in your query (date, location, type, etc).
* A **measure** is an aggregation over your dimensions (sum, count, average, etc). For example, to query total revenue per day you would select a date dimension (`order_items.created_date`) and a revenue measure (`order_items.sum_revenue`).

Here's an example of what that would look like:

<img alt="" />

There are several advanced actions available on field **selection using right click**, or hovering over the field and clicking the <Icon icon="ellipsis-vertical" /> icon.

### Identifying workbook-only fields

<Note>
  The [**Content permissions > Verification**](/administration/content-permissions#verification) setting must be enabled to use field verification indicators. **Organization Admins** can modify this setting.
</Note>

Fields created in a workbook — such as [custom fields](/analyze-explore/custom-fields) and [calculated fields](/analyze-explore/calculations) — are not part of the shared model. To help you distinguish these from shared model fields, Omni displays a small yellow badge called a **field verification indicator** next to their data type icon:

<img alt="Yellow badge next to a field's data type indicator in the field browser" />

These are **field verification indicators**, intended to help you understand which fields in the workbook are from the shared model and which are fields created specifically in the workbook. Fields without an indicator are from the shared model.

When the **Verification** setting is enabled, verification indicators appear in several locations throughout workbooks:

* **Field browser** - Next to unverified fields when selecting fields to add to your query
* **Data table column headers** - In the column headers of your results table
* **Visualization configurations** - Within the series editor, table configuration, and available fields lists

## Searching fields

Fields can be searched with the input box above the field picker. Default search will look at fields and views. However, you can specify additional conditions using these filter options:

* **In-use** - Limits results based on field usage. By default, all fields display regardless of whether they're used in the query. Click the dropdown arrow to choose between:
  * **Fields in-use** - Shows only fields that are selected or filtered in the current query
  * **Views in-use** - Shows all fields from views that have any in-use fields, useful for discovering related fields in the same view
* **Field type** - Limits the results to selected data types, such as `boolean`, `number`, etc.)
* **Topic** - Limits the results to fields in selected topics
* **Label** - Limits results to fields with or without labels
* **Descriptions** - Limits results to fields with or without descriptions

### Additional operators

The search box also supports operators that allow for additional querying options. For example, to limit the field type to `date` fields, you'd enter `data_type:date`.

| Operator      | Description                                                                                           | Example             |
| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------- |
| `data_type`:  | Filters fields based on data type: `date`, `string`, `boolean`, `interval`, `array`, `json`, `number` | `data_type:date`    |
| `is`:         | Filters fields based on whether the field is a `dimension`, `measure`, or `hidden`                    | `is:dimension`      |
| `model_type`: | Filters fields based on the model type: `schema`, `shared`, `branch`, `workbook`, `query`             | `model_type:schema` |
| `schema`:     | Filters fields based the schema that contains them                                                    | `schema:marketing`  |
| `tag`:        | Filters fields based on the provided tag                                                              | `tag:secure`        |

## Filtering

Each dimension can be added as a filter to focus on specific rows of data. See [Filter queries](/analyze-explore/queries/filters) for more information.

## Pivoting

Quickly build pivot tables by right-clicking any field in the field picker and selecting the **Pivot** option.

### Flattening and filtered measures

You can also flatten the pivot and create filtered measures by clicking the **actions menu** (three dots) on a column and selecting **Flatten pivot**. When using this feature you can also choose to create an **Other** bucket on the fly:

<img alt="" />

The new filtered measures will appear under the **Tab-only fields** section and the field that was originally pivoted on will no longer be selected as a field that is in-use.

## Creating custom fields

Custom fields can be created through the right click menu or using the **+** button in the field picker. Refer to the [Custom fields guide](/analyze-explore/custom-fields) for more information.

## Applying quick aggregates and timeframes

Omni provides a number of aggregations you can apply to fields right from the UI. In the field picker, right click on a field and select **Aggregates**. Date fields will have an additional **Timeframes** option.

| **Field type** | **Dimensions** (Timeframes)                                                                                                                                                                                                                                                                                                                                                          | **Measures** (Aggregates)                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Dates          | <ul><li>Date</li><li>Week</li><li>Month</li><li>Year</li><li>Second</li><li>Minute</li><li>Hour</li><li>Hour of Day</li><li>Day of Week Name <Tooltip><Icon icon="info-circle" /></Tooltip></li><li>Day of Week Number</li><li>Day of Month</li><li>Month Name <Tooltip><Icon icon="info-circle" /></Tooltip></li><li>Month Number</li><li>Quarter</li><li>Quarter of Year</li></ul> | <ul><li>Min</li><li>Max</li><li>Count Distinct</li><li>List <Tooltip><Icon icon="info-circle" /></Tooltip></li></ul> |
| Strings        | None                                                                                                                                                                                                                                                                                                                                                                                 | <ul><li>Count Distinct</li><li>List</li></ul>                                                                        |
| Numbers        | None                                                                                                                                                                                                                                                                                                                                                                                 | <ul><li>Count Distinct</li><li>Sum</li><li>Average</li><li>Min</li><li>Max</li><li>List</li></ul>                    |
| Booleans       | None                                                                                                                                                                                                                                                                                                                                                                                 | <ul><li>Count True</li><li>Count False</li></ul>                                                                     |

## Modeling options

In addition to the above, there are several more menu actions:

* **Duration** - Available on timestamp fields. Creates a [duration field](/analyze-explore/custom-fields#duration-fields) that calculates the time difference between two timestamps in configurable intervals.
* **Go to definition** - Opens the field definition in the [model IDE](/modeling/develop/guides/model-ide)
* **Hide** - Removes the field from the field picker; used for field cleanup
* **Primary Key** - Sets the field as the primary key for the view; used in counts through joined tables

## Limiting and paginating rows in results

<Tip>
  Set default row limits for queries running against the model with the [model-level](/modeling/models/default-row-limit) and [topic-level](/modeling/topics/parameters/default-row-limit) `default_row_limit` parameters.
</Tip>

By default, queries are filtered to 1000 rows of data, but the limit can be adjusted dynamically up to 50,000 rows and paginated to see all result rows directly in Omni.

Row limits don't impact the rows processed, only the rows available in the Omni UI. This setting is also used to paginate the results table. For example, if set to `5`, the results table will display five rows at a time.

<Warning>
  Use caution with high row limits. Browsers may have limitations on the amount of data that can be shown at once.
</Warning>

## Column and pivot limits

Omni currently supports any number of measures in the results table. Pivots are limited to 200 columns.

## Sorting

Data in the results table can be sorted on a column by column basis, with a cycle through descending, ascending, and unsorted. For sorting over more than one field (secondary sort or double sort), simply sort the first field and hold down shift for subsequent sort actions.

## Interacting with tables

Workbook results tables support spreadsheet-style selection, copying, editing, and cell interaction. For a full list of keyboard shortcuts, see [Table shortcuts](/getting-started/keyboard-shortcuts#table-shortcuts).

<Note>
  All gestures require the visualization to be in table view. These gestures are not available when viewing a chart.
</Note>

### Selecting cells

* **Click** a cell to select it
* **Click and drag** across cells to select a rectangular region
* **Shift+click** a cell to select a range from the anchor to the clicked cell
* **Command+click** (Mac) or **Ctrl+click** (Windows) a cell to add or remove it from your selection
* **Click a row number** to select an entire row. Combine with **Shift** to extend the selection or **Command/Ctrl** to toggle the row.
* **Click a column header** to select an entire column. Combine with **Shift** to extend the selection or **Command/Ctrl** to toggle the column.
* **Arrow keys** to move the focused cell. Hold **Shift** to extend the selection.
* **Command+A** (Mac) or **Ctrl+A** (Windows) to select all cells
* **Escape** or **click outside** the table to clear the selection

### Copying cells

Select one or more cells, then press **Command+C** (Mac) or **Ctrl+C** (Windows) to copy the selected values to your clipboard. Copied data uses a tab-separated format, so pasting into Excel or Google Sheets automatically places values into the correct cells.

When all cells are selected with **Command+A** / **Ctrl+A**, column headers are included in the copied output.

### Editing cells

* Press **Enter** on a calculation cell to enter edit mode, or on other cells to expand the cell value
* **Double-click** a calculation cell to enter edit mode
* **Right-click** a cell to open the context menu with options to drill, filter, copy, or expand

### Reordering columns

Drag a column header to reorder columns. Column reordering is not available in pivot tables.

### Editing calculations

When editing a [calculation](/analyze-explore/spreadsheet-tabs) in a table cell:

* Press **Enter** to save the calculation
* Press **Escape** to cancel and exit the editor
* **Shift+click** a cell to insert a cell range reference into the formula

Dashboard tables are read-only. For dashboard table interactions, see [Interacting with table tiles](/visualize-present/dashboards/charts#interacting-with-table-tiles).

## Formatting number and date columns

<Note>
  The formatting menu described in this section is supported for **number** and **date** columns. For unsupported data types, the formatting menu will be disabled in the format bar.
</Note>

You can quickly format columns in your results table using the quick formatting menu. This menu provides curated format presets based on the selected field's type, making it easy to apply common number and date formats.

To access the formatting menu:

1. In the results table, click a column header to select the column
2. Click the <WorkbookNumberFormatIcon /> icon in the format bar above the table

The menu displays format options appropriate for the selected field type.

### Number field formats

For number fields, the format menu includes:

* **Automatic** - Uses the field's default format
* **Number** - Standard number format
* **Percent** - Percentage format
* **Currency/Accounting/Financial** - Currency formats matched to your locale (for example, UK locale shows GBP options)

### Date field formats

For date fields, the format menu shows curated formats based on the field's date grain:

* **DATE and WEEK fields** - Day-level formats such as `Mar 17, 2022`, `2022-03-17`, and `Relative (3 days ago)`
* **MONTH fields** - Month-level formats such as `March 2022`, `Mar 2022`, and `2022-03`
* **QUARTER fields** - Quarter-level formats such as `Q1 2022`

All date format options include **Automatic** to use the field's default format.

### Advanced date formatting

The format menu provides quick access to commonly used formats. For advanced date formatting options, open the **Edit field** panel by:

* **Using the column header in the results table** - Hover over the header, click the <Icon icon="ellipsis-vertical" /> icon, then click **Modeling >** <Icon icon="pencil" /> **Edit**.
* **Using the field browser** - Hover over the field, click the <Icon icon="ellipsis-vertical" /> icon, then <Icon icon="pencil" /> **Edit**.

## Results table options

Clicking the **Options** button while viewing a workbook's results displays several options, outlined below.

### Column width

This setting allows you to automatically or manually set column width.

When widths are set automatically, Omni measures columns using the initially visible rows and locks the widths in place so columns don't shift as you scroll. Widths recalculate when the results or columns change or the table is resized.

### Header text

Controls how column headers in the results table are displayed - clipped (truncated) or wrapped to the next line.

### View names

When enabled, the name of the view the column belongs to will display above the column header

### Column totals

Enabling column totals adds a **Total** row at the bottom of the table. From here, you can right click on a measure's total and select **Total calculation** to customize how the total is calculated.

For example, you have a table that shows total sales by month for 2024. If you wanted to see the average sales across all months, you could change the **Total calculation** to **Average**:

<img alt="" />

#### Dimension column totals

By default, dimensions - such as dates or IDs - won't have a **Total** value. However, you can still apply one by clicking the column total and using the **Total calculation** menu.

#### Calculation column totals

Columns with calculations applied can also have custom totals. When column totals are enabled, Omni will default to using the column's calculation as the initial total. Take the following table as an example, where the **AVG Item Price** and **CONCAT Average Item Text** columns use Excel-like formulas:

| Date       | Order Total | Order Items | AVG Item Price | CONCAT Average Item Text      |
| ---------- | ----------- | ----------- | -------------- | ----------------------------- |
| Jan 2024   | \$50.00     | 2           | \$25.00        | Average item price is \$25.00 |
| Feb 2024   | \$100.00    | 3           | \$33.33        | Average item price is \$33.33 |
| Mar 2024   | \$72.00     | 6           | \$12.00        | Average item price is \$12.00 |
| **Totals** | \$222.00    | 11          | \$23.44        | Average item price is \$23.44 |

In this example:

* The **AVG Item Price** column has a formula of `Order Total / Order Items`. Using this formula, the column total is `$23.44`, which is the average of all the values in the column.
* The **CONCAT Average Item Text** column has a formula of `CONCAT("Average item price is ", AVG Item Price)`. Using this formula, the column total value is `Average item price is $23.44`, which uses the column total for the **AVG Item Price** column.

### Row totals

<Note>
  Row totals are only available for queries with at least one pivot.
</Note>

Enabling row totals adds a **Total** column to the right of the table. For example, you have products that are sold in the UK and USA. You want to view the total number of returned orders for each country by month, but you also want to calculate the total returns for the month. Creating a pivot table like the following and enabling **Row totals** will add a column containing this data:

<img alt="" />

### Swap rows and columns (transpose)

Enabling **Swap rows and columns** transposes the rows and columns in the results table, which is useful when measures are needed across rows. **Note**: Some features, such as column sort, must be set prior to enabling this feature.

### Group measures in pivot

**Applicable to pivot tables**. When enabled, measures in a pivot table will be grouped together. Let's say you have the following table, which is pivoted using `Status`:

| Status | Processing      | Processing      | Completed       | Processing      |
| ------ | --------------- | --------------- | --------------- | --------------- |
|        | **Total Sales** | **Order Items** | **Total Sales** | **Order Items** |
|        | 44,562.32       | 564             | 100,892.61      | 2,654           |

When **Group Measures in Pivot** is enabled, the table becomes:

| Status | Processing      |                 | Completed       |                 |
| ------ | --------------- | --------------- | --------------- | --------------- |
|        | **Total Sales** | **Order Items** | **Total Sales** | **Order Items** |
|        | 44,562.32       | 564             | 100,892.61      | 2,654           |

## Downloading results

Tab results can be downloaded as a CSV, Excel file, or JSON. Click **Tab > Download** or the <Icon icon="download" /> icon to the left of the **Limits** menu to get started.

When configuring a download, you can set the following options:

* **Format** - Select the file format for the download: CSV, XLSX, or JSON
* **Apply data formatting** - Preserve number and date formatting in the download
* **Timezone override** - Override the query timezone for the download. The picker pre-populates from your current page selection if the [timezone picker](/visualize-present/dashboards/timezone-override) is enabled.
* **Row limit** - Define the number of rows to include in the download. Options vary depending on the selected **Format**:
  * **Current limit** - Apply the query's current row limit to the downloaded results
  * **All possible results** - Include all possible rows in the result, disregarding the query's current row limit. For **XLSX formats**, this option allows downloads of up to 1 million rows.
  * **Custom** - Specify a custom row limit for the download, which can be greater than the query's current row limit

## Removing fields and filters

Fields can be removed from the table either using the field picker (clicking on active fields will remove them) or right-clicking / kebab-icon-clicking in the column's table header.

## All views and fields

Most querying will be done through curated topics in the UI, but at times, admins and developers may need access to the full database for ad hoc requests or in order to build new models. All Views & Fields allows those with access the ability to use the pivottable UI to query any table available for a given connection.

The dropdown above the search box offers two options to discover views:

* Views from modeled schemas
* Each schema in the database

The reason we offer both options is scalability in the data model - if we 'model' thousands or millions of tables in the Omni shared data model, there can be significant performance constraints in building the model and running queries. That said, for smaller schemas (hundreds of tables), you can comfortably model your entire data warehouse without performance considerations, and "View from modeled schemas" will simply reflect the entire warehouse. For customers with hundreds or thousands of schemas or tables, more curation in the data model will reduce clutter, and ad hoc needs across the warehouse can still be achieved through schema selection.

To 'model' a schema, simply touch any view in the given schema (for example, on view Users, add `label: Users`); this will be done through a curation process like starring in the future

For now, search will only operate inside the selected schema (or across all modeled schemas), so you may have to switch schemas to find the appropriate table if your full warehouse is not modeled. Note this UI will not override [Schema Restriction](/connect-data/schema-restriction), if the list of schemas has been curated. In the future, we will offer search over all schemas together in addition to schema by schema.

<Accordion title="Example">
  For a customer with 2 schemas of 10 tables each, any modeling in either schema will pull the full schemas into the "Views from modeled schemas". All Views & Fields will operate as simply one big list of all your tables

  For a customer with 1000 schemas of 10 tables each, likely only 5-10 schemas may be modeled (at least to start). "Views from modeled schemas" will by default curate the list of tables to those 10 schemas, but to browser alternative schemas, select them from the dropdown.
</Accordion>

## Period-over-period analysis

Period-over-period (PoP) analysis is a business intelligence technique that compares metrics in a recent period to the same period in the past.

You can seamlessly create those time periods from the field picker by selecting ”Period over Period” from the three dot menu of the date dimension you want to use.

<img alt="" />

Above the results pane two drop downs will appear. In the first drop down, choose the current period and in the second drop down, the period you want to compare. The options to compare will default to relevant time frames; however you can always customize that logic.

<img alt="" />

Users will be able to see more exact period parameters in the information icon on the results table.

<img alt="" />

## Filling missing data

### Dimension filling

<img alt="" />

Often when querying with filters, you may return a result set that does not include every possible dimensions, for example count of sales on days with zero sales. It can be valuable to return these missing dimensions for reporting.

After querying a dimension that can be filled (ranged dates, lists), simply right click on the dimension and select 'Fill in Missing Rows'. Note the option may not always appear on dates when Omni does not know the start and end date. To bring the 'Fill in Missing Rows' option, simply filter the date over a clear time period (ie. 2023-01-01 to 2023-02-01), which Omni will then fill in rows for.

In addition to dates, Omni can fill in missing values for enumeration fields - for now, just bins and groups defined in the data model. This may expand over time.

Note that fill is capped at 8000 values, for more complex use cases, direct SQL is recommended.

### Pivoted table filling

In addition to filling dimensions, it's often valuable to fill a pivoted table that contains nulls for 'more correct' reporting of aggregates. To replace nulls with 0s in the pivottable, simply select "Fill in Missing Cells in Grid" on a pivoted report:

<Note>
  It is best to use Fill in Missing Cells in Grid when adding calculations to your pivoted results. Based on the way that pivoted tables are constructed calculation formulas operating over a range or conditionally (e.g SUMIFS) in particular may behave unexpectedly
</Note>

<img alt="" />

## Joining tables

<Note>
  Database uploads must be enabled to join data input or CSV data using the methods described in this section. Otherwise, you can use the `XLOOKUP` function to perform cross-tab analysis. Refer to the [Data input tables guide](/analyze-explore/data-input-csvs#querying-and-joining-data-input-tables) for more information and examples.
</Note>

At times, you may need to join tables in a workbook for richer analysis. To join tables in the workbook, open the Join model from the action menu on any view:

<img alt="" />

There are three core pieces to configure joins: table and field selection, join type, and relationship:

<img alt="" />

### Adding joins to a topic

For existing joins that are not available in a topic, users will be prompted whether they want to add said join to the active topic.

<img alt="" />

### Join table and field selection

Simply select the table and corresponding fields to join. Right now compound joins or complex logic is not available in the UI, and must be configured in the model interface. Clicking in the table dropdown will also present a search option if there are many tables in the data warehouse.

### Join types

Omni offers `LEFT`, `RIGHT`, `INNER`, `FULL OUTER`, and `CROSS` joins in the UI.

### Join relationships

Join relationships are used to ensure correctness of counts when joins may fan the result set (ie joining many orders to a query about users and counting users). If you know the relationship between your tables, you can select via dropdown. Options include `Many to one`, `One to many`, `One to one`, and `Many to many`. It is generally recommended to use `Many to one` joins rather than `One to many` joins.

For users that may struggle with choosing the correct relationship, when relationship is set to `Unknown`, the Infer Relationship button will become active. This will examine the cardinality between each join key and select the proper relationship. We recommended using the button, as often uniqueness may not match expectation and this can flag potential data issues like duplicated rows or keys.

## Adding controls

Controls allow a user to swap out one field for another on a query making it more dynamic. There are three main types of controls:

* Time
* Field
* Parent

### Time controls

These controls will allow you to swap the time frame within the underlying query. This provides an easy UI based mechanism to swap from daily to weekly to monthly and back again, all without any underlying work needing to be done to facilitate it from an administrative perspective. A time frame control can be added from either the field picker or from the date field in the results table by choosing **Add Time Frame Selector** from the three dot menu.

### Field

In order to create a control for dimensions or measures, first add one to the query and switch to the **Results** view. From there, select the three dot menu on the column and **Add field selector**. A control will appear above the table with a three dot menu for a user to edit the control (change the label, add additional fields, or add a parent control).

Once there are two or more options in the control, a user can select the field they want represented in the table or visualization and dynamically toggle among the options.

### Parent controls

These controls will allow you to coordinate the toggling of multiple controls at once from a single point and click UI. From any existing control, select the option **Add parent control**. A control will appear above the table, select the three dot menu to edit the control. First add options that will appear in the drop down, then assign the child controls that will be chosen based on the option selected in the parent control.

<Note>
  Controls created in the workbook will not appear on the dashboard. Read more about how to add controls on the dashboard level [here](/visualize-present/dashboards).
</Note>


# Filters
Source: https://docs.omni.co/analyze-explore/queries/filters

Add dimension-based filters to workbook queries to focus on specific data. Configure date, number, and string filter options.

Each dimension can be added as a filter to focus on specific rows of data. Different filtering options will be presented for dates, numbers, and strings:

<img alt="" />

<img alt="" />

<img alt="" />

To filter using more than one value (equivalent to using `OR`), insert a comma between values: `[bread, cheese]`. If your filter values include commas, you can escape them with `\`: `San Francisco\, CA`.

## Date filters

<Note>
  Filter suggestions are limited to 2,000 rows.
</Note>

Date filtering offers several filter options, including:

* Absolute date filtering, such as `2022`, `2023-01-01`, `2021-Q4`
* Relative date filtering, such as `after 7 complete days ago`, `1 year ago`

At times, filtering may require using both absolute and relative dates, for example `first ten days of 2023` or `100 days ago for 10 days`. For these situations, time for an interval duration offers more flexible time inputs:

* **The first input** should contain the **starting point**. This value should either be a date (`2023-01-01`) or a relative date (`10 days ago`). **Note**: `Ago` is required.
* **The second input** should contain the **duration**.

Check out the following examples to see how it all comes together:

```
# First ten days of 2023
[2023][10 days]
# 100 days ago for 10 days 
[100 complete days ago][10 days]
# 1 hour ago for 2000 milliseconds
[1 hour ago][2000 milliseconds]
```

### Interval timeframe units

Intervals can accept any timeframe unit:

| Interval type | Supported units                                                                |
| ------------- | ------------------------------------------------------------------------------ |
| day           | `day`, `days`, `complete day`, `complete days`                                 |
| week          | `week`, `weeks`, `complete week`, `complete weeks`                             |
| month         | `month`, `months`, `complete month`, `complete months`                         |
| quarter       | `quarter`, `quarters`, `complete quarter`, `complete quarters`                 |
| year          | `year`, `years`, `complete year`, `complete years`                             |
| millisecond   | `millisecond`, `milliseconds`, `complete millisecond`, `complete milliseconds` |
| second        | `second`, `seconds`, `complete second`, `complete seconds`                     |
| minute        | `minutes`, `complete minute`, `complete minutes`                               |
| hour          | `hour`, `hours`, `complete hour`, `complete hours`                             |

## Filtering by another query

With two or more tabs, one tab, or query, can be used as a filter in other queries. This is particularly useful for creating a dynamic subset of information in one query and a deep dive into the results on another tab.

For example, you want to understand the brands your top customers are purchasing. To do this, you would:

1. In a workbook, create a tab with the definition of a top customer.

2. Create a new tab.

3. In the new tab, add the dimensions and measures you want to analyze.

4. In the field picker, locate a dimension used in the top customer definition tab.

5. On the dimension, click the **options menu** (three dots) and select **Filter**.

6. Select **Is from another query**.

7. In the modal that displays, select the tab and dimension you want to filter by:

   <img alt="" />

This will filter the tab results by the selected subset. In SQL, this generates `WHERE` clauses that look like `WHERE IN (SELECT...)` where the `SELECT` clause is the filtering query.

<Check>
  You can also use this approach to filter **out** data. To do this, select **Is not from another query** in the **Filter** menu or the [`field_name_not_in_query` filter parameter](/modeling/filters/operators/field-name-not-in-query).
</Check>

## Filtering by multiple conditions

You can filter a field by multiple conditions (e.g. `Date is in the past 30 days OR date is null`) by clicking **Add Condition** in the filter modal. Then, select if you want **All** or **Any** of the conditions to apply to the query.

## Filtering across multiple fields

You can create filter groups of OR filters that span multiple fields, allowing you to build queries where any of several conditions across different fields can be true, such as `Country is USA OR Joined Month is March`.

Unlike filtering by multiple conditions on a single field, multi-field OR filters let you combine conditions from entirely different dimensions, while single-field multi-condition filtering applies multiple conditions to the same field.

For example:

* **Single-field filtering** - `Date is in the past 30 days OR date is null`, where both conditions apply to the same date field
* **Multi-field filtering** - `Country is USA OR Gender is Female`, where conditions apply to two different fields

To create a multi-field OR filter:

1. Add a filter to your query by selecting a dimension and choosing your filter condition.
2. Hover over the filter and click the <Icon icon="ellipsis-vertical" /> icon.
3. Click **Add to filter group > New filter group**.
4. In the dialog that displays, click **Add filter**.
5. Select another field and configure its filter condition.
6. Repeat as needed to add additional fields to the filter group.
7. When finished, click **Create**.

## Filter suggestions

When you filter on a field, Omni suggests values to pick from. By default these come from a query for the field's distinct values, capped at 2,000 rows, scoped to the topic the field belongs to.

See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information, including changing where suggestions come from, how other filters facet them, and how they're cached and refreshed.

## Adding dashboard filters to workbook queries

<Note>
  This feature is not available in raw SQL mode or on read-only/linked tabs.
</Note>

When editing a workbook tab that's backed by a dashboard with filters, you can quickly add dashboard-level filters to your workbook query using the **Filters from dashboard** dropdown.

Click the **Filters from dashboard** dropdown located in the query tab's filter bar to see applicable dashboard filters. Values and settings from the dashboard are preserved when a filter is added.

If you don't see a filter you expect to, keep in mind that Omni excludes:

* Filters already present on the query
* Filters whose fields are covered by existing controls
* Hidden filters
* Cross-topic filters (filters that don't match the tab's topic)
* Dashboard controls


# Building workbook queries on topics
Source: https://docs.omni.co/analyze-explore/queries/topics

Start workbook queries from curated topics to explore governed datasets with pre-defined fields, joins, and business logic.

When you create a workbook or add a new query tab, you'll be prompted to select a starting point for the query. The **All Views & Fields** view will display the topics you have access to in the model that the workbook is based on.

<img alt="" />

## Using topics in queries

<Note>
  Workbook queries can be used to create dashboard visualization tiles. If you intend to create and share a dashboard of your work with **Restricted Queriers** and **Viewers**, keep in mind that these users can only see dashboard tiles built on topics unless AccessBoost is enabled. Refer to the [AccessBoost guide](/share#boosting-permissions-with-accessboost) for more information.
</Note>

### Switching topics

To change topics in a query tab, use the topic switcher in the top left corner of the field browser:

<Frame>
  <img alt="Highlighted topic switcher in an Omni workbook" />
</Frame>

The search allows you to search for topics, topic groups, and composite topics by label, name, and description.

Select the topic you want to use, which will populate the field browser with the topic's tables and fields.

### Using multiple topics

A query can only use a single topic at a time. However, depending on your needs, there are a few workarounds that may be useful.

Start your analysis in the topic that best matches your use case. Then:

* Consider adding a new join path to data that isn't included in the topic yet, or
* If there isn't a clear relationship, consider using [`XLOOKUPs`](/analyze-explore/calculations/position#xlookup) or a [spreadsheet tab](/analyze-explore/spreadsheet-tabs) to combine multiple queries into a final output

**Note**: While a query can only be tied to one topic, you can use multiple topics in a single document by adding multiple queries. The topics must exist in the model that the workbook is built on.

### Querying with AI

If the Workbook Agent is enabled in your Omni instance, you can use the agent to query topics using natural language. How you access the agent differs depending on whether you're using an embedded Omni instance or not:

* **Embedded** - Click the <Icon icon="sparkles" /> icon in the workbook's sidebar
* **Non-embedded Omni** - Click the floating avatar to open the chat panel

Refer to the [Building queries & filters with AI guide](/ai/queries) for more tips on using the Workbook Agent.

## Editing topics in the workbook

To make changes to a query's current topic, you can do either of the following:

* Click **Model > Edit topic**
* Click the <Icon icon="ellipsis-vertical" type="solid" /> icon and then select **Edit topic** from the context menu

Both of these options will open the topic in the topic editor.

You can also use <Icon icon="ellipsis-vertical" type="solid" /> icon **> Go to definition**, which opens the topic's YAML file in the model IDE in a new tab.

Refer to the [Creating topics guide](/modeling/topics/setup) for more information about the workbook-based topic editor.

## Creating topics from queries

Queries created using **All Views & Fields** can be converted into topics to enable reuse. In a query tab, click **Model > Save as topic**. This will open the topic editor, where some information - such as in-use fields - will be automatically populated using metadata from the query.

Refer to the [Creating topics guide](/modeling/topics/setup) for more information about the workbook-based topic editor.


# Querying data in Omni
Source: https://docs.omni.co/analyze-explore/querying

Explore the different ways to query and analyze data in Omni, from conversational AI to point-and-click to SQL.

Omni offers several ways to query your data, whether you prefer natural language, a visual interface, or writing SQL directly. Each path produces a modeled query that respects your organization's [permissions](/administration/users/permissions) and [semantic model](/modeling), so results are consistent no matter how you get there.

## Ask questions with the Omni Agent

The [Omni Agent](/ai/chat) is a standalone chat experience available from Omni's main [sidebar](/administration/settings/sidebar). Ask questions in plain language and get queries, visualizations, and summaries back — no workbook required.

The Omni Agent is a good starting point when you:

* Want a quick answer without setting up a workbook
* Need to explore a dataset you're not familiar with
* Want to create a dashboard from a conversation

<Card title="Omni Agent" icon="message-bot" href="/ai/chat">
  Ask questions, generate queries, and build visualizations in a conversational interface.
</Card>

## Build queries in a workbook

[Workbooks](/analyze-explore/workbook-basics) are Omni's core analysis environment. Each workbook contains one or more tabs where you can build queries, create visualizations, and save your work. Within a workbook, you have several options for building queries:

### Workbook Agent

The [Workbook Agent](/ai/queries) lets you build and refine queries using natural language directly in a workbook. Describe what you're looking for — like "total revenue by region for the last quarter" — and the agent generates a modeled query you can then modify, visualize, and save.

The agent can also [create filters](/ai/queries#creating-filters), [summarize results](/ai/queries#summarizing-query-results), [build calculations](/analyze-explore/calculations#ai-generated), and [generate visualizations](/ai/visualizations) from your query.

### Point-and-click

The [point-and-click interface](/analyze-explore/point-click-queries) lets you build queries by selecting fields from the field picker. Choose dimensions and measures, apply filters, set sorts, and pivot results — all without writing any code. This is the most flexible way to build and iterate on queries in Omni.

### SQL

For users who prefer writing queries directly, Omni supports [SQL tabs](/analyze-explore/sql) in workbooks. You can write queries in your database's SQL dialect or use Omni SQL, which adds helper functions and field references on top of standard SQL.

## Work with additional data

Beyond querying your connected databases, Omni workbooks support additional ways to bring in and work with data:

* **[CSV & Excel uploads](/analyze-explore/data-input-csvs)** — Upload files or manually enter data to use alongside your database queries. Useful for enriching analyses with data that isn't in your data warehouse.
* **[Spreadsheets](/analyze-explore/spreadsheet-tabs)** — Add spreadsheet tabs to a workbook that connect to your queries and provide an Excel-like environment for formatting, ad hoc analysis, and building on top of live data.

## Automate with skills

[Skills](/ai/skills) let you save a set of AI instructions and reuse them by name. Type the skill's identifier in the Omni Agent and the AI follows those steps — querying data, summarizing results, or working through a multi-step process — without needing writing the prompt again.

Skills are useful for standardizing recurring analyses, guided lookups, and data quality checks across your team. Any user with AI chat access can create one — the quickest way is to ask the agent to turn a conversation into a skill.

## Next steps

* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve the quality of AI-generated queries
* [Configure topics](/modeling/topics) to organize the data available for querying
* [Learn about workbooks](/analyze-explore/workbook-basics) for saving and sharing your analyses


# Saving queries as views
Source: https://docs.omni.co/analyze-explore/saved-views

Save workbook queries as reusable views to build subqueries and join them to your analysis, compiled as CTEs when queried.

Workbook queries can be saved as views, allowing you to quickly build and join subqueries to your analysis. This workflow allows you to do light transformations on data, which are then compiled as CTEs when queried.

## Requirements

To create query views, you'll need:

* **Querier, Modeler,** or **Connection Admin** permissions
* **Connection Admin** or **Modeler** permissions to promote the changes to the shared model

## Creating query views

Start by building out a query in a workbook. Then:

<Steps>
  <Step>
    Click **Model > Save query as view**.
  </Step>

  <Step>
    When prompted, enter a name for the view. Omni provides a smart default name:

    * **For point-and-click (semantic) queries**: `{base_view_name}_facts` (e.g., `users_facts`)
    * **For raw SQL queries**: `sql_query_view_HH_MM` (based on the current time)

    If a view with the default name already exists, Omni automatically appends `_2`, `_3`, etc. to avoid name collisions. You can customize the name by editing the **Name** field.
  </Step>

  <Step>
    Click **Create query view**.
  </Step>
</Steps>

A new **View** tab will open where you can edit the view itself. You can add or remove fields, add calculated fields, and add joins, just like you would with any other database view:

<img alt="" />

Click the **Save changes to view** button to apply the changes to the view. This tab can be closed and you'll still be able to use the view in other workbook queries.

## Editing query views

See [Editing query views](/modeling/query-views/edit).

## Promoting query views

If you want the query view to be accessible in new and existing workbooks built on the underlying model, you'll need to promote them. See [Promoting changes to the shared model](/modeling/develop/promotion) for more information.


# Formatting & analyzing data with spreadsheet tabs
Source: https://docs.omni.co/analyze-explore/spreadsheet-tabs

Use spreadsheet tabs in Omni workbooks for Excel-style formatting, formulas, and analysis powered by always-live query data.

Omni’s spreadsheet tabs bring the power of traditional Excel spreadsheets into your existing reporting and analysis workflows, with the added benefit of always-on, live data.

Spreadsheet tabs are ideal for:

* Creating richly formatted tables such as financial statements, invoices, or planning sheets
* Performing ad hoc or exploratory analysis

<img alt="" />

Because these spreadsheets are directly connected to your database via Omni queries, you no longer need to export or manually refresh data. You can build and maintain familiar spreadsheet workflows - such as reporting templates or budget trackers - confident that your data is accurate, current, and easy to work with.

## How it works

<Info>
  Spreadsheets are enabled by default, but **Organization Admins** can disable (or re-enable) them in the [Organization settings](/administration/settings) with the **Create spreadsheets** setting.

  You can enable and disable spreadsheet tabs for individual documents by navigating to **File > Document settings > Abilities** in a saved document.
</Info>

Spreadsheets are a type of tab that, when enabled, can be added to Omni workbooks. Other queries in the workbook can be connected to the spreadsheet and used as a data source.

When queries are connected to a spreadsheet tab, a new sheet will be added inside the spreadsheet tab. You can then reference the data in the sheet like you normally would in Excel.

Sheets that correspond to a workbook query will automatically update when the query changes. For example, if a new column is added to a query, the sheet associated with the query will be updated to include the new column.

### Limitations

The most important limitation relates to data usability outside of a spreadsheet tab. **Data in spreadsheets can't be used in other queries or promoted to a shared model.** While you can work with query data by [connecting it to a spreadsheet tab](#connecting-workbook-queries), data created in the spreadsheet - for example, by manual entry or through the use of [formulas](#creating-formulas) - can't be used elsewhere.

#### Excel differences

* **Some formulas may differ slightly from Excel**. Omni expects the majority of formulas to be the same, but we recommend using the [in-sheet formula builder](#creating-formulas) to verify the correct syntax.
* **Hotkeys aren't an exact match**
* **References may not reflect structural changes the same way as Excel.** Refer to the [Handling query changes](#handling-query-changes) section for more information and examples.
* **Creating pivot tables isn't supported**. If you need to create pivot tables, create a ["regular"](/analyze-explore) or [SQL query tab](/analyze-explore/sql) to use Omni's native [pivot](/analyze-explore/point-click-queries#pivoting) functionality. **Note**: You can connect queries containing pivots to spreadsheets as a data source.
* **Creating in-sheet charts isn't supported**. If you need to create a visualization, create a ["regular"](/analyze-explore) or [SQL query tab](/analyze-explore/sql) to use Omni's native [chart](/visualize-present/visualizations/types) functionality.

## Adding spreadsheets to workbooks

When spreadsheet tabs are enabled, you'll see a **Spreadsheet** option when you create a new workbook or query tab. Click this option to add a **Sheet** tab to the workbook.

The tab will display a blank sheet similar to what you'd see in an Excel workbook. At this point, you can [connect other workbook queries to the spreadsheet](#connecting-workbook-queries) to interact with your data.

## Adding data to spreadsheets

You can add data to spreadsheets by:

* [**Connecting workbook queries**](#connecting-workbook-queries) - **Recommended**. Creates additional sheets containing query data in the spreadsheet, which are automatically updated when a query or its results change.
* [**Importing existing CSVs & XLSX files**](#importing-existing-csvs-and-xlsx-files) - Recreate existing formatting and formulas in Omni
* [**Manually entering data**](#manually-entering-data)

Omni recommends connecting workbook queries as data sources whenever possible. This ensures that your data is current and, if needed, accessible outside of the spreadsheet tab.

### Connecting workbook queries

The recommended way to add data to a spreadsheet tab is to connect an existing workbook query. This allows you to manipulate and format data while taking advantage of your existing data model.

Open the spreadsheet's settings by clicking the **drawer icon** (highlighted in the following image) in the sidebar:

<img alt="" />

When a workbook query is added to a spreadsheet, Omni will add a **protected sheet** with the same name as the query to the spreadsheet.

Data in sheets associated with workbook queries will automatically update when the query's results or structure changes. For example, if you add a new column to a query, the associated sheet will also be updated to include the new column.

### Importing existing CSVs and XLSX files

<Info>
  Data added using this method only lives in the spreadsheet tab where you upload it. If you need to use CSV or XLSX data outside of a spreadsheet tab, consider using [data input tables instead](/analyze-explore/data-input-csvs).
</Info>

Omni also supports importing existing CSV and XLSX files into spreadsheet tabs! For XLSX files, Omni will preserve your formatting, formulas, and references, allowing you to recreate existing workflows and wire them up to live data. CSVs will be parsed into columns.

1. In a workbook, create a new spreadsheet tab or add a blank sheet to an existing spreadsheet tab.
2. Drag the file into the blank sheet. A **Drag CSV or XLSX here** message should display.
3. Drop (release) the file to begin the import.

After the upload completes, you can edit the spreadsheet like you usually would.

<Check>
  Get started quickly by importing an [an Excel template](https://create.microsoft.com/en-us/excel-templates) - you can then customize it using your own Omni data.
</Check>

### Manually entering data

To manually enter data, click into a cell and type or paste the data. **Note**: Data added using this method only lives in the spreadsheet tab you enter it into. It will not be accessible outside of the spreadsheet tab.

## Referencing query data

Data in other sheets in a spreadsheet tab can be referenced just like you would in Excel. This includes direct references like `'<SHEET_NAME>'!A1` or as arguments in [formulas](#creating-formulas).

### Creating formulas

<Note>
  The formulas described in this section are **not** the same as Omni's [table calculations](/analyze-explore/calculations). Spreadsheet tabs support additional formulas, and the syntax between Omni table calculations and spreadsheet tab formulas may differ slightly.
</Note>

Formulas in Omni spreadsheets generally mirror those in Excel. To view all supported formulas, click the **Formulas** tab in a spreadsheet and then **Insert Function**:

<img alt="" />

Refer to the [Excel documentation](https://support.microsoft.com/en-us/office/excel-functions-by-category-5f91f4e9-7b42-46d2-9bd1-63f26a86c0eb) for detailed information about these formulas.

If you prefer a more guided experience when using functions, select a function in this window and click **OK**. You'll be prompted to fill in the formula's arguments.

You can also directly add formulas to sheets. In a cell or the formula editor, enter `=` to start building the formula. For example:

```
=AVG(A:A)
```

### Copying with references

Omni supports copying a sheet connected to a workbook query to a new, editable sheet in a spreadsheet tab.

Right-click on the protected query sheet and select **Copy with references**:

<img alt="" />

A copy of the results sheet will be created. Unlike the original protected sheet, you can directly edit the contents of the copied sheet:

<img alt="" />

**Note**: The new sheet uses absolute references to pull in data. This means that if the query's results set changes, the data in the copied sheet will also change. Refer to the [Handling query changes section](#handling-query-changes) for more information and examples.

### Unlocking spreadsheets for dashboard editing

By default, spreadsheets on dashboards are read-only. If you want dashboard viewers to be able to edit cells - for example, to perform what-if analysis - you can unlock a spreadsheet tab.

When a spreadsheet is unlocked and viewed on a dashboard, viewers can edit all cells in the spreadsheet.

To unlock a spreadsheet:

1. Open the spreadsheet's settings by clicking the **drawer icon** in the workbook sidebar.
2. Toggle **Unlock spreadsheet** to **on**.

<Note>
  Unlocking a spreadsheet only affects how it behaves on a dashboard. In the workbook editor, all cells remain fully editable regardless of the toggle state.
</Note>

### Handling query changes

When a workbook query is updated, the sheet associated with it in a spreadsheet tab will also be updated to reflect the changes. This includes - but isn't limited to - structural changes like adding columns, changing a filter value, or adding pivots.

Omni spreadsheets differ from Excel in the way that underlying data changes are "absorbed." For example, if you have a hardcoded reference for columns `A:D` and a new column (`E`) is added, only the query sheet will be updated to include the new column. The sheet containing the reference will have to be manually updated to `A:E`.

Let's take a look at another example, this time with a query that uses pivots.

#### 1. Workbook query with filters and pivots

The image below displays the results of a query with two filters:

* **Category** - Only include specified product categories
* **Created At** - Only include records for the **past 3 complete years**

The results of the query have been pivoted so that the table has columns for the years `2022`, `2023`, and `2024`.

<img alt="Workbook query results table for a query that has two filters. Results show the total sales price for product categories, pivoted by year for 2022, 2023, and 2024" />

#### 2. Query results sheet

This image displays the sheet in a spreadsheet tab associated with the **Sale Prices by Year** workbook query.

Notice that the years are in the `B`, `C`, and `D` columns, which matches the results table in the actual workbook tab.

<img alt="" />

#### 3. Reference query results data

This image displays a formatted sheet that references cells in the `Sale Prices by Year` sheet. Just like in the query results, this sheet contains a column for each year (or pivot).

For example, data for `2022` is pulled from the `B` column in the `Sale Prices by Year` sheet.

<img alt="" />

#### 4. Change filter in workbook query

Let's look at what happens to a sheet when the underlying structure of the query results changes.

In this example, the **Created At** filter has been changed to include only the **past 2 complete years**, resulting in the `2022` column being removed from the query results.

<img alt="" />

#### 5. Updated query results sheet

When query results change, the sheet associated with the query will automatically be updated. This image shows the updated `Sale Prices by Year` sheet in the spreadsheet tab.

Notice that it now only contains columns for `2023` and `2024`, which matches the results in the actual workbook tab.

<img alt="" />

#### 6. Impact on query data references

In this last image, you can see what happened to the formatted sheet when the query results sheet it references changed. The references and formulas in the highlighted column are now incorrect.

When the query's filter included **the past 3 complete years**, the `D` column in the `Sale Prices by Year` sheet was populated. Because it was changed to **the past 2 complete years**, a column was removed and the data shifted to the left, leaving the `D` column empty.

<img alt="" />

### Removing query data

You can remove workbook queries from a spreadsheet by unchecking them in the spreadsheet's settings panel.

**Note**: When a workbook query is removed from a spreadsheet, the sheet referencing the query will also be removed. This doesn't delete the query from the workbook.

## Saving your work

Changes in spreadsheet tabs autosave automatically in the background as you work.

You can also manually save your work at any time by clicking **Save Sheet** in the spreadsheet's **Home** tab:

<img alt="" />

This button will be highlighted in blue when there are unsaved changes.

## Displaying spreadsheets on dashboards

<Note>
  Spreadsheets on dashboards are read-only by default. To allow dashboard viewers to edit cells, [unlock the spreadsheet](#unlocking-spreadsheets-for-dashboard-editing) in the workbook editor. To edit the full spreadsheet, click **File > Edit** or the **Edit** button to open a draft of the document.
</Note>

Spreadsheets can be included on a dashboard just like any other visualization. By default, Omni will only display the **first sheet** in the spreadsheet on the dashboard.

### Including all sheets

To display all sheets on a dashboard, first open the spreadsheet's settings by clicking the **drawer icon** in the workbook's sidebar. Then in the **Dashboard settings** section, toggle **Show tab strip** to **on**:

<img alt="" />

When enabled, all sheets will display as tabs on the dashboard:

<img alt="" />

### Changing sheet display order

By default, Omni will display the first sheet in a spreadsheet tab when a dashboard is viewed. You can change the sheet order by dragging sheets in the spreadsheet tab in the workbook. When finished, click [**Home tab > Save Sheet**](#saving-your-work) to ensure the changes are reflected on the dashboard.

### Exporting spreadsheets

Spreadsheets can also be exported back to Excel. On a dashboard, hover over the right corner of a spreadsheet tile and click the ⠇ (three dots). Then select **Download XLSX**.


# Understanding SQL generation in Omni
Source: https://docs.omni.co/analyze-explore/sql/generation

When building an analysis - whether that's through the workbook or using AI - Omni generates SQL to execute against your data warehouse and returns the results.

Omni accomplishes this by leveraging the models, relationships, and topics defined in the semantic layer to dynamically build SQL statements. Through this process, Omni is able to optimize queries for application performance and readability while also providing graceful handling for data fanouts using symmetric aggregates.

Omni provides the flexibility to query data in two main ways:

1. **Through the virtualized schema model**
2. **Directly using raw SQL.** When using raw SQL, Omni will not generate or override any SQL logic.

## Key concepts

<AccordionGroup>
  <Accordion title="Semantic model">
    Think of a semantic model as instructions to Omni on how to write SQL on your behalf. Omni breaks down common SQL statements you might write into small, reusable pieces that can be pieced together on demand.

    You don't have to run everything through a semantic model in Omni - and likely shouldn't! - but it can be a powerful tool for enabling self-service reporting, AI querying, and improved change management through your BI tool.
  </Accordion>

  <Accordion title="Views">
    [View files](/modeling/views) in Omni are virtualized representations of tables (or views) within your data warehouse that tell Omni how fields in the workbook map to fields in your data warehouse.

    These map to the `FROM` and `JOIN` statements in SQL.
  </Accordion>

  <Accordion title="Relationships">
    Relationships tell Omni the join logic that should be used when the multiple views are used in the same analysis.

    This maps to a `JOIN` statement in SQL.
  </Accordion>

  <Accordion title="Dimensions">
    Dimensions are field definitions, which can be either a column reference or a calculated field (e.g. `datediffs` or `case whens`). Dimensions are attributes that can be queried and grouped by.

    These go into `SELECT` and `GROUP BY` statements in SQL.
  </Accordion>

  <Accordion title="Measures">
    Measures are field definitions specifically for aggregations - `sums`, `counts`, `averages`, etc.

    These go into the `SELECT` statement in SQL, but won't be grouped by.
  </Accordion>

  <Accordion title="Topics">
    [Topics](/modeling/topics) are not required for using Omni's semantic model but they are a helpful tool for adding an extra layer of curation on top of your semantic model.

    They let you explicitly control how the UI looks and feels to users and have more control over what's allowed to be queried for specific contexts. This is especially helpful if they are less familiar with the data warehouse (e.g. tables, schemas, column names, etc.). For example, you may want to curate which fields, tables, and joins are allowed to be used together or perhaps there is a field calculation that has different logic based on the context that it's getting queried with. Topics will also enable you to manage row-level security, force default behaviors (filters, joins, etc.), and overwrite model and relationship logic if necessary.

    In the context of SQL, topics can be curated to influence all elements of generated SQL.
  </Accordion>
</AccordionGroup>

## Inspecting query SQL

A great way to learn what Omni is doing is to see the SQL generated when you build a query. You can view the generated SQL by opening a workbook.

For every query, Omni generates two layers of SQL:

* [SQL wrapped in Omni helper functions](#sql-wrapped-in-omni-helper-functions)
* [Dialect SQL executed against the database](#dialect-sql-executed-against-the-database)

### SQL wrapped in Omni helper functions

This layer contains [Omni's accelerator functions](/analyze-explore/sql#omni-sql-operators) and is optimized for cache performance and readability. You can inspect this SQL by clicking the **SQL** button in a workbook query tab:

In this example, the SQL looks like this:

```sql SQL with Omni helper functions theme={null}
SELECT
  OMNI_SUM(${order_items.sale_price}) AS "order_items.total_sale_price",
  OMNI_DATE("CREATED_AT") AS "order_items.created_at[date]"
FROM "ORDER_ITEMS" AS "order_items"
WHERE ${order_items.status} NOT IN ('Returned', 'Cancelled') OR ${order_items.status} IS NULL
GROUP BY 2
ORDER BY 2 NULLS FIRST
```

### Dialect SQL executed against the database

This layer of SQL is written in the same dialect used by the database backing the connection in Omni. All field references and Omni functions will be translated to the flavor of SQL used by your database. In fact, you could copy this SQL query and run it in another IDE pointed at the database.

Users with the Querier or higher connection role can view the dialect SQL by toggling the [**Inspector** on in a workbook query tab](/analyze-explore/workbook-inspector). Restricted Queriers can also view dialect SQL if the **View SQL** granular permission is enabled on their [custom role](/administration/users/custom-roles).

In this example, the SQL looks like this:

```sql Dialect SQL theme={null}
SELECT
  COALESCE(SUM("SALE_PRICE"), 0) AS "order_items.total_sale_price",
  DATE_TRUNC('DAY', "CREATED_AT") AS "order_items.created_at[date]__raw",
  TO_CHAR(DATE_TRUNC('DAY', "CREATED_AT"), 'YYYY-MM-DD') AS "order_items.created_at[date]"
FROM "ORDER_ITEMS" AS "order_items"
WHERE "STATUS" NOT IN ('Returned', 'Cancelled') OR "STATUS" IS NULL
GROUP BY 2
ORDER BY 2 NULLS FIRST
```

## Examples

Let's look at a few examples to bring everything together. Click the following dropdowns to view the examples, each of which contains a clip of a workbook interaction that builds the [Omni-wrapped SQL](#sql-wrapped-in-omni-helper-functions) for a query and its corresponding [dialect SQL](#dialect-sql-executed-against-the-database).

<AccordionGroup>
  <Accordion title="Adding a measure (SELECT)">
    #### Dialect SQL

    ```sql Dialect SQL theme={null}
    SELECT
      COUNT(DISTINCT "ID") AS "ecomm__order_items.total_orders"
    FROM "ECOMM"."ORDER_ITEMS" AS "ecomm__order_items"
    ```

    #### SQL with Omni helper functions
  </Accordion>

  <Accordion title="Adding a dimension (SELECT, GROUP BY)">
    #### Dialect SQL

    ```sql Dialect SQL theme={null}
    SELECT
      TO_CHAR(DATE_TRUNC('DAY', "CREATED_AT"), 'YYYY-MM-DD') AS "ecomm__order_items.created_at[date]",
      COUNT(DISTINCT "ID") AS "ecomm__order_items.total_orders"
    FROM "ECOMM"."ORDER_ITEMS" AS "ecomm__order_items"
    GROUP BY 1
    ORDER BY 1 NULLS FIRST
    ```

    #### SQL with Omni helper functions
  </Accordion>

  <Accordion title="Adding a field from another view (JOIN)">
    #### Dialect SQL

    ```sql Dialect SQL theme={null}
    SELECT
      DATE_TRUNC('DAY', "ecomm__order_items"."CREATED_AT") AS "ecomm__order_items.created_at[date]__raw",
      "ecomm__users"."STATE" AS "ecomm__users.state",
      COUNT(DISTINCT "ecomm__order_items"."ID") AS "ecomm__order_items.total_orders",
      TO_CHAR(DATE_TRUNC('DAY', "ecomm__order_items"."CREATED_AT"), 'YYYY-MM-DD') AS "ecomm__order_items.created_at[date]"
    FROM "ECOMM"."ORDER_ITEMS" AS "ecomm__order_items"
    LEFT JOIN "ECOMM"."USERS" AS "ecomm__users" ON "ecomm__order_items"."USER_ID" = "ecomm__users"."ID"
    GROUP BY 1, 2
    ORDER BY 1 NULLS FIRST
    ```

    #### SQL with Omni helper functions
  </Accordion>

  <Accordion title="Filtering by a dimension (WHERE)">
    #### Dialect SQL

    ```sql Dialect SQL theme={null}
    SELECT
      DATE_TRUNC('DAY', "ecomm__order_items"."CREATED_AT") AS "ecomm__order_items.created_at[date]__raw",
      "ecomm__users"."STATE" AS "ecomm__users.state",
      COUNT(DISTINCT "ecomm__order_items"."ID") AS "ecomm__order_items.total_orders",
      TO_CHAR(DATE_TRUNC('DAY', "ecomm__order_items"."CREATED_AT"), 'YYYY-MM-DD') AS "ecomm__order_items.created_at[date]"
    FROM "ECOMM"."ORDER_ITEMS" AS "ecomm__order_items"
    LEFT JOIN "ECOMM"."USERS" AS "ecomm__users" ON "ecomm__order_items"."USER_ID" = "ecomm__users"."ID"
    WHERE "ecomm__users"."STATE" = 'Michigan'
    GROUP BY 1, 2
    ORDER BY 1 NULLS FIRST
    ```

    #### SQL with Omni helper functions
  </Accordion>

  <Accordion title="Filtering on a measure (HAVING)">
    #### Dialect SQL

    ```sql Dialect SQL theme={null}
    SELECT
      DATE_TRUNC('DAY', "ecomm__order_items"."CREATED_AT") AS "ecomm__order_items.created_at[date]__raw",
      "ecomm__users"."STATE" AS "ecomm__users.state",
      COUNT(DISTINCT "ecomm__order_items"."ID") AS "ecomm__order_items.total_orders",
      TO_CHAR(DATE_TRUNC('DAY', "ecomm__order_items"."CREATED_AT"), 'YYYY-MM-DD') AS "ecomm__order_items.created_at[date]"
    FROM "ECOMM"."ORDER_ITEMS" AS "ecomm__order_items"
    LEFT JOIN "ECOMM"."USERS" AS "ecomm__users" ON "ecomm__order_items"."USER_ID" = "ecomm__users"."ID"
    WHERE "ecomm__users"."STATE" = 'Michigan'
    GROUP BY 1, 2
    HAVING COUNT(DISTINCT "ecomm__order_items"."ID") > 6
    ORDER BY 1 NULLS FIRST
    ```

    #### SQL with Omni helper functions
  </Accordion>
</AccordionGroup>


# Writing SQL in Omni
Source: https://docs.omni.co/analyze-explore/sql/index

Write SQL queries in Omni using Omni SQL, an abstraction layer that simplifies complex syntax with built-in operators and helpers.

Behind every query in Omni is Omni SQL - an Omni-generated version of SQL with its own operators, intended to simplify complex syntax. Omni SQL is an abstraction on top of the dialect SQL that makes writing SQL in Omni even faster than a standard SQL editor.

If you want to see the Omni SQL being generated you can always pop open the SQL dialog box by clicking the `SQL` button in the top right hand corner of the workbook or by going to the `View Menu` > `SQL`

If you leave that dialog open, you will see the generated SQL as you manipulate data through the field picker and UI gestures.

## Editing Omni SQL

The Omni SQL is editable by clicking the button in the top right hand corner of the SQL dialog box `Advanced Editor`. For field references, use `${ }` notation, fully scoped to the view, ie `${user_facts.lifetime_value//}`.

To run the new SQL query you’ve edited, you can use the keyboard shortcut on Macs `Command + Enter` or select the run (▶️) button in the top right hand corner of the workbook.

If Omni can’t interpret the SQL functions used, an error message will appear with the option to open a [SQL tab](#sql-tabs). To undo any changes to the query use the back button in the web browser.

## Tab-only fields (Query models)

Query models represent temporary or localized modifications to how data fields are interpreted or displayed within a single query’s context, rather than permanently changing the way those fields are defined in the underlying shared or workbook model.

* Query models only exist in the scope of one specific query.
* Query models do not affect the global data model or how the same field behaves in other workbooks or queries.

> In most cases, these modifications should be promoted to the workbook model rather than remain in the query model.

**For example:** When you edit Omni SQL in the Advanced Editor, Omni will try to parse it. If the resulting SQL contains fields that don’t match those that exist in the workbook or shared model, Omni will represent them in the UI by creating tab-only fields that are specific to that query. These fields can have descriptive names if you’ve given them aliases in the query, or they may appear with default names like ‘Custom Field 0’.

In the field picker, tab-only fields appear under the **Tab-only fields** section. These views and fields only exist in the current tab and are not available on other tabs in the workbook.

Once you’ve finished editing SQL in the Advanced Editor you may either promote those tab-only fields to the workbook (and then optionally promote to the shared model) or save that new query as a view (query view).

<img alt="" />

Best practice is to work out of a SQL tab which will allow you to write SQL without generating any tab-only fields.

### Omni SQL operators

Omni offers a handful of accelerator functions that make writing SQL easier and faster. When you build queries through the UI, you may see these show up in the SQL editor. You can also write these directly when hand-writing SQL.

#### Date functions

* `OMNI_DATE`
* `OMNI_DATETIME_INTERVAL_ADD`
* `OMNI_DATETIME_LITERAL`
* `OMNI_DATETIME_UNIT_INTERVAL_ADD`
* `OMNI_DAY_OF_MONTH`
* `OMNI_DAY_OF_QUARTER`
* `OMNI_DAY_OF_WEEK`
* `OMNI_DAY_OF_WEEK_INDEX`
* `OMNI_DAY_OF_YEAR`
* `OMNI_HOUR`
* `OMNI_HOUR_OF_DAY`
* `OMNI_MILLISECOND`
* `OMNI_MINUTE`
* `OMNI_MONTH`
* `OMNI_MONTH_NAME`
* `OMNI_MONTH_NUM`
* `OMNI_QUARTER`
* `OMNI_QUARTER_OF_YEAR`
* `OMNI_SECOND`
* `OMNI_WEEK`
* `OMNI_YEAR`

#### Calculations

* `OMNI_OFFSET`
* `OMNI_PERCENT_CHANGE_FROM_PREVIOUS`
* `OMNI_PERCENT_OF_PREVIOUS`
* `OMNI_PERCENT_OF_TOTAL`
* `OMNI_RANK`
* `OMNI_RUNNING_PRODUCT`
* `OMNI_RUNNING_TOTAL`

## Custom SQL filters

Enabling custom SQL filters directly from a workbook is possible by creating custom SQL queries using templated filter syntax. By implementing the [templated filter syntax](/modeling/templated-filters), you can link dashboard filters to specific fields or filter fields in the query. Although the process can be a bit complex, it offers flexibility in filtering data within SQL queries and ultimately allowing dashboard tiles based on SQL queries to have dynamic filters.

<Tabs>
  <Tab title="Setup">
    To set this up, write a SQL query like the following:

    ```sql theme={null}
    SELECT * 
      FROM order_items as items 
     WHERE 
        {{# order_items.created_at.filter }} items.created_at {{/ order_items.created_at.filter}}
        AND {{# order_items.status.filter }} items.status {{/ order_items.status.filter}}
     LIMIT 100
    ```

    This query will parse out the filters so they can be altered from the UI and mapped to dashboard filters. The field referenced in the `{{ # filter_name_here }}` has to be a field or filter field that exists in a table and referenced exactly as it is modeled. In this example, `order_items.created_at.filter` is written with the view referenced `order_items` even though the SQL query aliases the table as `items` because `order_items` is the modeled view's name.
  </Tab>

  <Tab title="Video walkthrough">
    <iframe title="Custom SQL filters" />
  </Tab>
</Tabs>

## SQL tabs

Workbooks can also be used as a SQL IDE for ad hoc analysis by selecting `Start from SQL` on a new workbook at the bottom of the page and then write queries in the appropriate dialect for your database and select the run (▶️) button. Queries generated in this state will be shown as a tab with `SQL` prefacing the title of the tab.

When using the SQL tab, the field picker will be hidden by default and fields will not be selectable. The results from the query will also not be editable (yet) however all of the chart options and other Omni functionalities will be available to users (eg. downloading, appearing on dashboards, visualizing the data etc.)

**Note:** SQL tabs run directly against your database and bypass the Omni model.


# Handling fan out with symmetric aggregates
Source: https://docs.omni.co/analyze-explore/sql/symmetric-aggregates

Use symmetric aggregates to ensure correct aggregation results in queries with table joins and fan outs, without manual adjustments.

Ensuring the correctness of data is every analyst's top priority. Symmetric aggregates allow you to ensure aggregations are always correct without needing to be aware of table relationships and fan outs.

## Understanding table fan out

To demonstrate why symmetric aggregates are so useful, let's start with explaining what table fan out means. Fan out occurs when a table containing metrics joins to a dimension table in a way that results in multiple matching rows, leading to inflated results during aggregation.

This example uses two tables - `customers` and `orders`.

Each row in the `customers` table represents a unique customer:

| customer\_id | name           | loyalty\_points |
| :----------- | :------------- | :-------------- |
| 1            | Bloberta Smith | 100             |
| 2            | Blobzilla Lee  | 200             |
| 3            | Blobina Chen   | 150             |

And each row in the `orders` table represents a unique order placed by a customer:

| order\_id | customer\_id | order\_date | amount |
| :-------- | :----------- | :---------- | :----- |
| 101       | 1            | 2025-03-25  | \$50   |
| 102       | 1            | 2025-03-26  | \$30   |
| 103       | 2            | 2025-03-27  | \$80   |
| 104       | 3            | 2025-03-28  | \$20   |
| 105       | 3            | 2025-03-29  | \$40   |

Because **one** customer can have **many** orders, this [relationship](/modeling/relationships) is `one-to-many`.

The fan out of data occurs when the tables are joined together. The following table demonstrates what a joined table might look like - note that the customer's `loyalty_points` are repeated for each order:

| customer\_id | name           | loyalty\_points | order\_id | amount |
| :----------- | :------------- | :-------------- | :-------- | :----- |
| 1            | Bloberta Smith | 100             | 101       | \$50   |
| 1            | Bloberta Smith | 100             | 102       | \$30   |
| 2            | Blobzilla Lee  | 200             | 103       | \$80   |
| 3            | Blobina Chen   | 150             | 104       | \$20   |
| 3            | Blobina Chen   | 150             | 104       | \$20   |
| 3            | Blobina Chen   | 150             | 105       | \$40   |

## Handling fan out from joins

If you were to sum the total `loyalty_points` for each customer from the join table, you'd end up overstating Bloberta's and Blobina's points by `x` the number of orders. To prevent incorrect results like these, it's important to declare a [`primary_key`](/modeling/dimensions/parameters/primary-key) for tables and, when defining joins, a [`relationship_type`](/modeling/relationships/parameters/relationship-type).

Before Omni calculates an aggregation on a fanned out table, Omni will check the table's primary key - the unique key per row - to ensure values aren't double-counted in the aggregation. If Omni detects potential for fan out, it will prompt you to define primary keys within your views.

To handle the example from the previous section, you could define the following in the model:

```yaml title="customers table" theme={null}
customer_id:
  primary_key: true
```

```yaml title="orders table" theme={null}
order_id:
  primary_key: true
```

```yaml title="Relationship between customers and orders" theme={null}
- join_from_view: customers
  join_to_view: orders
  join_type: always_left
  relationship_type: one_to_many
  on_sql: ${customers.customer_id} = ${orders.customer_id}
```

## Handling fan out in materialized tables

Let’s say you pushed the logic to join customers and orders down into your transformations layer. As this is now a single materialized table, Omni no longer has the context of the relationship between the underlying models.

In this scenario, you can leverage the [`aggregate_type`](/modeling/measures/parameters/aggregate-type) and the `custom_primary_key_sql` parameters to tell Omni how to properly aggregate on nested fields:

```yaml title="Symmetric aggregates on a materialized table" theme={null}
dimensions:
  order_id:
    primary_key: true # Defines the table's primary key
  customer_id: {}
  loyalty_points: {}
  amount: {}

measures:
  loyalty_points_sum:
    sql: ${loyalty_points}
    aggregate_type: sum_distinct_on
    custom_primary_key_sql: ${customer_id} # Dedupe on customer_id
  amount_sum:
    sql: ${amount}
    aggregate_type: sum
```

## Handling fan out from unnested columns

While similar to the [join scenario](/analyze-explore/sql/symmetric-aggregates#handling-fan-out-from-joins), this example performs an [unnest join](https://community.omni.co/t/how-can-i-unnest-my-json-data/51) on an array instead of joining two tables together. For example, this could occur when you have an `orders` table and an array of objects that represent the individual order items.

You can leverage the [`custom_primary_key_sql_for_quick_aggs`](/modeling/dimensions/parameters/custom-primary-key-sql-for-quick-aggs) parameter to handle this scenario:

```yaml title="Symmetric aggregates on an unnested column" theme={null}
dimensions:
  order_id:
    primary_key: true # Defines the table's primary key
  order_items: {} # Repeated field
  order_item_price:
    parent_field: order_items
    nested_on_field: order_items
    custom_primary_key_sql_for_quick_aggs: ${order_item_id}
    sql: price

measures:
  total_price:
    sql: ${order_item_price}
    aggregate_type: sum_distinct_on
    custom_primary_key_sql: ${order_item_id}
```

Quick aggregates for which a primary key is applicable - such as `SUM` but not `MIN` or `MAX` - based on the `order_item_price` dimension will be assigned a custom primary key of `order_item_id`. In this example, that will apply to the `total_price` measure.


# Build analyses in workbooks
Source: https://docs.omni.co/analyze-explore/workbook-basics

Learn Omni workbook basics: create tabs, query data with point-and-click or SQL, save versions, and share analyses with your team.

Omni's workbook UI is focused on asking any question of both modeled and un-modeled data in your databases. Each workbook contains one or more tabs, where data can be queried either using a UI-driven pivot-table experience or by writing SQL.

<img alt="Workbook with a stacked bar chart showing Order Items Count by date, with the field picker open on the left and multiple tabs at the bottom" />

## Creating a new workbook

To create a new workbook from the **Home** page:

<Steps>
  <Step>
    Click the **+ New** button in the top-left corner of the page.
  </Step>

  <Step>
    Select the [model](/modeling) to use for the workbook. If your organization has more than 10 models, use the search bar to locate the model you want to use.
  </Step>

  <Step>
    After you select a model, a blank workbook will display.
  </Step>
</Steps>

### Exploring a workbook

You can also create a new workbook from within an existing workbook. Clicking the **Explore** button near the top-right corner of the page creates a new copy of the workbook that you can work in without impacting the original version.

## Saving a new workbook

Workbooks can optionally be named and saved. When a workbook is saved, it will appear alongside other dashboards and workbooks in the [content system](/content/navigate).

To save a workbook:

<Steps>
  <Step>
    In the workbook, click **File > Save**.
  </Step>

  <Step>
    Give the document a **Name** and an optional **Description**:

    <img alt="" />

    By default, Omni will automatically suggest a title and description based on your analysis. These AI-generated suggestions will have a <Badge>Suggested</Badge> badge. You can change or remove them as needed.
  </Step>

  <Step>
    Use the **Locations** browser to find and select the [folder](/content/organize#folders) you want to save the document to. The document can be moved after saving if needed.

    <Note>
      **Document location determines content access**! For example, if you save a document in **My documents**, it will only be accessible to other users if you explicitly share it with them. See [Sharing content](/share) for more information.
    </Note>
  </Step>

  <Step>
    Click **Save** to save the document.
  </Step>
</Steps>

## Unsaved analyses and URL behavior

When you click **+ New** to start a fresh analysis, Omni creates an unnamed workbook in the background. Until you explicitly save it, this is considered an **unsaved analysis** — and its URL is not a stable, permanent link.

<Warning>
  Do not rely on unsaved analysis URLs as bookmarks or informal reports. These URLs are ephemeral and their behavior can change when any state of the session is saved.
</Warning>

### What happens when you save

Saving an unsaved analysis converts the unnamed workbook into a named document. When this happens, all URLs that pointed to unsaved states of that session will redirect to the newly saved document — even if the content appears unrelated.

For example: if a user has been bookmarking an unsaved analysis URL, and then saves a different analysis that was built in the same session, the original bookmarked URL will redirect to the newly saved document. This is expected behavior.

### Preserve your analysis

If you want a query to remain accessible, save it explicitly using **File > Save** and store it in an appropriate [folder](/content/navigate). Saved documents have stable, permanent URLs and appear in the content system where they can be shared with others.

## Workbook states

A workbook can be in either **View** or **Edit (draft)** mode.

When **viewing**, you're looking at the latest saved version of the workbook.

When **editing**, you're changing the workbook and changes will auto-save as you work. Changes made in draft mode will also impact the dashboard that attached to the workbook.

## Workbook versions

To view a history of all changes to the workbook, click **File > Version History** to open the **Version History** panel. You can also use this panel to restore a previous version of the workbook.

<img alt="Version History panel showing a list of changes with timestamps, authors, and a Restore button on hover" />

<Note>
  The **Version History** panel only contains changes to the workbook itself, not the workbook model or the dashboard. Open the model IDE (**Model > Model layers > Workbook**) to view workbook model changes.
</Note>

## Moving queries between workbooks

Workbook tabs can be duplicated inside workbooks, or copied to an existing workbook, or create an entirely new workbook.

### Duplicate a tab in the same workbook

From the workbook, enter edit mode, right click on the tab and select 'Duplicate'.

### Copy a tab to an existing workbook

<Note>
  Copying workbook tabs requires the [Duplicate content permission](/administration/content-permissions#default-document-abilities) to be set to **On**.

  This permission only applies if your organization has the **Duplicate** feature enabled by support — if it isn't enabled, you can copy tabs without restriction.
</Note>

Copying an existing tab allows you to share a query between workbooks.

In the workbook with the query you want to copy:

1. Enter draft mode.
2. Right-click on the tab you want to copy.
3. Select **Copy to**.
4. Click the button to copy the query ID.

Then, in the workbook you want to copy the query to:

1. Enter draft mode.
2. Click **Edit > Import tab**. In the Import Tab dialog, you can paste either:

   * The query ID (e.g., `abc123def456`)
   * The full widget URL (e.g., `https://yourinstance.omni.co/workbooks/123?w=abc123def456`)

Omni will automatically extract the query ID from the full URL if provided.

There are a couple of caveats to copying to an existing workbook:

1. A tab can only be copied to a workbook with the same connection and shared model. With [cross model tabs](/analyze-explore/cross-model-tabs#import-a-tab-from-a-workbook-on-another-model) enabled, you can also import a query tab built on another model.
2. If there are changes to the workbook model in the tab you are copying over, those will be copied into the existing workbook as well. In the event of a conflict (e.g. the same field exists on both workbooks with different definitions), the workbook copied to should win.
3. If the source workbook contains query views with names that match query views in the destination workbook, the import will be refused with an error message identifying the conflicting view(s).

   To proceed, rename the conflicting query view in the source workbook before importing the tab. This prevents data corruption where an imported tab would incorrectly read an unrelated view from the destination workbook.

### Create a new workbook with a new tab

From the dashboard, right click on the tile and click **Explore**. From the workbook, right click on the tab and click **Explore**.

### Linked tabs

From the workbook, enter edit mode, right click on the tab and select `Create linked tab`. Save the linked tab, and you can now build multiple visualizations from the same query in a workbook. This also means changing one query, you do not need repeat that change for each linked query.

* Dashboard filters can only be mapped to the source tab.
* When you delete a source tab, may either delete the linked tabs or unlink them and turn them into independent queries.


# Workbook inspector
Source: https://docs.omni.co/analyze-explore/workbook-inspector

Inspect query structure, visualization config, and generated SQL in the workbook inspector to debug and copy to your model.

The workbook inspector provides a detailed view of your query and visualization configuration, making it easy to understand how your queries are structured and copy them to your model for reuse.

The inspector is useful for:

* **Understanding query structure**: See exactly how Omni is interpreting your point-and-click query building
* **Creating sample queries**: Quickly copy queries from workbooks to topic files for AI context and example queries
* **Debugging queries**: Compare the query configuration to the generated SQL to troubleshoot issues
* **Learning YAML syntax**: See how your UI actions translate to YAML configuration for modeling

## Opening the inspector

There are two ways to open the inspector in a workbook:

* Click **View > Inspector**
* Click the <Icon icon="bug" /> icon located near the bottom left corner of the page

The inspector will open as a side panel showing the configuration for the current query:

<img alt="" />

## Inspector sections

The inspector contains a few sections:

* [**Dialect SQL**](#dialect-sql) - **Requires Querier or higher permissions, or the View SQL granular permission on a custom Restricted Querier role**. Displays the query written in the SQL dialect of the database backing the connection.
* [**Query structure**](#query-structure) - The query represented in Omni's query language
* [**Vis config**](#visualization-configuration-vis-config) - The configuration of the visualization associated with the query, if any
* [**Messages**](#ai-messages) - Information about the current AI session in the workbook, if any

### Dialect SQL

<Note>
  **Querier** permissions or higher are required to view dialect SQL. Restricted Queriers can view dialect SQL if the **View SQL** granular permission is enabled on their [custom role](/administration/users/custom-roles).
</Note>

The **Dialect SQL** section in the inspector displays the query written in the same SQL dialect as the database backing the connection. All field references and Omni functions will be translated to the flavor of SQL used by your database. In fact, you could copy this SQL query and run it in another IDE pointed at the database.

<img alt="" />

### Query structure

The **Query structure** section in the inspector displays the complete query configuration:

<img alt="" />

This can include:

* Fields selected in the query
* Base view or topic
* Filters applied to the query
* Sorts and limits
* Calculations
* Pivots
* Period-over-period settings

You can toggle between JSON and YAML formats using the format selector at the top of the section.

### Visualization configuration (vis config)

<Note>
  While the Vis Config section will be present even when viewing the results table, it may not be populated. This section of the inspector will only populate when viewing a visualization.
</Note>

The **Vis Config** section in the inspector displays the visualization settings for the current chart:

<img alt="" />

This includes:

* Chart type
* Color configuration
* Axis settings
* Series configuration
* Other visualization-specific settings

You can toggle between JSON and YAML formats using the format selector at the top of the section.

### AI messages

The **AI messages** section in the inspector displays information about the current AI session in the workbook, if one is active. If there isn't an active session, this section won't be visible. Along with the final generated query, this section includes:

* **Context passed to the LLM** - Including Omni's system instructions, model-level context, the current topic, and information about the prompting user
* **Conversation transcript** - Including user prompts, responses from the agent, tool calls and inputs, and tool results

<Tip>
  Use the information in this section to debug context issues and refine instructions for the agent.
</Tip>

## Copying configuration

Each section in the inspector includes a copy button that allows you to copy the configuration to your clipboard:

* **Query structure copy button**: Copies just the query configuration
* **Visualization config copy button**: Copies just the visualization configuration
* **Copy query and visualization YAML button** (in inspector header): Copies both the query and visualization configuration in the [sample query format](/modeling/topics/parameters/sample-queries) ready to paste into a topic file:

  <img alt="" />

### Copying queries to topics as sample queries

The YAML format in the inspector matches the structure used in topic sample queries. To add a query as a sample query to a topic:

<Steps>
  <Step>
    Build your query in a workbook.
  </Step>

  <Step>
    Open the inspector and click **Copy query and visualization YAML** in the inspector header.
  </Step>

  <Step>
    Open the model IDE and navigate to your topic file.
  </Step>

  <Step>
    Paste the copied YAML into the `sample_queries` section of your topic file.
  </Step>

  <Step>
    Add a query name and any additional parameters like `description`, `prompt`, or `ai_context`.
  </Step>
</Steps>

## Next steps

* Learn more about [sample queries in topics](/modeling/topics/parameters/sample-queries)
* Read about [building queries in workbooks](/analyze-explore/point-click-queries)
* Explore the [model IDE](/modeling/develop/guides/model-ide)


# Get AI credit controls
Source: https://docs.omni.co/api/ai-credit-controls/get-ai-credit-controls

/api/openapi.yaml get /v1/ai/credit-controls
<Note>
  **Organization Admin** permissions are required for this endpoint.
</Note>

Get the organization's AI credit controls: the downgrade and shutoff thresholds, the default per-user and per-entity-group credit limits, plus read-only context (the credit limit, usage for the current billing period, and the period bounds). This endpoint can be used for embedded instances.




# List individual entity groups' AI credit limits
Source: https://docs.omni.co/api/ai-credit-controls/list-individual-entity-groups-ai-credit-limits

/api/openapi.yaml get /v1/ai/credit-controls/entity-groups
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

List the organization's active individual embed entity-group AI credit limits, ordered by entity group id ascending.

Only entity groups with an individual limit will be returned in the response. Entity groups that use the organization default are not included.




# List individual users' AI credit limits
Source: https://docs.omni.co/api/ai-credit-controls/list-individual-users-ai-credit-limits

/api/openapi.yaml get /v1/ai/credit-controls/users
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

List the organization's active individual user AI credit limits, ordered by `userId` ascending.

Only users with an individual limit will be returned in the response.




# Set individual entity groups' AI credit limits
Source: https://docs.omni.co/api/ai-credit-controls/set-individual-entity-groups-ai-credit-limits

/api/openapi.yaml patch /v1/ai/credit-controls/entity-groups
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Set individual embed entity groups' AI credit limits in bulk. Each entry names an entity group and either sets an individual limit or removes one so the entity group follows the organization default. All entries are applied in a single transaction.


<Tip>
  To set an unlimited override for an entity group, use `creditLimit: null`. This is distinct from having the entity group follow the organization default.
</Tip>


# Set individual users' AI credit limits
Source: https://docs.omni.co/api/ai-credit-controls/set-individual-users-ai-credit-limits

/api/openapi.yaml patch /v1/ai/credit-controls/users
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Set individual users' AI credit limits in bulk. Each entry names a user and either sets an individual limit or removes one so the user follows the organization default. All entries are applied in a single transaction.




# Update AI credit controls
Source: https://docs.omni.co/api/ai-credit-controls/update-ai-credit-controls

/api/openapi.yaml patch /v1/ai/credit-controls
<Note>
  **Organization Admin** permissions are required for this endpoint.
</Note>

Update the organization's AI credit controls. This endpoint can be used for embedded instances.

All fields are optional, but at least one must be provided:

- Omit a field to leave it unchanged
- Send `null` to turn that control off (for `userDefaultCredits` and `entityGroupDefaultCredits`: unlimited by default)
- Send a non-negative number to set it




# Read individual entity groups' AI credit usage
Source: https://docs.omni.co/api/ai-credit-usage/read-individual-entity-groups-ai-credit-usage

/api/openapi.yaml post /v1/ai/credit-usage/entity-groups
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

List individual embed entity groups' (up to 1,000 unique entities per request) AI credit usage for the current billing period. Each included `entity` must have an entity group in the organization. Unknown, invalid, and duplicate `entity` values will fail the request.

Returns each entity group's credits used, in request order, plus the billing-period bounds. Entity groups with no current usage will report `0`.




# Read individual users' AI credit usage
Source: https://docs.omni.co/api/ai-credit-usage/read-individual-users-ai-credit-usage

/api/openapi.yaml post /v1/ai/credit-usage/users
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

List individual users' (up to 1,000 unique users per request) AI credit usage for the current billing period. Each user ID must be a member of the organization. Unknown, invalid, and duplicate IDs will fail the request.

Returns each user's credits used, in request order, plus the billing-period bounds. Users with no current usage will report `0`. 




# Archive an eval prompt set
Source: https://docs.omni.co/api/ai-eval/archive-an-eval-prompt-set

/api/openapi.yaml delete /v1/ai/eval/prompt-sets/{promptSetId}
Archive (soft-delete) a prompt set. Omni also attempts to cancel every in-flight agentic job associated with the set; the returned `cancelled_job_count` reports how many were cancelled. Cancellation is best-effort — the archive is committed first, so if a run-cancellation later fails the endpoint returns 500 even though the set is already archived. The call is idempotent: retrying drains any remaining runs.



# Archive an eval run
Source: https://docs.omni.co/api/ai-eval/archive-an-eval-run

/api/openapi.yaml delete /v1/ai/eval/runs/{runId}
Archive (soft-delete) an eval run. Any non-terminal per-prompt agentic jobs are cancelled as part of the archive (best-effort), and a still-RUNNING run is flipped to CANCELLED before archival. The call is idempotent; archiving an already-terminal or already-archived run is a no-op.



# Cancel an eval run
Source: https://docs.omni.co/api/ai-eval/cancel-an-eval-run

/api/openapi.yaml post /v1/ai/eval/runs/{runId}/cancel
Cancel an in-flight eval run. Marks the run cancelled first so no in-progress per-prompt job can flip it back to COMPLETE, then cancels every non-terminal agentic job associated with the run. The run is also archived as part of the cancel — the response returns the updated run inline (`status: CANCELLED`, `is_archived: true`); use `/unarchive` to surface it in the default `archived=false` list again.



# Create an eval prompt set
Source: https://docs.omni.co/api/ai-eval/create-an-eval-prompt-set

/api/openapi.yaml post /v1/ai/eval/prompt-sets
Create a new eval prompt set bound to a shared model. Initial prompts can be supplied; additional prompts can be added later via PATCH.



# Get an eval prompt set
Source: https://docs.omni.co/api/ai-eval/get-an-eval-prompt-set

/api/openapi.yaml get /v1/ai/eval/prompt-sets/{promptSetId}
Get a single prompt set with all of its prompts.



# Get an eval run
Source: https://docs.omni.co/api/ai-eval/get-an-eval-run

/api/openapi.yaml get /v1/ai/eval/runs/{runId}
Get an eval run with every per-prompt result row, including the underlying agentic job state and any scoring data.



# List eval prompt sets
Source: https://docs.omni.co/api/ai-eval/list-eval-prompt-sets

/api/openapi.yaml get /v1/ai/eval/prompt-sets
List eval prompt sets, sorted alphabetically by name. When `model_ids` is omitted, returns prompt sets for every shared model the caller can access. Requires at least the Querier role on each requested model.



# List eval runs
Source: https://docs.omni.co/api/ai-eval/list-eval-runs

/api/openapi.yaml get /v1/ai/eval/runs
List runs for a prompt set, newest first, filtered to runs whose model the caller can access. The `prompt_set_id` query parameter is required.



# Restore an archived eval prompt set
Source: https://docs.omni.co/api/ai-eval/restore-an-archived-eval-prompt-set

/api/openapi.yaml post /v1/ai/eval/prompt-sets/{promptSetId}/unarchive
Restore an archived prompt set.



# Restore an archived eval run
Source: https://docs.omni.co/api/ai-eval/restore-an-archived-eval-run

/api/openapi.yaml post /v1/ai/eval/runs/{runId}/unarchive
Restore an archived eval run.



# Start an eval run
Source: https://docs.omni.co/api/ai-eval/start-an-eval-run

/api/openapi.yaml post /v1/ai/eval/runs
Create and start a new run against an existing prompt set. The run enqueues one agentic job per prompt and begins executing immediately. Returns the newly created run with its initial per-prompt result rows.



# Update an eval prompt set
Source: https://docs.omni.co/api/ai-eval/update-an-eval-prompt-set

/api/openapi.yaml patch /v1/ai/eval/prompt-sets/{promptSetId}
Update a prompt set's name, description, and/or prompts. When `prompts` is supplied, it fully replaces the existing list — existing prompts omitted from the list are deleted, entries without an `id` are created, and entries with a matching `id` are updated in place.



# Delete a suggestion
Source: https://docs.omni.co/api/ai-model-suggestions/delete-a-suggestion

/api/openapi.yaml delete /v1/models/{modelId}/suggestions/{suggestionId}
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Permanently deletes an AI Model suggestion.




# Disable model AI suggestions schedule
Source: https://docs.omni.co/api/ai-model-suggestions/disable-model-ai-suggestions-schedule

/api/openapi.yaml delete /v1/models/{modelId}/suggestions/schedule
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Disable the daily generation schedule for AI model suggestions on a shared model.

This operation is idempotent: calling it multiple times returns success even if the schedule is already disabled.




# Dismiss a suggestion
Source: https://docs.omni.co/api/ai-model-suggestions/dismiss-a-suggestion

/api/openapi.yaml post /v1/models/{modelId}/suggestions/{suggestionId}/ignore
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Dismiss a suggestion, removing it from the active list. Dismissed suggestions can be restored using the [restore endpoint](/api/ai-model-suggestions/restore-a-dismissed-suggestion).




# Enable model AI suggestions schedule
Source: https://docs.omni.co/api/ai-model-suggestions/enable-model-ai-suggestions-schedule

/api/openapi.yaml put /v1/models/{modelId}/suggestions/schedule
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Enable the daily generation schedule for AI model suggestions on a shared model. Suggestions are generated daily at midnight in the specified timezone.

This operation is idempotent: calling it multiple times returns the persisted schedule.




# Generate model suggestions
Source: https://docs.omni.co/api/ai-model-suggestions/generate-model-suggestions

/api/openapi.yaml post /v1/models/{modelId}/suggestions/generate
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Trigger an AI suggestion generation run for the shared model and enqueue the async job. Poll the [Get status for a generation run endpoint](/api/ai-model-suggestions/get-status-for-a-generation-run) for status.

A model can have one active run at a time and a cooldown period is enforced after a successful run. See the `Retry-After` header in the response for more information.




# Get status for a generation run
Source: https://docs.omni.co/api/ai-model-suggestions/get-status-for-a-generation-run

/api/openapi.yaml get /v1/models/{modelId}/suggestions/runs/{runId}
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Retrieve the status of a specific generation run. Poll until `status` is terminal (`complete` or `failed`), then re-fetch the suggestions list.




# Get the latest generation run
Source: https://docs.omni.co/api/ai-model-suggestions/get-the-latest-generation-run

/api/openapi.yaml get /v1/models/{modelId}/suggestions/runs/latest
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Retrieve the most recent generation run for the shared model (the active run if one is in flight, otherwise the last terminal run), or `null` if none exists.




# List AI-generated suggestions
Source: https://docs.omni.co/api/ai-model-suggestions/list-ai-generated-suggestions

/api/openapi.yaml get /v1/models/{modelId}/suggestions
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Lists AI-generated suggestions for a shared model. Suggestions can be filtered by status and are returned with keyset-based pagination.

Suggestions are sorted by priority, creation date, and ID for stable pagination.




# Restore a dismissed suggestion
Source: https://docs.omni.co/api/ai-model-suggestions/restore-a-dismissed-suggestion

/api/openapi.yaml post /v1/models/{modelId}/suggestions/{suggestionId}/restore
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Restore a previously dismissed suggestion back to the active list.




# Create an AI Routine
Source: https://docs.omni.co/api/ai-routines/create-an-ai-routine

/api/openapi.yaml post /v1/ai/routines
Create a new AI Routine that will run on the specified schedule.

Each scheduled run executes once using the routine owner's permissions, and every recipient receives the same result.




# Delete an AI Routine
Source: https://docs.omni.co/api/ai-routines/delete-an-ai-routine

/api/openapi.yaml delete /v1/ai/routines/{routineId}
Delete an AI Routine. This action cannot be undone.




# Get an AI Routine
Source: https://docs.omni.co/api/ai-routines/get-an-ai-routine

/api/openapi.yaml get /v1/ai/routines/{routineId}
Retrieve details for a specific AI Routine by ID, including the status of its most recent completed run.




# List AI Routines
Source: https://docs.omni.co/api/ai-routines/list-ai-routines

/api/openapi.yaml get /v1/ai/routines
List AI Routines for the calling user, newest first. Includes routines paused by the owner or disabled by Omni, but excludes deleted routines. 

Use `pageInfo.nextCursor` from one response as the `cursor` query parameter on the next request. 




# Trigger AI Routine
Source: https://docs.omni.co/api/ai-routines/trigger-ai-routine

/api/openapi.yaml post /v1/ai/routines/{routineId}/trigger
Run an existing routine immediately, in addition to its schedule — e.g. to get an off-cycle result or verify a routine produces the email you expect.

Executes once using the routine owner's permissions and delivers the AI response to every recipient configured on the routine. Returns as soon as the run has started; the result arrives asynchronously via the routine's normal email delivery.

If a run is already in progress, the endpoint returns `409` rather than starting a second one. Manual runs that hit broken configuration will return `400` but not pause the schedule.




# Update an AI Routine
Source: https://docs.omni.co/api/ai-routines/update-an-ai-routine

/api/openapi.yaml put /v1/ai/routines/{routineId}
Update an existing AI Routine. All request fields are optional, and only supplied fields are changed. Supplying `destination` replaces the full recipient configuration.




# Cancel AI job
Source: https://docs.omni.co/api/ai/cancel-ai-job

/api/openapi.yaml post /v1/ai/jobs/{jobId}/cancel
Request cancellation of an AI job. This endpoint is idempotent — calling it on an already-cancelled or completed job returns success with the current state. 

- For `QUEUED` jobs, cancellation is immediate
- For `EXECUTING` jobs, the worker will stop after completing its current iteration
- Jobs in a `DELIVERING` state cannot be cancelled as they are already finalizing results. **Only the job owner or organization admins can cancel jobs.**




# Create AI job
Source: https://docs.omni.co/api/ai/create-ai-job

/api/openapi.yaml post /v1/ai/jobs
Submit a new AI job for asynchronous execution. The AI will analyze the prompt, generate and execute queries against the specified model, and produce a summarized answer.

Jobs are processed by a background worker and typically complete within 15–60 seconds. Use [Get AI job status](/api/ai/get-ai-job-status) to poll for status, or configure a `webhookUrl` to receive a notification when the job completes. Optionally continue an existing conversation by providing a `conversationId`.


## Dashboard creation and publishing

The AI can build and modify dashboards. A dashboard it creates is published immediately. An edit to an existing dashboard lands on that dashboard's draft. The AI can publish the draft when the prompt explicitly requests it (for example, *"fix the revenue tile and publish it"*). Publishing makes the draft live for everyone who views the dashboard.

<Note>
  Publishing takes any changes already in the draft live with it, not just the edits made by the AI in this job. The AI's response will disclose when it published a dashboard and when that publish included draft changes made by someone else.
</Note>

A publish request may be refused in the following cases:

* No draft exists on the dashboard
* The draft is stale, meaning it has been superseded by a more recent published version
* The organization requires pull requests to merge branch changes
* Publishing would disable the dashboard's scheduled deliveries. In the browser, this requires user confirmation; headless jobs refuse rather than disable deliveries silently.

## Webhook notifications

If a `webhookUrl` is configured, it will receive a `POST` with the following body when the job reaches a terminal state:

```json
{
  "event_id": "evt_550e8400_COMPLETE_1706123456",
  "jobId": "550e8400-...",
  "status": "COMPLETE",
  "result_summary": "Generated revenue report showing $1.2M total revenue",
  "metadata": { "slack_channel": "C123456" },
  "completed_at": "2025-01-24T10:30:00Z"
}
```

The request will also include the following signature headers:

* `X-Omni-Signature-Timestamp` - `unix`
* `X-Omni-Signature` - (`sha256=HMAC(timestamp.body, secret)`)

<Note>
  The webhook payload includes `result_summary` which can contain actual data values from query results. Full result detail (CSV data, query definitions, actions) requires calling the [Stream AI job results endpoint](/api/ai/stream-ai-job-results) with credentials.
</Note>


# Generate a query
Source: https://docs.omni.co/api/ai/generate-a-query

/api/openapi.yaml post /v1/ai/generate-query
Generate a structured Omni query from natural language using AI. 

For exploratory or cross-topic questions, use [Create AI job](/api/ai/create-ai-job) instead.




# Get AI Agent branding
Source: https://docs.omni.co/api/ai/get-ai-agent-branding

/api/openapi.yaml get /v1/ai/branding
Return the organization's AI Agent's [branding configuration](/ai/settings/branding), including display name, custom logo URL, and copy for AI Agent landing surfaces. Falls back to Omni's default values when custom branding hasn't been configured.




# Get AI job status
Source: https://docs.omni.co/api/ai/get-ai-job-status

/api/openapi.yaml get /v1/ai/jobs/{jobId}
Retrieve the current status and details of an AI job, including its state, progress information, and result summary.

The response fields vary by `state` — for example, `progress` is only present during `EXECUTING`, and `resultSummary` is only present when `COMPLETE`.

Poll this endpoint every 2–5 seconds until the job reaches a terminal state (`COMPLETE`, `FAILED`, or `CANCELLED`).




# Get conversation
Source: https://docs.omni.co/api/ai/get-conversation

/api/openapi.yaml get /v1/ai/conversations/{conversationId}
Retrieve a conversation with its full message history — alternating user and assistant turns. Each assistant turn carries the originating `jobId` and an `omniChatUrl` deep link.

The conversations returned by this API depend on the type of API key being used:

- Organization API keys can access any conversation in the organization
- Personal Access Tokens can only access the authenticating user's conversations




# List AI conversations
Source: https://docs.omni.co/api/ai/list-ai-conversations

/api/openapi.yaml get /v1/ai/conversations
List a user's recent AI conversations, ordered by most-recent activity. Each conversation includes an ID that can be passed as `conversationId` to subsequent [Create AI job](/api/ai/create-ai-job) requests to continue the thread.

Returns a paginated list with conversation metadata including optional names and the most recent user prompt for display purposes.




# Pick topic
Source: https://docs.omni.co/api/ai/pick-topic

/api/openapi.yaml post /v1/ai/pick-topic
Analyze a natural language prompt and determines which topic in the model is the best fit for answering the question. 

Useful as a preprocessing step before calling the [Generate AI query](/api/ai/generate-a-query) or [Create AI job](/api/ai/create-ai-job) endpoints, especially when the user's question could relate to multiple topics.




# Search Omni docs
Source: https://docs.omni.co/api/ai/search-omni-docs

/api/openapi.yaml post /v1/ai/search-omni-docs
Search the Omni documentation using AI to answer questions about Omni features, configuration, modeling, dashboards, and more. Sends a natural language question and returns a synthesized answer with source links to the relevant documentation pages.




# Stream AI job results
Source: https://docs.omni.co/api/ai/stream-ai-job-results

/api/openapi.yaml get /v1/ai/jobs/{jobId}/result
Retrieve the full result of a completed AI job, including all actions taken by the AI (queries generated, data retrieved) and the final summarized answer. 

Results are only available for jobs in `COMPLETE` state and are retained for 14 days after completion. The response is streamed directly from storage.




# API Explorer
Source: https://docs.omni.co/api/api-explorer

Interactively browse and test Omni API endpoints using the built-in API Explorer.

<Note>
  **Prefer to work from your terminal or IDE?** Omni's [CLI](/developers/cli) and [agent skills](/developers/agent-skills) wrap these REST APIs so you can query data, manage models, and automate workflows without hand-writing HTTP calls. Both are open source — browse the [CLI repo](https://github.com/exploreomni/cli) and the [agent skills repo](https://github.com/exploreomni/omni-agent-skills).
</Note>

The API Explorer is a built-in interactive interface for browsing and testing Omni's REST API endpoints. It is powered by [Swagger UI](https://swagger.io/tools/swagger-ui/) and uses the same OpenAPI specification that powers this documentation.

## Access the API Explorer

The API Explorer is available at the `/api-explorer` route on your Omni instance. For example, if your Omni instance is `https://blobsrus.omniapp.co`, the API Explorer is at:

```
https://blobsrus.omniapp.co/api-explorer
```

The API Explorer is publicly accessible and does not require authentication to view. However, you will need a valid [API key or personal access token](/api/authentication) to execute API requests from the Explorer.

## OpenAPI specification

The raw OpenAPI specification is also available at the `/openapi.json` route on any Omni instance:

```
https://blobsrus.omniapp.co/openapi.json
```

You can use this specification with third-party API tools like [Postman](https://www.postman.com/) or code generation utilities.

## Next steps

* [API authentication](/api/authentication) - Set up API keys or personal access tokens
* [Rate limits](/api/rate-limits) - Understand API rate limiting
* [Available endpoints](/api/index) - View all available API endpoints


# Delete API token
Source: https://docs.omni.co/api/api-tokens/delete-api-token

/api/openapi.yaml delete /v1/api-keys/{id}
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Permanently delete an API token. Works for all token types — Organization API keys, Personal Access Tokens (PATs), and MCP OAuth grants. This is the same as revoking a token in the Omni app.

Concurrent deletes are safe — the first caller receives `200` and the second receives `404` consistently. An Organization Admin can delete the token they authenticated with, which is useful for self-service rotation.




# Enable or disable API token
Source: https://docs.omni.co/api/api-tokens/enable-or-disable-api-token

/api/openapi.yaml put /v1/api-keys/{id}
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Disable or re-enable an API token. To permanently revoke a token, use the [Delete API token](/api/api-tokens/delete-api-token) endpoint.

This operation is **idempotent**: calling it twice with the same body produces the same result.




# List API tokens
Source: https://docs.omni.co/api/api-tokens/list-api-tokens

/api/openapi.yaml get /v1/api-keys
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

List API tokens in the organization - including Organization API keys, Personal Access Tokens, and MCP OAuth grants - with optional filtering by type. Only metadata - not actual secret values - is returned.




# Retrieve an API token
Source: https://docs.omni.co/api/api-tokens/retrieve-an-api-token

/api/openapi.yaml get /v1/api-keys/{id}
<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>

Get a single API token by its ID.




# Create/reuse draft and replace app content
Source: https://docs.omni.co/api/apps/createreuse-draft-and-replace-app-content

/api/openapi.yaml put /v2/documents/{documentId}/draft/app
<Note>
  This API is currently in development and may change.
</Note>

Create or reuse the document's main draft and replace the existing app. Use the `draftIdentifier` in the response to call the [Publish draft API](/api/documents-v2/publish-draft) and publish the changes.



# Read app content
Source: https://docs.omni.co/api/apps/read-app-content

/api/openapi.yaml get /v2/documents/{documentId}/app
<Note>
  This API is currently in development and may change.
</Note>

Read the published app content, including its HTML and settings.

The response can be used to create a draft. Read the draft state before building, as an existing draft may have diverged from the published version in the response.




# Read app content on a draft
Source: https://docs.omni.co/api/apps/read-app-content-on-a-draft

/api/openapi.yaml get /v2/documents/{documentId}/draft/{draftId}/app
<Note>
  This API is currently in development and may change.
</Note>

Read the app content on a specified draft.



# Read app content on main draft
Source: https://docs.omni.co/api/apps/read-app-content-on-main-draft

/api/openapi.yaml get /v2/documents/{documentId}/draft/app
<Note>
  This API is currently in development and may change.
</Note>

Read the app content on the document's main (non-branch) draft. If a document doesn't have a main draft, the API will return a `404`.



# Remove app from a draft
Source: https://docs.omni.co/api/apps/remove-app-from-a-draft

/api/openapi.yaml delete /v2/documents/{documentId}/draft/{draftId}/app
<Note>
  This API is currently in development and may change.
</Note>

Remove the app from an existing draft. Use the `draftIdentifier` in the response to call the [Publish draft API](/api/documents-v2/publish-draft) and publish the changes.



# Replace app content on a draft
Source: https://docs.omni.co/api/apps/replace-app-content-on-a-draft

/api/openapi.yaml put /v2/documents/{documentId}/draft/{draftId}/app
<Note>
  This API is currently in development and may change.
</Note>

Replace the app HTML on an existing draft. If the specified document does not yet have an app, one will be created. 



# API authentication
Source: https://docs.omni.co/api/authentication

Authenticate your requests to the Omni API with an API token.

## API token types

All API requests require authentication using either:

* **Organization API keys** - Created by **Organization Admins** in **Settings > API access**.
* **Personal Access Tokens (PAT)** - User-scoped tokens created in a user's **profile settings**. PATs allow individual users to use the Omni API with their own permissions. A PAT is scoped to the user who creates it and will inherit their in-app permissions.

  **Note**: If connecting to the MCP Server or CLI through OAuth, Omni will automatically create an OAuth PAT for the authenticating user. See the [MCP Server authentication documentation](/ai/mcp/authentication#oauth-authentication) or [CLI authentication documentation](/developers/cli/authentication#oauth-authentication) for more information.

### API token type comparison

Use the following table to compare API token types:

|                     | Organization API key                                                              | Personal Access Token (PAT)                                                 | CLI OAuth PAT                                                                                          | MCP OAuth PAT                                                                                          |
| ------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **What's it for**   | Systems integrations, automated workflows, and API endpoints inaccessible to PATs | Individual user workflows using any PAT-compatible API endpoint             | CLI authentication with OAuth                                                                          | Connecting to the MCP Server with OAuth                                                                |
| **Who can create**  | Organization Admins                                                               | Restricted Querier+ users                                                   | Any user                                                                                               | Any user                                                                                               |
| **Permissions**     | Organization Admin                                                                | Creating user's permissions                                                 | Creating user's permissions                                                                            | Creating user's permissions                                                                            |
| **Endpoint access** | Unlimited                                                                         | [Some restrictions](#pat-endpoint-limitations)                              | Same as PAT                                                                                            | Same as PAT                                                                                            |
| **Expiration**      | None                                                                              | None                                                                        | 8 hours (auto-refreshes)                                                                               | None                                                                                                   |
| **Where to create** | [**Settings > API access > Organization keys**](/api/authentication#create)       | [**Profile > Manage account > Generate token**](/api/authentication#create) | Automatically created during the [CLI OAuth flow](/developers/cli/authentication#oauth-authentication) | Automatically created during the [MCP OAuth flow](/ai/mcp/authentication#oauth-authentication)         |
| **Where to view**   | **Settings > API access > Organization keys**                                     | **Settings > API access > Personal tokens**                                 | Not currently visible in the app                                                                       | Not currently visible in the app - use the [List API tokens endpoint](/api/api-tokens/list-api-tokens) |

### PAT endpoint limitations

PATs cannot be used for authentication with the following endpoints:

* [Document export](/api/content-migration/export-dashboard)
* [Document import](/api/content-migration/import-dashboard)
* [Create email only user](/api/schedule-recipients/manage-email-only-user)
* [Bulk create mail-only users](/api/schedule-recipients/bulk-manage-email-only-users)
* All SCIM **user** & **user group** endpoints

An Organization API key is required to use these endpoints.

## Authorization header

Include your token in the `Authorization` header as: `Bearer YOUR_API_KEY`:

```bash {3} theme={null}
curl -L 'https://your-omni-org.omniapp.co/api/scim/v2/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_API_KEY>'
```

## API token expiration

API tokens do not expire, but they may be revoked by the user at any time. In the event that your API token is lost or compromised, you can [rotate the token](#rotate) for zero-downtime updates, or delete the API token in your Omni instance and create a new one.

API tokens are tied to the current state of the user who created them. If the creator's user attributes change or the user is revoked, the associated token will reflect that change.

## Creating API tokens

The steps to create an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.

<Tabs>
  <Tab title="Organization API key">
    <Note>
      **Organization Admin** permissions are required to create and access organization API keys.
    </Note>

    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization keys**.
      </Step>

      <Step>
        Click **Generate new key**.
      </Step>

      <Step>
        In the modal that displays, enter a descriptive name for the API key.

        **Note**: API keys will inherit the [user attributes](/administration/users/attributes) of the user who created the key. Enter something that distinguishes you as the creator, such as your initials, into the key's **Name** field to make it easy to identify who created the key. This can be helpful when troubleshooting permission issues.
      </Step>

      <Step>
        Click **Generate**.
      </Step>

      <Step>
        Copy the key. **Note**: API keys are only displayed once when created.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    <Steps>
      <Step title="Enable Personal Tokens for your Omni instance">
        First, an **Organization Admin** has to enable the **Settings > API access > Personal tokens** setting. This allows users in the instance to create PATs.
      </Step>

      <Step title="Generate a token">
        Once enabled, users with **Restricted Querier** or higher permissions can create a personal token.

        Click your Omni [user profile icon](/administration/users/your-account), then **Manage account > Generate token**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Enabling and disabling API tokens

API tokens can be temporarily disabled and re-enabled without [revoking](#revoke) them, both in the Omni UI and with the [API](/api/api-tokens/enable-or-disable-api-token). This allows you to suspend a token's access without permanently deleting it.

Disabled API tokens will remain visible in Omni and in responses from the [List API tokens](/api/api-tokens/list-api-tokens) endpoint, but they can't be used to authenticate until they are re-enabled.

The steps to rotate an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.

<Tabs>
  <Tab title="Organization API key">
    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization keys**.
      </Step>

      <Step>
        In the **Organization Keys** tab, locate the key you want to work with.
      </Step>

      <Step>
        Click **Disable** to disable the token, or **Enable** to re-enable a disabled token.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    <Steps>
      <Step>
        Navigate to **Settings > API access > Personal tokens**.
      </Step>

      <Step>
        In the **Personal tokens** tab, locate the token you want to work with.
      </Step>

      <Step>
        Click **Disable** to disable the token, or **Enable** to re-enable a disabled token.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Rotating API tokens

<Note>
  Rotation is not supported for disabled tokens, already-expired tokens, or OAuth/MCP tokens.
</Note>

Rotating an API token allows you to generate a new secret without downtime. When you rotate a token, the old secret continues working for a 24 hour grace period, allowing you to update your applications before the old secret expires.

During rotation:

* A new secret is generated and the token retains its original name
* The old secret remains valid for 24 hours
* If the token has a finite expiration date, the new token inherits it

The steps to rotate an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.

<Tabs>
  <Tab title="Organization API key">
    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization keys**.
      </Step>

      <Step>
        Locate the key you want to rotate.
      </Step>

      <Step>
        Click **Rotate** in the same row as the API key.
      </Step>

      <Step>
        When prompted, click **Confirm** to proceed with the rotation.
      </Step>

      <Step>
        Copy the new secret. **Note**: The new secret is only displayed once.
      </Step>
    </Steps>

    The old secret will continue working for a 24 hour grace period, allowing you to update your applications without disruption.
  </Tab>

  <Tab title="Personal Access Token">
    <Steps>
      <Step>
        Click your Omni [user profile icon](/administration/users/your-account) in the top right corner.
      </Step>

      <Step>
        Click **Manage account**.
      </Step>

      <Step>
        Locate the **Personal API token** section.
      </Step>

      <Step>
        Click **Rotate**.
      </Step>

      <Step>
        When prompted, click **Confirm** to proceed with the rotation.
      </Step>

      <Step>
        Copy the new secret. **Note**: The new secret is only displayed once.
      </Step>
    </Steps>

    The old secret will continue working for a 24 hour grace period, allowing you to update your applications without disruption.
  </Tab>
</Tabs>

## Revoking API tokens

Unlike [disabling an API token](#enable-disable), revoking permanently deletes the API token from your Omni instance. Tokens can be revoked in the Omni app using the following instructions or with the [Delete an API token endpoint](/api/api-tokens/delete-api-token).

The steps to revoke an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.

<Tabs>
  <Tab title="Organization API key">
    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization Keys**.
      </Step>

      <Step>
        Locate the API key you want to revoke.
      </Step>

      <Step>
        Click the <Icon icon="trash-can" /> (trash can) icon in the same row as the API key.
      </Step>

      <Step>
        When prompted, click **Yes, revoke** to confirm.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    Organization Admins can revoke **all** user-created PATs by disabling the **Settings > API access > Personal tokens** setting. OAuth-minted tokens (CLI and MCP OAuth PATs) are unaffected. A confirmation dialog will appear before the setting is disabled to prevent accidental revocation of all user tokens.

    To revoke a single PAT:

    <Steps>
      <Step>
        Click your Omni [user profile icon](/administration/users/your-account) in the top right corner.
      </Step>

      <Step>
        Click **Manage account**.
      </Step>

      <Step>
        Locate the **Personal API token** section.
      </Step>

      <Step>
        Click the <Icon icon="trash-can" /> (trash can) icon.
      </Step>

      <Step>
        When prompted, click **Yes, revoke** to confirm.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Introspecting token capabilities

The [Who Am I endpoint](/api/who-am-i) allows you to discover your token's identity, scope, and permissions without attempting an action. This is useful for CLIs, agents, and client applications that need to determine their capabilities upfront. For example, checking which models a token has access to or whether a token has Organization Admin permissions.

See the [Who Am I endpoint documentation](/api/who-am-i) for more information.


# Omni API base URL
Source: https://docs.omni.co/api/base-url

Find the base URL for requests to your Omni instance's REST APIs.

The API base URL is the same as the URL you use to log in to Omni. For example, if you log in using `https://blobsrus.omniapp.co`, your base URL will be `https://blobsrus.omniapp.co/api`.

Only HTTPS calls are accepted.


# Omni CLI
Source: https://docs.omni.co/api/cli

Prefer the terminal? The Omni CLI wraps these REST APIs so you can query data, manage models, and automate workflows without hand-writing HTTP calls.

Prefer to work from your terminal or IDE? The [Omni CLI](/developers/cli) wraps these REST APIs so you can query data, manage models, and automate workflows without hand-writing HTTP calls. It's open source.

The CLI lets you manage your Omni instance from the terminal — run queries, manage models and content, administer users and permissions, and automate workflows in scripts or CI/CD. All commands return JSON, so they pipe cleanly into tools like `jq`.

See the [installation guide](/developers/cli/install) to get started, then the [quickstart](/developers/cli/quickstart) to run your first commands. The source is on GitHub: [exploreomni/cli](https://github.com/exploreomni/cli).

<Tip>
  Working directly with the REST API instead? Use the [API Explorer](/api/api-explorer) to browse and test endpoints interactively.
</Tip>


# Create connection environments
Source: https://docs.omni.co/api/connection-environments/create-connection-environments

/api/openapi.yaml post /v1/connection-environments
Creates connection environments by associating environment-specific connections with a base connection



# Delete connection environment
Source: https://docs.omni.co/api/connection-environments/delete-connection-environment

/api/openapi.yaml delete /v1/connection-environments/{connectionEnvironmentId}
Deletes a connection environment by ID. Requires Connection Admin or Organization Admin permissions.




# Update connection environment
Source: https://docs.omni.co/api/connection-environments/update-connection-environment

/api/openapi.yaml put /v1/connection-environments/{connectionEnvironmentId}
Associates user attribute values with a specific connection environment, which will determine when it is used.


<Note>
  User attribute values for environment connections work in conjunction with the user attribute name and values set on the base connection, which can be defined using the [Update connection endpoint](/api/connections/update-connection).

  The base connection specifies which user attribute to evaluate, while each environment connection specifies which values of that attribute will trigger its use.
</Note>


# Create connection
Source: https://docs.omni.co/api/connections/create-connection

/api/openapi.yaml post /v1/connections
Creates a new database connection. See the **Parameters**




# Delete connection
Source: https://docs.omni.co/api/connections/delete-connection

/api/openapi.yaml delete /v1/connections/{connectionId}
<Note>
  This endpoint requires **Connection Admin** permissions.
</Note>

Archives a connection (moves it to trash). Archived connections can be restored from the trash in the Omni app.

This endpoint performs a soft delete. The connection and its associated models and content are moved to trash, and sensitive information such as passwords and keys is permanently deleted.




# Get connection
Source: https://docs.omni.co/api/connections/get-connection

/api/openapi.yaml get /v1/connections/{connectionId}
<Note>
This endpoint requires **Restricted Querier** permissions or higher.
</Note>

Fetch a single connection by ID.




# List connections
Source: https://docs.omni.co/api/connections/list-connections

/api/openapi.yaml get /v1/connections
Retrieves a list of database connections with optional filtering and sorting



# Update connection
Source: https://docs.omni.co/api/connections/update-connection

/api/openapi.yaml patch /v1/connections/{connectionId}
Update connection properties including credentials. Credentials are encrypted at rest and never returned in API responses.

This endpoint supports credential rotation for infrastructure-as-code workflows. Depending on the connection type, you can update:
- **Password-based connections** (Postgres, MySQL, etc.): Use `passwordUnencrypted` to update the password
- **BigQuery**: Use `passwordUnencrypted` to update the service account JSON
- **Snowflake**: Use `privateKey` to update the RSA private key (PEM format, minimum 2048 bits)

At least one field must be provided in the request body.




# Export dashboard
Source: https://docs.omni.co/api/content-migration/export-dashboard

/api/openapi.yaml get /unstable/documents/{dashboardId}/export
Export dashboard for migration between Omni instances

<Warning>
  This API is in beta and may have future breaking changes.
</Warning>


# Import dashboard
Source: https://docs.omni.co/api/content-migration/import-dashboard

/api/openapi.yaml post /unstable/documents/import
Import dashboard to Omni instance.


<Warning>
  This API is in beta and may have future breaking changes.
</Warning>


# Find and replace content
Source: https://docs.omni.co/api/content-validator/find-and-replace-content

/api/openapi.yaml post /v1/models/{modelId}/content-validator
Performs find/replace operations on content using the specified model.

This endpoint allows you to replace views or fields across all documents associated with the model. This is useful when renaming model elements and need to update all references.




# Validate content
Source: https://docs.omni.co/api/content-validator/validate-content

/api/openapi.yaml get /v1/models/{modelId}/content-validator
Validate all content against the model and return documents with queries and any validation issues.

This endpoint scans all documents associated with the model and identifies any fields, views, or other model elements referenced in queries that are no longer valid.

You can optionally scope validation to only content that references a specific model element (view, field, or topic) using the `find` and `find_type` parameters. This is useful when you only need to validate content using a specific element, avoiding the overhead of validating all documents.




# Retrieve content
Source: https://docs.omni.co/api/content/retrieve-content

/api/openapi.yaml get /v1/content
Retrieve paginated list of documents and folders



# Search dashboards
Source: https://docs.omni.co/api/content/search-dashboards

/api/openapi.yaml get /v1/content/search
Free-text search over the organization's dashboards.




# Check download status
Source: https://docs.omni.co/api/dashboard-downloads/check-download-status

/api/openapi.yaml get /v1/dashboards/{dashboardId}/download/{jobId}/status

Retrieve the current status of a dashboard or tile download job. Poll this endpoint to determine when the file is ready.

The response will contain one of the following statuses:

| Status        | Description                                | Next Step                                                            |
| ------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| `in_progress` | Job is still processing                    | Continue polling                                                     |
| `complete`    | File is ready                              | Call the [Download endpoint](/api/dashboard-downloads/download-file) |
| `error`       | Job failed - see `error` field for details | Review error and retry if needed                                     |

<Tip>
  We recommend the following when polling:

  * Use a reasonable polling interval (2-5 seconds)
  * Avoid polling more frequently than once per second
</Tip>


# Download file
Source: https://docs.omni.co/api/dashboard-downloads/download-file

/api/openapi.yaml get /v1/dashboards/{dashboardId}/download/{jobId}

<Note>
  Only call this endpoint when the [Check download status endpoint](/api/dashboard-downloads/check-download-status) returns a `complete` status.
</Note>

Retrieve the completed dashboard or tile download file.

The response will include appropriate headers for the file type:

* `Content-Type` -  MIME type based on format (e.g., `application/pdf`)
* `Content-Disposition` - Attachment with filename (e.g., `attachment; filename="Dashboard Name.pdf"`)
* `Content-Length` - File size in bytes (when available)


# Initiate dashboard or tile download
Source: https://docs.omni.co/api/dashboard-downloads/initiate-download

/api/openapi.yaml post /v1/dashboards/{dashboardId}/download
Start an asynchronous download job for a published dashboard, a dashboard draft, or single tile with support for multiple output formats. After starting a job, poll [Check download status](/api/dashboard-downloads/check-download-status) for completion, then retrieve the file from [Download file](/api/dashboard-downloads/download-file).

<Note>
  Only one download per dashboard per user is allowed at a time. If a download is already in progress for the specified dashboard, the request will return a `409 Conflict` response with the existing job ID.
</Note>


## Downloading drafts

A draft's unpublished content renders against the branch its currently on. Permissions and the download setting come from the published dashboard, whether you request the published version or a draft.


# Get dashboard filters and controls
Source: https://docs.omni.co/api/dashboard-filters/get-dashboard-filters-and-controls

/api/openapi.yaml get /v1/dashboards/{dashboardId}/filters
Retrieve the filter and control configuration for a dashboard, including IDs, types, current default values, and metadata.




# Update dashboard filters/controls
Source: https://docs.omni.co/api/dashboard-filters/update-dashboard-filterscontrols

/api/openapi.yaml patch /v1/dashboards/{dashboardId}/filters

Set or reset values for filters and/or controls on a dashboard. Update specific filters or controls by providing an ID.

<Note>
  Updates to published dashboards go through a [draft/publish workflow](/content/develop). If a draft already exists for the dashboard, you must set `clearExistingDraft: true` to discard it and proceed with the update.
</Note>


# Create dbt environment
Source: https://docs.omni.co/api/dbt/create-dbt-environment

/api/openapi.yaml post /v1/connections/{connectionId}/dbt/environments
Create a new [dbt environment](/integrations/dbt/environments) on the specified connection. A dbt environment allows you to connect Omni to a specific dbt project and manage dbt-related functionality within the connection context.

dbt environments can be personal (owned by a single user) or shared (owned by no one). To create:

- **A personal environment for yourself**, you'll need **Restricted Querier** permissions or higher on the associated Omni model
- **A personal environment for another user**, you'll need **Organization Admin** permissions
- **A shared environment**, you'll need **Connection Admin** or **Organization Admin** permissions




# Delete dbt configuration
Source: https://docs.omni.co/api/dbt/delete-dbt-configuration

/api/openapi.yaml delete /v1/connections/{connectionId}/dbt
<Note>
  **Connection Admin** permissions are required to use this endpoint.
</Note>

Remove the dbt configuration for the specified connection by removing the link to the dbt repository.




# Delete dbt environment
Source: https://docs.omni.co/api/dbt/delete-dbt-environment

/api/openapi.yaml delete /v1/connections/{connectionId}/dbt/environments/{environmentId}
<Note>
  This endpoint requires **Connection Admin** permissions for the connection.
</Note>

Delete an existing dbt environment from the specified connection. This action cannot be undone.




# Get dbt configuration
Source: https://docs.omni.co/api/dbt/get-dbt-configuration

/api/openapi.yaml get /v1/connections/{connectionId}/dbt
<Note>
  **Connection Admin** permissions are required to use this endpoint.
</Note>

Retrieve the dbt configuration for the specified connection.




# Get dbt exposures
Source: https://docs.omni.co/api/dbt/get-dbt-exposures

/api/openapi.yaml get /v1/models/{modelId}/dbt-exposures
<Note>
  **Connection Admin** permissions are required to use this endpoint.
</Note>

Retrieve dbt exposures for the specified model. This endpoint computes exposures on-demand by analyzing which dbt models are referenced by dashboards that use the specified model.

This enables automated retrieval of exposure data previously only available via the manual **Sync exposures** flow in Omni, making it ideal for CI/CD pipelines and automated workflows.




# List dbt environments
Source: https://docs.omni.co/api/dbt/list-dbt-environments

/api/openapi.yaml get /v1/connections/{connectionId}/dbt/environments
<Note>
  This endpoint requires **Connection Admin** permissions for the connection.
</Note>

Retrieves a list of all dbt environments configured for the specified connection.




# Set dbt environment on model branch
Source: https://docs.omni.co/api/dbt/set-dbt-environment-on-model-branch

/api/openapi.yaml post /v1/models/{modelId}/branch/{branchName}/dbt
Sets the active dbt environment on a model branch. This endpoint allows you to programmatically configure which dbt environment a branch should use, enabling CI/CD pipelines to automate dbt environment configuration before triggering schema refreshes.




# Update dbt configuration
Source: https://docs.omni.co/api/dbt/update-dbt-configuration

/api/openapi.yaml put /v1/connections/{connectionId}/dbt
<Note>
  **Connection Admin** permissions are required to use this endpoint.
</Note>

Update the dbt configuration for the specified connection.




# Update dbt environment
Source: https://docs.omni.co/api/dbt/update-dbt-environment

/api/openapi.yaml put /v1/connections/{connectionId}/dbt/environments/{environmentId}
<Note>
  This endpoint requires **Connection Admin** permissions for the connection.
</Note>

Update an existing dbt environment on the specified connection. All fields are optional; only the provided fields will be updated.




# Favorite document
Source: https://docs.omni.co/api/document-favorites/favorite-document

/api/openapi.yaml put /v1/documents/{documentId}/favorite
Add a document to a user's favorites. Only published documents can be favorited.

**Note**: Successful requests will return `204` regardless of whether the document is newly favorited or already in the user's favorites.




# List document favoriters
Source: https://docs.omni.co/api/document-favorites/list-document-favoriters

/api/openapi.yaml get /v1/documents/{documentId}/favorites
<Note>
  This endpoint requires **Manager** or **Owner** permissions on the requested document.
</Note>

Lists users who have favorited a published document, paginated and sorted by `favoritedAt`.

Use this endpoint when you need to know "who favorited document X" — for example, a content-migration script that preserves favorites when replacing a document needs to call this once per document, rather than iterating every user in the organization.




# Unfavorite document
Source: https://docs.omni.co/api/document-favorites/unfavorite-document

/api/openapi.yaml delete /v1/documents/{documentId}/favorite
Remove a document from a user's favorites. Only published documents can be unfavorited.

**Note**: Successful requests will return `204` regardless of whether the document was previously favorited or not.




# Apply label to document
Source: https://docs.omni.co/api/document-labels/apply-label-to-document

/api/openapi.yaml put /v1/documents/{documentId}/labels/{labelName}
Apply an existing label to a document. Labels must be created first via the [Create label](/api/labels/create-label) endpoint.

Documents can have multiple labels. When a new label is applied using this endpoint, the API adds it to the document's existing labels. Labels are not replaced.




# Bulk update document labels
Source: https://docs.omni.co/api/document-labels/bulk-update-document-labels

/api/openapi.yaml patch /v1/documents/{documentId}/labels
Add and/or remove multiple labels from a document in a single atomic operation.

When using this endpoint, keep in mind that:

* **All changes succeed or fail together.** No partial updates occur.
* **Label matching is case-insensitive**.
* **Requests must have at least one operation.** Either `add` or `remove` must contain at least one label.
* **Labels must already exist to be added to or removed from a document.** Create labels via the [Create label API](/api/labels/create-label).
* **Labels cannot be included in both `add` and `remove` in the same request.**
* **Organization Admin permissions are required to**:
  * Add or remove **Verified** labels
  * Add or remove **Homepage** labels


# Remove label from document
Source: https://docs.omni.co/api/document-labels/remove-label-from-document

/api/openapi.yaml delete /v1/documents/{documentId}/labels/{labelName}
Remove a label from a document.

<Note>
  This endpoint is not idempotent. If the label does not exist on the document, the API returns a `404` error.
</Note>


# Get document permissions
Source: https://docs.omni.co/api/document-permissions/get-document-permissions

/api/openapi.yaml get /v1/documents/{documentId}/permissions
Retrieve the document-level ability values (the **Abilities** toggles in the document's settings), plus the resolved permits for a specific user when `userId` is provided.




# Grant document permissions
Source: https://docs.omni.co/api/document-permissions/grant-document-permissions

/api/openapi.yaml post /v1/documents/{documentId}/permissions
Grant document permissions to users or groups.



# List all users and groups with document access
Source: https://docs.omni.co/api/document-permissions/list-all-users-and-groups-with-document-access

/api/openapi.yaml get /v1/documents/{documentId}/access-list
List all users and groups with access to a document. 

The paginated response includes a list of `principal` objects, where each entry represents a distinct access grant with its own role and settings. A `principal` may appear twice in the response if they have both `direct` access and `folder`-based access to the same document. 




# Revoke document permissions
Source: https://docs.omni.co/api/document-permissions/revoke-document-permissions

/api/openapi.yaml delete /v1/documents/{documentId}/permissions
Revoke document permissions for users or user groups.



# Update document permission settings
Source: https://docs.omni.co/api/document-permissions/update-document-permission-settings

/api/openapi.yaml put /v1/documents/{documentId}/permissions
Update the permission and [interactivity settings](/share#controlling-document-interactivity) for a document. For example, the ability to allow users to schedule or download the document's content.

**Note**: Only the fields included in the request will be updated.




# Update document permissions
Source: https://docs.omni.co/api/document-permissions/update-document-permissions

/api/openapi.yaml patch /v1/documents/{documentId}/permissions
Update existing document permissions for users or groups.



# Create document
Source: https://docs.omni.co/api/documents-v2/create-document

/api/openapi.yaml post /v2/documents
Create a brand-new document and publish it. Accepts creation metadata (`modelId`, `name`, and optional `identifier` / `description` / `folderId`) plus the same content slice as the draft patch body, including `queryPresentations`, `controls`, `settings`, and `containers`.

Tiles are addressed by their record key in `queryPresentations.data` (e.g. `"1"`, `"2"`); the server owns internal tile identity, so you never send `miniUuid`. A new document starts with a single empty seed tile at key `"1"` — write to `"1"` (or send it as `null`) to replace the seed.

Because this is the first publish of brand-new content, it is not subject to the organization's `requirePullRequestToPublish` policy (which gates edits to existing content).


## Content sections

* **`queryPresentations`** — Tabs/tiles keyed by record key. `data` is shallow-merged by key; `order` (when present) replaces the tab order.
* **`controls`** — Dashboard filters/controls keyed by control ID. `data` is shallow-merged by key (`data.{id}: null` deletes a control); `order` (when present) replaces the control order.
* **`settings`** — Dashboard settings, shallow-merged per key: `crossfilterEnabled`, `customText` (`queryError` / `queryNoResults`), `facetFilters`, `refreshInterval`, `runQueriesOn`.
* **`containers`** — The dashboard layout. When present it fully replaces the existing layout (grid / stack / page / reference containers, recursively nested).

## Migrating from v1

The v1 one-shot `PUT /v1/documents/{documentId}` maps to the v2 **Create > Patch draft > Publish** workflow. For a brand-new document, a single request to this endpoint is enough. To edit an existing document, use [Create draft and patch document](/api/documents-v2/create-draft-and-patch-document) then [Publish draft](/api/documents-v2/publish-draft).

| v1 `PUT` field                    | v2 location                                                                                          |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `modelId`                         | `modelId` (returned on read; accepted but immutable on patch)                                        |
| `name` / `description`            | `name` / `description`                                                                               |
| `facetFilters` (top-level)        | `settings.facetFilters`                                                                              |
| `refreshInterval` (top-level)     | `settings.refreshInterval`                                                                           |
| `filterConfig` / `filterOrder`    | `controls.data` / `controls.order`                                                                   |
| `documentMetadata` (presentation) | `settings.*` / `containers`                                                                          |
| `queryPresentations` (array)      | `queryPresentations.data` (keyed) + `queryPresentations.order`                                       |
| `clearExistingDraft`              | **Removed.** A pre-existing draft now returns `409`; patch that draft or publish/discard it instead. |

There is no one-shot `PATCH` endpoint for full document updates that includes identifier changes. To rename a published document's identifier, use the [Rename document identifier endpoint](/api/documents-v2/rename-document-identifier).

There is also no `narrative` field — AI summaries attach as `linked`-type query presentations. See [Create draft and patch document](/api/documents-v2/create-draft-and-patch-document#ai-summaries-via-linked-tiles) for more information.


# Create draft and patch document
Source: https://docs.omni.co/api/documents-v2/create-draft-and-patch-document

/api/openapi.yaml patch /v2/documents/{documentId}/draft
Create a new draft on the published document and apply the patch. There is no auto-publish — the response includes the new `draftIdentifier` for follow-up calls. Pass an optional `branchId` to attach the draft to a branch; omit it for a draft on the main (unpublished) workspace.


## Draft and publish workflow

Editing an existing document is a three-step flow:

1. **`PATCH /api/v2/documents/{documentId}/draft`** *(this endpoint)* — creates a new draft on the published document and applies your patch. Returns the new `draftIdentifier`.
2. *(optional)* [**`PATCH /api/v2/documents/{documentId}/draft/{draftId}`**](/api/documents-v2/patch-draft) — apply further patches to that draft.
3. [**`POST /api/v2/documents/{documentId}/draft/publish`**](/api/documents-v2/publish-draft) — publish the main draft live.

A document may have only one main draft at a time. If one already exists, this endpoint returns `409` — patch the existing draft (step 2) or publish/discard it first. This replaces v1's `clearExistingDraft` flag, which **does not exist** in v2.

A `GET` response is a valid `PATCH` body — [read the current state](/api/documents-v2/get-document-state), edit it, and submit it back verbatim.

## Addressing tiles (no `miniUuid`)

Tiles are addressed by their record key in `queryPresentations.data` (e.g. `"2"`). The server owns internal tile identity, so you never send or manage `miniUuid`:

* **New key** → a new tile is created.
* **Existing key, identical content** (a verbatim round-trip of a `GET`) → treated as a **no-op** and dropped from the patch.
* **Existing key, changed content** → the tile is updated (the server regenerates its internal identifier).
* **`linked`-type tabs** always re-resolve — they are excluded from no-op detection.
* Query presentations are immutable server-side: replace a tile by key, don't mutate it in place.
* `model_extension_id` - The query-model binding. This is read-only and managed by Omni.

`data` is **shallow-merged** by key — omitted keys are untouched; `data.{key}: null` deletes that tile. `order`, when present, replaces the tab order. `controls` and `settings` are likewise shallow-merged; `containers`, when present, fully replaces the layout.

## AI summaries via linked tiles

There is no `narrative` field. To attach an AI-style summary that reuses another tile's query, add a `linked`-type query presentation whose `sourceQueryPresentationKey` points at the source tile's record key (a string such as `"2"` — **not** a positional index into `order`):

```json
{
  "queryPresentations": {
    "data": {
      "3": {
        "type": "linked",
        "name": "Summary",
        "sourceQueryPresentationKey": "2"
      }
    }
  }
}
```

## Binding an upload as a Source tab

To bind an existing upload (created via [POST /v1/uploads](/api/uploads/upload-csv-file)) as a document Source tab:

1. [**`GET /api/v2/documents/{documentId}`**](/api/documents-v2/get-document-state) to read the document's `workbookModelId`
2. [**`POST /api/v1/uploads`**](/api/uploads/upload-csv-file) with `modelId` set to the draft's workbook model (the connection decides warehouse staging vs S3-only)
3. **`PATCH /api/v2/documents/{documentId}/draft`** *(this endpoint)* with a `csv` or `spreadsheet` tab whose `fileUploadId` is the upload ID returned in step 2
4. [**`POST /api/v2/documents/{documentId}/draft/publish`**](/api/documents-v2/publish-draft) to publish

```json
{
  "queryPresentations": {
    "data": {
      "2": {
        "type": "csv",
        "name": "Customer data",
        "fileUploadId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
      }
    }
  }
}
```

Changing `fileUploadId` on an existing tab key repoints the tab at a different upload, regenerating the tab with the new upload's data. The same endpoints for [creating documents](/api/documents-v2/create-document) and [patching existing drafts](/api/documents-v2/patch-draft) accept `fileUploadId` on `csv` / `spreadsheet` tabs.


# Get document state
Source: https://docs.omni.co/api/documents-v2/get-document-state

/api/openapi.yaml get /v2/documents/{documentId}
Retrieve the document's published state. The response can be used as-is as the request body in a call to the [Patch draft API](/api/documents-v2/patch-draft).

To read a draft's state, use [Get draft state](/api/documents-v2/get-draft-state). To read an app document's HTML, use [Read app content](/api/apps/read-app-content).


## Query tiles

Tiles in `queryPresentations.data` are keyed by a stable record key (e.g. `"1"`, `"2"`); the server uses that key to identify existing tiles on a later patch, so you never need to track any other identifier. Control IDs and container `instanceKey` / `referenceKey` values also round-trip unchanged.

## Workbook-only documents

Workbook-only documents return only the workbook-scoped fields (`name`, `description`, `queryPresentations`); the dashboard-scoped `containers`, `controls`, and `settings` are omitted until a layout exists.

## App documents

App documents return the workbook-scoped fields plus an `app` property whose `url` is the app sub-resource, where the app's HTML and settings are read and written — the document body itself doesn't include anything app-scoped. The `app` property is omitted (the document reads as workbook-only) when apps are disabled for the organization.


# Get draft state
Source: https://docs.omni.co/api/documents-v2/get-draft-state

/api/openapi.yaml get /v2/documents/{documentId}/draft/{draftId}
Read the named draft's state. The response can be used as a request body when [creating](/api/documents-v2/create-draft-and-patch-document) and [patching](/api/documents-v2/patch-draft) drafts. 




# Patch draft
Source: https://docs.omni.co/api/documents-v2/patch-draft

/api/openapi.yaml patch /v2/documents/{documentId}/draft/{draftId}
Apply a patch to an existing draft. The request body, content sections, field caps, and tile-addressing rules are identical to [Create draft and patch document](/api/documents-v2/create-draft-and-patch-document); this route does not accept `branchId`.

This endpoint doesn't create or publish drafts.




# Publish draft
Source: https://docs.omni.co/api/documents-v2/publish-draft

/api/openapi.yaml post /v2/documents/{documentId}/draft/publish
Publish the document's current main (non-branch) draft, promoting it to the published version. No request body — the draft is consumed, so the response echoes the now-published document's metadata.

Only the main draft is publishable with this endpoint. A branch-attached draft is published by [merging its branch](/api/model-branches/merge-a-branch).




# Rename document identifier
Source: https://docs.omni.co/api/documents-v2/rename-document-identifier

/api/openapi.yaml put /v2/documents/{documentId}/identifier
Rename a published document's identifier. The change is applied live and immediately. Changes do not go through the draft/publish workflow. The former identifier is recorded in the document's rename history to enable automatic redirects. Only published documents can be renamed.

The new identifier must be a valid slug and unused by any other document in the organization. If the new value is identical to the existing value (case-sensitive), the API will return a `200` but not write a history record.



# Archive draft
Source: https://docs.omni.co/api/documents/archive-draft

/api/openapi.yaml delete /v1/documents/{documentId}/draft
Archive the current draft of the specified document. Archived drafts are placed in the [**Archived** section of the **Drafts** drawer](/content/develop/drafts#archiving-drafts) in the document's workbook and retained for 30 days.

If a branch is specified, the current draft on the branch is archived.




# Create document
Source: https://docs.omni.co/api/documents/create-document

/api/openapi.yaml post /v1/documents
<Warning>
  This endpoint is deprecated. Use the [Documents v2 API](/api/documents-v2/create-document) instead.
</Warning>

Create a new document




# Create draft
Source: https://docs.omni.co/api/documents/create-draft

/api/openapi.yaml post /v1/documents/{documentId}/draft
<Warning>
  This endpoint is deprecated. Use the [Documents v2 API](/api/documents-v2/create-draft-and-patch-document) instead.
</Warning>

<Note>
  This endpoint requires **Editor** permissions or higher on the specified document.
</Note>

Create a [draft](/content/develop/drafts) of the specified document. Drafts are isolated copies of a document - including its workbook and dashboard - that can be modified without impacting the published version.

To create a draft on a [branch](/content/develop/branch-mode), include a `branchId` in the request body. Each branch can have one draft per document.

If a draft already exists for the document (or branch, if specified), the existing draft is returned instead of creating a new one.




# Delete document
Source: https://docs.omni.co/api/documents/delete-document

/api/openapi.yaml delete /v1/documents/{documentId}
Delete a document (move to Trash)



# Duplicate published document
Source: https://docs.omni.co/api/documents/duplicate-published-document

/api/openapi.yaml post /v1/documents/{documentId}/duplicate
Duplicate a published document.

<Warning>
  Only published documents can be duplicated. Attempting to duplicate a draft document will return a 404 error.
</Warning>


# Get dashboard document
Source: https://docs.omni.co/api/documents/get-dashboard-document

/api/openapi.yaml get /v1/documents/{documentId}
<Warning>
  This endpoint is deprecated. Use the [Documents v2 API](/api/documents-v2/get-document-state) instead.
</Warning>

Retrieve dashboard document configuration in a format compatible with PUT for round-trip editing. This endpoint returns all fields needed to modify and update a dashboard document.

**Note:** This endpoint only supports dashboard documents. Workbook-only documents are not supported and will return a `400 Bad Request` error.




# List document drafts
Source: https://docs.omni.co/api/documents/list-document-drafts

/api/openapi.yaml get /v1/documents/{documentId}/drafts
<Note>
  This endpoint requires **Viewer** permissions or higher on the specified document.
</Note>

List all drafts attached to a published document. A document in Omni can have up to one draft per branch plus one draft not attached to a branch.

By default, returns active drafts only. Pass `?include=archived` to include soft-deleted drafts retained for approximately 7 days.




# List document queries
Source: https://docs.omni.co/api/documents/list-document-queries

/api/openapi.yaml get /v1/documents/{documentId}/queries
Retrieve queries associated with a document by its identifier. The specified document must be a saved document with at least one query in the workbook.


<Tip>
  Check out the [Running document queries with APIs guide](/guides/api/run-document-queries) to learn how to programmatically run the queries you retrieve with this API.
</Tip>


# List documents
Source: https://docs.omni.co/api/documents/list-documents

/api/openapi.yaml get /v1/documents
List documents with pagination and filtering



# Move document
Source: https://docs.omni.co/api/documents/move-document

/api/openapi.yaml put /v1/documents/{documentId}/move
Move a document to new folder or change scope.




# Remove dashboard from document
Source: https://docs.omni.co/api/documents/remove-dashboard-from-document

/api/openapi.yaml delete /v2/documents/{documentId}/draft/{draftId}/dashboard
Remove the dashboard from an existing draft, leaving a workbook-only document. Documents that are already workbook-only will remain unchanged.

Use the [Publish draft endpoint](/api/documents-v2/publish-draft) to apply the changes from this endpoint to the published version of the document. **Note**: Schedules will be removed when the document is published.



# Transfer document ownership
Source: https://docs.omni.co/api/documents/transfer-document-ownership

/api/openapi.yaml put /v1/documents/{documentId}/transfer-ownership
<Warning>
  This endpoint is deprecated. Use the [Grant document permissions](/api/document-permissions/grant-document-permissions) and [Update document permissions](/api/document-permissions/update-document-permissions) endpoints to assign document ownership.
</Warning>

Transfer ownership of a document to another user in the organization.

To successfully transfer a document:

- The user performing the transfer must have `MANAGER` permissions or higher on the document
- The new owner must be a member of the organization AND have explicit access to the document

Upon success, the following occurs:

- The named user is granted `OWNER` role on the document
- All other users with `OWNER` role are demoted to `MANAGER` permissions on the document
- Explicit permits for the new owner are revoked, as they now have owner access
- Content search index is updated

**Note:** This operation does not modify the document's creator, and does not move a restricted document out of its current folder. Transferring to the current owner is a no-op and returns success.




# Upgrade dashboard layout
Source: https://docs.omni.co/api/documents/upgrade-dashboard-layout

/api/openapi.yaml post /v1/documents/{documentId}/upgrade
Upgrade a document to the advanced dashboard layout — the same action available in the UI under **File > Upgrade layout**.

<Note>
  This operation is idempotent. If the document already uses the advanced layout, the request is a no-op and returns `upgraded: false`.
</Note>

For published documents the upgrade runs through a draft-and-publish workflow automatically. If a draft already exists, the request returns `409` unless `clearExistingDraft` is set to `true`, which discards the existing draft before upgrading.




# Bulk update folder labels
Source: https://docs.omni.co/api/folder-labels/bulk-update-folder-labels

/api/openapi.yaml patch /v1/folders/{folderId}/labels
Add and/or remove multiple labels from a folder.

When using this endpoint, keep in mind that:

* **All changes succeed or fail together.** No partial updates occur.
* **Label matching is case-insensitive**.
* **Requests must have at least one operation.** Either `add` or `remove` must contain at least one label.
* **Labels must already exist to be added to or removed from a folder.** Create labels with the [Create label API](/api/labels/create-label).
* **Labels cannot be included in both `add` and `remove` in the same request.**
* **Organization Admin permissions** are required to add or remove **Verified** or **Homepage** labels


# Get folder permissions
Source: https://docs.omni.co/api/folder-permissions/get-folder-permissions

/api/openapi.yaml get /v1/folders/{folderId}/permissions
Retrieve folder permissions for a user



# Grant folder permissions
Source: https://docs.omni.co/api/folder-permissions/grant-folder-permissions

/api/openapi.yaml post /v1/folders/{folderId}/permissions
Grant folder permissions to users or groups



# Revoke folder permissions
Source: https://docs.omni.co/api/folder-permissions/revoke-folder-permissions

/api/openapi.yaml delete /v1/folders/{folderId}/permissions
Revoke folder permissions from users or groups



# Update folder permissions
Source: https://docs.omni.co/api/folder-permissions/update-folder-permissions

/api/openapi.yaml patch /v1/folders/{folderId}/permissions
Update existing folder permissions for users or groups



# Update organization-level folder permissions
Source: https://docs.omni.co/api/folder-permissions/update-organization-level-folder-permissions

/api/openapi.yaml put /v1/folders/{folderId}/permissions
Set the role every member of the organization holds on a folder, and/or turn [AccessBoost](/share#boosting-permissions-with-accessboost) on or off for that organization-wide access, without naming individual users or groups. The role cascades to every descendant folder and document, so a single call can re-permission an entire folder tree.

At least one of `organizationRole` or `organizationAccessBoost` is required.




# Create folder
Source: https://docs.omni.co/api/folders/create-folder

/api/openapi.yaml post /v1/folders
Create a new folder. Folders can be nested up to 7 levels.

Folder paths are automatically generated based on hierarchy. Child folder paths include the paths of their parents.




# Delete folder
Source: https://docs.omni.co/api/folders/delete-folder

/api/openapi.yaml delete /v1/folders/{folderId}
Delete a folder. By default, only empty folders can be deleted. Use the `force` parameter to recursively delete folders containing documents and sub-folders.

When `force` is enabled:

- All documents are archived (soft-delete to trash) across the folder tree
- Subfolders are deleted recursively, starting with the most deeply-nested subfolder and walking up the folder tree
- Up to 100 items (documents and subfolders) can be deleted. If a folder contains more than 100 items, the item will return a `400`. No items will be deleted.
- All operations occur in a single transaction - partial failures roll back completely
- SSO embed users cannot force-delete entity folders




# List folders
Source: https://docs.omni.co/api/folders/list-folders

/api/openapi.yaml get /v1/folders
Retrieve a paginated list of folders within an organization. Supports filtering, sorting, and cursor-based pagination.

The folders endpoint behaves differently based on the type of API key used to authenticate the request:

- **Organization-scoped API keys:** Full access to all folders. Can view any user's restricted folders with `ownerId`. Must provide `ownerId` for `scope=restricted`.
- **Personal Access Tokens (PAT):** Permission-filtered access matching the UI.
   - For `scope=organization` - Returns all organization-shared folders the user can access
   - For `scope=restricted` - Returns only the user's own restricted folders. An `ownerId` is optional; if not provided, it will be auto-inferred and the API will return only the folders belonging to PAT owner.




# Update folder
Source: https://docs.omni.co/api/folders/update-folder

/api/openapi.yaml patch /v1/folders/{folderId}
<Note>
  This endpoint requires [**Editor** permissions or higher](/share#content-access-permissions) on the folder being updated.
</Note>

Update a folder's name and/or path segment. Either or both fields can be updated in a single request.


Name-only updates will not trigger updates to descendant folders (subfolders).

However, path updates will automatically update all descendent folder paths. Consider the following folder structure:

```text title="Existing paths with /blob-shared"
.
└── blob-shared
    ├── sales      # full path: /blob-shared/sales
    └── marketing  # full path: /blob-shared/marketing
```

If the path for `blob-shared` is updated to `all-blobs`, the full paths for its descendent folders will be automatically updated:

```text title="New paths with /all-blobs"
.
└── all-blobs
    ├── sales       # full path: /all-blobs/sales
    └── marketing   # full path: /all-blobs/marketing
```


# Omni REST APIs
Source: https://docs.omni.co/api/index

Programmatically interact with your Omni instance with Omni's REST APIs.

<Note>
  **Prefer to work from your terminal or IDE?** Omni's [CLI](/developers/cli) and [agent skills](/developers/agent-skills) wrap these REST APIs so you can query data, manage models, and automate workflows without hand-writing HTTP calls. Both are open source — browse the [CLI repo](https://github.com/exploreomni/cli) and the [agent skills repo](https://github.com/exploreomni/omni-agent-skills).
</Note>

Omni's REST APIs let you manage and automate your Omni instance programmatically, including configuring database connections, building and managing semantic models, organizing documents, dashboards, and folders, running queries, provisioning users and groups, scheduling deliveries, and integrating Omni's AI.

## Overview

<Columns>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Authenticate your requests with an API token.
  </Card>

  <Card title="Base URL" icon="link" href="/api/base-url">
    Find the base URL for requests to your Omni instance.
  </Card>

  <Card title="Versioning" icon="arrow-rotate-right" href="/api/versioning">
    See how endpoints are versioned and their current status.
  </Card>

  <Card title="Rate limits" icon="circle-stop" href="/api/rate-limits">
    Understand and handle throttling behavior.
  </Card>
</Columns>

## Endpoints

**Looking for endpoint references?** Use the navigation on the left side of the page to navigate and view reference documentation.

Endpoints are grouped by resource type. For example, the **AI APIs** section contains references for endpoints related to the Omni Agent and other AI features.

## Interacting with APIs

The Omni API docs include a secure, interactive environment that you can use to test and explore API endpoints using your Omni data. You can also browse and test API endpoints using the [API Explorer](/api/api-explorer), available at `/api-explorer` on your Omni instance.

To get started, get your Omni [base URL](/api/base-url) and generate an [API key](/api/authentication).

<Warning>
  **Heads up!** Authenticated requests sent from the docs API playground or API Explorer will interact with **real data** in your Omni organization. Use caution when experimenting with the APIs. You can also set up dedicated test data before sending requests.
</Warning>

## Guides

Task-based walkthroughs for common API workflows. See the [Guides section](/guides/?tags=api) for all API guides.

<Columns>
  <Card title="Run document queries" href="/guides/api/run-document-queries">
    Programmatically run document queries
  </Card>

  <Card title="Port SQL into a workbook" href="/guides/api/port-sql-queries-omni-api">
    Build tabs and tiles with a bash script
  </Card>

  <Card title="Bulk update model YAML" href="/guides/api/bulk-update-model-yaml">
    Batch YAML updates into a single Git sync
  </Card>

  <Card title="Set up connection environments" href="/guides/api/connection-environments">
    Configure dev and prod connection environments
  </Card>

  <Card title="Build a data lineage integration" href="/guides/api/data-lineage-integration">
    Build OpenMetadata or DataHub integrations
  </Card>

  <Card title="All API guides" href="/guides/?tags=api">
    See all API guides
  </Card>
</Columns>


# Get job status
Source: https://docs.omni.co/api/jobs/get-job-status

/api/openapi.yaml get /v1/jobs/{jobId}/status
<Note>
  Currently, this endpoint only supports schema refresh jobs. Job IDs from other job types will return an error.
</Note>

Retrieves the current status of an asynchronous job. The user authenticating the request must have **read** permissions on the connection.

This endpoint is used to check the status of jobs initiated by other API calls, such as schema refreshes. Poll this endpoint to determine when the job has completed.


The response will contain one of the following statuses:

| Status      | Description                |
| ----------- | -------------------------- |
| `RUNNING`   | Job is currently executing |
| `COMPLETED` | Job finished successfully  |
| `FAILED`    | Job failed                 |

<Tip>
  We recommend the following when polling:

  * Use a reasonable polling interval (2-5 seconds)
  * Avoid polling more frequently than once per second
</Tip>


# Create label
Source: https://docs.omni.co/api/labels/create-label

/api/openapi.yaml post /v1/labels
Create a new label in the organization.

Any user can create basic labels, but **Organization Admin** permissions are required to:

- Create **Verified** labels (`verified: true`)
- Create **Homepage** labels (`homepage: true`)




# Delete label
Source: https://docs.omni.co/api/labels/delete-label

/api/openapi.yaml delete /v1/labels/{labelName}
Delete a label from the organization.

Any user can delete basic labels, but **Organization Admin** permissions are required to delete **Verified** and **Homepage** labels.


<Warning>
  Labels that are currently applied to documents cannot be deleted. You must first remove the label from all documents.
</Warning>


# Get label
Source: https://docs.omni.co/api/labels/get-label

/api/openapi.yaml get /v1/labels/{labelName}
Retrieve a single label by name.



# List labels
Source: https://docs.omni.co/api/labels/list-labels

/api/openapi.yaml get /v1/labels
Retrieve all labels in the organization.



# Update label
Source: https://docs.omni.co/api/labels/update-label

/api/openapi.yaml put /v1/labels/{labelName}
Update an existing label, including renaming, changing **Verified** status, or adding/removing it from the **Homepage**.

Users can update basic labels they created. **Organization Admin** permissions are required to modify **Verified** or **Homepage** labels, including making a label `verified` or visible on the `homepage`.




# Merge a branch
Source: https://docs.omni.co/api/model-branches/merge-a-branch

/api/openapi.yaml post /v1/models/{modelId}/branch/{branchName}/merge
Merge a model branch into the shared model.


For PR-required and [git follower](/integrations/git/follower-mode) models, direct merges via API are rejected by default as they would bypass the intended git workflow. You can use the `force_override_git_settings` parameter to override this check when necessary, but git will not be synced to avoid force-pushing to `main`.

<Warning>
  The `force_override_git_settings` parameter requires **Connection Admin** or **Organization Admin** permissions. Users with lesser permissions will receive a `403 Forbidden` error when attempting to use this parameter.
</Warning>

| Model Configuration          | Default Behavior             | With `force_override_git_settings: true` |
| ---------------------------- | ---------------------------- | ---------------------------------------- |
| No git                       | Merge succeeds, no git sync  | N/A                                      |
| Git enabled (no PR required) | Merge succeeds, syncs to git | N/A                                      |
| Git + PR required            | Rejected with 400 error      | Merge succeeds, no git sync              |
| Git + git follower           | Rejected with 400 error      | Merge succeeds, no git sync              |


# Create Git configuration
Source: https://docs.omni.co/api/model-git-configuration/create-git-configuration

/api/openapi.yaml post /v1/models/{modelId}/git
Create a new Git configuration for a shared model.




# Create or update a pull request for a model branch
Source: https://docs.omni.co/api/model-git-configuration/create-or-update-a-pull-request-for-a-model-branch

/api/openapi.yaml post /v1/models/{modelId}/git/commit
<Note>
  This endpoint requires **Modeler** or **Connection Admin** permisisons.
</Note>

Push a branch's model contents to Git and create or update a pull request. This mirrors the **Create Pull Request** / **Update Pull Request** buttons in Omni allowing API consumers and AI agents to drive the pull request workflow programmatically.

By default, the endpoint automatically detects whether the Git branch exists. If a branch doesn't exist, a successful request will create a new Git branch and open a pull request. If a branch does exist, a commit will be added to the branch.

The `allow_branch_exists` and `require_branch_exists` parameters constrain this behavior:

- **Create or update mode** (default) - Auto-detects and handles both scenarios
- **Create-only mode** (`allow_branch_exists: false`) - Fails if the Git branch already exists
- **Update-only mode** (`require_branch_exists: true`) - Fails if the Git branch doesn't exist




# Delete Git configuration
Source: https://docs.omni.co/api/model-git-configuration/delete-git-configuration

/api/openapi.yaml delete /v1/models/{modelId}/git
Remove the Git configuration from a shared model.



# Get Git configuration
Source: https://docs.omni.co/api/model-git-configuration/get-git-configuration

/api/openapi.yaml get /v1/models/{modelId}/git
Retrieve the Git configuration for a shared model.




# Sync model with Git repository
Source: https://docs.omni.co/api/model-git-configuration/sync-model-with-git-repository

/api/openapi.yaml post /v1/models/{modelId}/git/sync
Trigger a sync operation between the model and its configured Git repository.

This will pull the latest changes from the repository and apply them to the model.




# Update Git configuration
Source: https://docs.omni.co/api/model-git-configuration/update-git-configuration

/api/openapi.yaml patch /v1/models/{modelId}/git
Update the Git configuration for a shared model. Oly provided fields will be updated.



# Archive shared or extension model
Source: https://docs.omni.co/api/models/archive-shared-or-extension-model

/api/openapi.yaml delete /v1/models/{modelId}
<Note>
  **Connection Admin** permissions are required to use this endpoint.
</Note>

Archive a shared or shared extension model, including all content and child extension models built on the target. For shared models, the model's Git configuration is also removed.

This endpoint performs a soft delete - the model is recoverable from the [trash](/content/archive-restore). Restoring the model does not automatically restore its content, which must be restored separately.

Only `SHARED` and `SHARED_EXTENSION` models can be deleted with this endpoint. To delete a branch model, use the [Delete branch API](/api/models/delete-branch).




# Create model
Source: https://docs.omni.co/api/models/create-model

/api/openapi.yaml post /v1/models
Create a new model. The typical workflow for using this endpoint is:

1. Create a schema model using this endpoint
2. Use the [Refresh schema](/api/models/refresh-schema) endpoint to load the schema for the created model
3. Create shared models based on the schema model




# Create or update YAML files
Source: https://docs.omni.co/api/models/create-or-update-yaml-files

/api/openapi.yaml post /v1/models/{modelId}/yaml
Create or overwrite a YAML file for a model. The file can be a special file (`model` or `relationships`) or a YAML file ending in `.topic`, `.view`, or `.composite_topic`.

The following models cannot be edited using this endpoint:

- Schema models
- Models using git follower mode




# Delete a YAML file
Source: https://docs.omni.co/api/models/delete-a-yaml-file

/api/openapi.yaml delete /v1/models/{modelId}/yaml
Delete a topic, composite topic, or view YAML file from a model. The file must be a YAML file ending in `.topic`, `.composite_topic`, or `.view`.

The following models cannot be edited using this endpoint:

- Schema models
- Models using git follower mode




# Delete branch
Source: https://docs.omni.co/api/models/delete-branch

/api/openapi.yaml delete /v1/models/{modelId}/branch/{branchName}
Deletes a branch associated with the specified shared model.



# Delete view
Source: https://docs.omni.co/api/models/delete-view

/api/openapi.yaml delete /v1/models/{modelId}/view/{viewName}
Delete or ignores a view in a model. Use the `mode` parameter to specify the behavior of this endpoint.




# Get model AI agent actions
Source: https://docs.omni.co/api/models/get-model-ai-agent-actions

/api/openapi.yaml get /v1/models/{modelId}/ai-agent-actions
Return AI agent actions configured for a model — a unified list of sample queries and skills suitable for surfacing as suggested prompts in AI interfaces.

Sample queries come from both `model.sample_queries` and each topic's `sample_queries`. Skills come from `model.skills` and each topic's `skills`, deduped by ID with topic skills overriding model skills.

When no actions are configured at the model or topic level, `records` returns an empty array.




# Get model YAML
Source: https://docs.omni.co/api/models/get-model-yaml

/api/openapi.yaml get /v1/models/{modelId}/yaml
Retrieve the YAML representation of a model with optional filtering and mode selection.



# List model schemas
Source: https://docs.omni.co/api/models/list-model-schemas

/api/openapi.yaml get /v1/models/{modelId}/schemas
Retrieves a sorted list of all available schema names for the specified model, including physical, virtual, and dynamic schemas.



# List models
Source: https://docs.omni.co/api/models/list-models

/api/openapi.yaml get /v1/models
Retrieves a paginated list of models with their metadata.



# Migrate a model
Source: https://docs.omni.co/api/models/migrate-a-model

/api/openapi.yaml post /v1/models/{modelId}/migrate
Copy a model from one Omni connection to another by reading the source model's YAML at a specific Git ref and writing it to the target model. Supports same-organization and cross-organization migrations.

This API:

1. Reads the full model YAML from the source model's git repository at the specified `gitRef` (merged with the default branch).
2. If `branchName` is provided and the branch already exists on the target model, the API writes to that branch. If the branch doesn't exist, one is created.
3. Writes the YAML to the target model or branch, replacing its model definition.

### Requirements

To successfully migrate a model:

- The user performing the migration must have:
   - **For the source model** - **Querier**, **Modeler**, or **Connection Admin** permissions 
   - **For the target model** - **Modeler** or **Connection Admin** permissions
   - **For cross-organization migrations** - The user must be a member of both organizations
- The source model must have [git configured](/integrations/git). This is required so the API can read the model YAML from the repository.
- The target model should have an identical schema model to the source model at the instant the git ref was committed.




# Refresh schema
Source: https://docs.omni.co/api/models/refresh-schema

/api/openapi.yaml post /v1/models/{modelId}/refresh
<Note>
  This endpoint requires either **Connection Admin** or **Modeler** permissions:

  - **Modelers** can use this endpoint on connections that have exactly **one** shared model
  - **Connection Admins** can use this endpoint on any connection they are an admin of, whether the connection has one or multiple models
</Note>

Refresh the schema of the specified model. This will cause the model to reflect the latest changes to schemas, views, and fields from the data source. Schema refreshes will remove structures that are no longer present in the source, but not anything created by users.

Depending on whether the **Branch-based schema refresh** setting is configured:

- If **Branch-based schema refresh** is enabled, the `branch_id` query parameter is required. The `branch_id` is validated against the shared model.
- If **Branch-based schema refresh** isn't enabled, do not provide the `branch_id` parameter. The API will return a `400` error in this case.




# Rename model
Source: https://docs.omni.co/api/models/rename-model

/api/openapi.yaml patch /v1/models/{modelId}
<Note>
  **Connection Admin** permissions are required to rename a shared model or shared extension model. **Modeler** permissions and higher are required to rename a branch model.
</Note>

<Warning>
  Workbook models and query models cannot be renamed via this endpoint.
</Warning>

Rename a model. This endpoint allows you to programmatically rename models without using the UI, which is particularly useful for bulk operations on shared extension models created via `POST /api/v1/models`.

The new name must be unique among active models with the same `modelKind` and `baseModelId`.

**Branch-specific constraints:**

- Name must match git-compatible regex: `[\w\-/]+`
- No git ref path conflicts (e.g., cannot rename to `team` if `team/project` exists)
- Cannot rename branches with an open pull request (when `pullRequestUrl` is set) — renaming would desync Omni from the git remote




# Reset cache
Source: https://docs.omni.co/api/models/reset-cache

/api/openapi.yaml post /v1/models/{modelId}/cache_reset/{cachePolicyName}
Reset the cache for the specified cache policy.

<Note>
  `cachePolicyName` values are not validated against existing policies. Verify that the values you provide are exact matches to policies in the model.
</Note>




# Validate model
Source: https://docs.omni.co/api/models/validate-model

/api/openapi.yaml get /v1/models/{modelId}/validate
Retrieve validation issues for a model and its branches.



# Run query
Source: https://docs.omni.co/api/queries/run-query

/api/openapi.yaml post /v1/query/run
Run the query specified in the request body. Successful requests will return the data as a base64 encoded [Apache Arrow](https://arrow.apache.org/) table, allowing you to extract query results from Omni and use them elsewhere. For example, piping data to Google Sheets or leveraging data in a Python notebook.


**Encountering timeouts?** If a request takes too long, the API will return a `408 timeout` error with a body that includes a `remaining_job_ids` property. When this occurs, poll the [Wait for query results](/api/queries/wait-for-query-results) endpoint until the `timed_out` property is `false`.


# Wait for query results
Source: https://docs.omni.co/api/queries/wait-for-query-results

/api/openapi.yaml get /v1/query/wait
Poll for the results of one or more query jobs. Use this endpoint when a request to the [Run query endpoint](/api/queries/run-query) times out and returns `remaining_job_ids` in the response.

This endpoint will wait for the specified jobs to complete and return their results. If the jobs are still processing when the request times out, the response will include the remaining job IDs to poll again.




# Omni API rate limiting
Source: https://docs.omni.co/api/rate-limits

Understand Omni API rate limits and how to handle them in your integration.

The Omni API allows **60 requests per minute per API key**. When you exceed this limit, the API returns a `429 Too Many Requests` response.

If you hit the limit, we recommend implementing retry logic with exponential backoff. You can also use multiple API keys to distribute requests and increase total throughput.

<Tip>
  **Need higher limits?** <br /><br />
  You can request an increase to **500 requests per minute** for your instance. This applies to all `/api/*` endpoints except Embed Login URL generation. Contact Omni Support to discuss your requirements.
</Tip>


# Add schedule recipients
Source: https://docs.omni.co/api/schedule-recipients/add-schedule-recipients

/api/openapi.yaml put /v1/schedules/{scheduleId}/add-recipients
Add one or more recipients to an existing scheduled email task. Recipients can be specified by email address or user ID.

<Note>
  This endpoint only works with schedules that have [email destinations](/share/deliveries/email).
</Note>




# Bulk manage email-only users
Source: https://docs.omni.co/api/schedule-recipients/bulk-manage-email-only-users

/api/openapi.yaml post /v1/users/email-only/bulk
Create or update up to 20 [email-only users](/share/deliveries/email). An email-only user is a recipient of a delivery that isn't associated with an Omni account.

If Omni matches a provided email to an existing email-only user, the user will be updated according to the `userAttributes` in the request body.




# List schedule recipients
Source: https://docs.omni.co/api/schedule-recipients/list-schedule-recipients

/api/openapi.yaml get /v1/schedules/{scheduleId}/recipients
Retrieve the list of recipients for the specified schedule. Successful responses will include the recipients and details about the schedule's destination type.

To retrieve a schedule's full configuration, use the [List schedules](/api/schedules#list-schedules) endpoint.




# Manage email-only user
Source: https://docs.omni.co/api/schedule-recipients/manage-email-only-user

/api/openapi.yaml post /v1/users/email-only
Create or update an [email-only user](/share/deliveries/email). An email-only user is a recipient of a delivery that isn't associated with an Omni account.

If Omni matches the provided email to an existing email-only user, the user will be updated according to the `userAttributes` in the request body.

<Tip>
  Need to include multiple email-only users? Use the [Create or update multiple email-only users](/api/schedule-recipients/bulk-manage-email-only-users) endpoint.
</Tip>




# Remove schedule recipients
Source: https://docs.omni.co/api/schedule-recipients/remove-schedule-recipients

/api/openapi.yaml put /v1/schedules/{scheduleId}/remove-recipients
Remove one or more recipients from an existing scheduled email task. Recipients can be specified by email address or user ID.

<Note>
  This endpoint only works with schedules that have [email destinations](/share/deliveries/email).
</Note>




# Create schedule
Source: https://docs.omni.co/api/schedules/create-schedule

/api/openapi.yaml post /v1/schedules
Create a scheduled task for the specified dashboard. Supports applying filters and formatting, creating alert conditions, and triggering test deliveries.

Supports the following destinations:

- [**Email**](/share/deliveries/email)
- [**Slack**](/share/deliveries/slack) - **Note**: A Slack workspace must already be connected to Omni to use this destination type.
- [**SFTP**](/share/deliveries/sftp)
- [**Webhook**](/share/deliveries/webhooks)
- [**Amazon S3**](/share/deliveries/amazon-s3)




# Delete schedule
Source: https://docs.omni.co/api/schedules/delete-schedule

/api/openapi.yaml delete /v1/schedules/{scheduleId}
Delete a schedule.



# Get schedule
Source: https://docs.omni.co/api/schedules/get-schedule

/api/openapi.yaml get /v1/schedules/{scheduleId}
Retrieve the details of a single schedule, including its delivery destinations, recurrence configuration, and current status.


How this endpoint behaves depends on the type of API key being used:

| API Key Type          | Behavior                                                                                                                                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Personal Access Token | The user must be able to view and manage the associated dashboard. Users who can view and schedule but do not have permissions to manage schedules must also be the schedule owner to access the schedule. |
| Organization API Key  | Acts at org level with no additional permission check; optionally accepts `userId` to check permissions as a specific user.                                                                                |


# List schedules
Source: https://docs.omni.co/api/schedules/list-schedules

/api/openapi.yaml get /v1/schedules
Retrieves scheduled tasks. This endpoint supports filtering, sorting, and cursor-based pagination.

To retrieve the recipients for a schedule, use the [List schedule recipients](/api/schedule-recipients/list-schedule-recipients) endpoint.




# Pause schedule
Source: https://docs.omni.co/api/schedules/pause-schedule

/api/openapi.yaml put /v1/schedules/{scheduleId}/pause
Pause a schedule.



# Resume schedule
Source: https://docs.omni.co/api/schedules/resume-schedule

/api/openapi.yaml put /v1/schedules/{scheduleId}/resume
Resume a schedule.



# Transfer schedule ownership
Source: https://docs.omni.co/api/schedules/transfer-schedule-ownership

/api/openapi.yaml put /v1/schedules/{scheduleId}/transfer-ownership
Transfer ownership of a schedule from one user to another user in the same organization. New ownership will be immediate and can't be reversed using this endpoint.

How ownership transfer affects schedule execution depends on the type of destination the schedule uses, and for email destinations, whether the [**Personalize delivery with the recipient's user attributes**](/share/deliveries/email/personalization) for more information. is enabled:

|                                                                 | Slack, SFTP, & Webhooks | Email without personalization | Email with personalization |
| --------------------------------------------------------------- | ----------------------- | ----------------------------- | -------------------------- |
| **Future jobs are executed by...**                              | New owner               | New owner                     | Each recipient             |
| **Permissions, data access, & user attributes are based on...** | New owner               | New owner                     | Each recipient             |
| **Output is generated using...**                                | New owner access        | New owner access              | Recipient access           |


# Trigger schedule
Source: https://docs.omni.co/api/schedules/trigger-schedule

/api/openapi.yaml post /v1/schedules/{scheduleId}/trigger
Trigger the execution of a schedule on demand, outside of its regular schedule.



# Update schedule
Source: https://docs.omni.co/api/schedules/update-schedule

/api/openapi.yaml put /v1/schedules/{scheduleId}
Update the specified task. Changes to the schedule are applied to future runs. Currently running jobs are not affected.

<Note>
  Only properties included in the request are updated. Omitted properties will retain their current values.
</Note>




# Create schema refresh schedule
Source: https://docs.omni.co/api/schema-refresh-schedules/create-schema-refresh-schedule

/api/openapi.yaml post /v1/connections/{connectionId}/schedules
Create a new schema refresh schedule for the specified connection. Multiple schedules can be created for the same connection.

<Note>
  This endpoint requires Connection Admin permissions for the connection.
</Note>




# Delete schema refresh schedule
Source: https://docs.omni.co/api/schema-refresh-schedules/delete-schema-refresh-schedule

/api/openapi.yaml delete /v1/connections/{connectionId}/schedules/{scheduleId}
Delete a schema refresh schedule. This does not affect other schedules for the same connection.

 <Note>
  This endpoint requires Connection Admin permissions for the connection.
</Note>




# Get schema refresh schedule
Source: https://docs.omni.co/api/schema-refresh-schedules/get-schema-refresh-schedule

/api/openapi.yaml get /v1/connections/{connectionId}/schedules/{scheduleId}
Retrieve the details of a connection's specific schema refresh schedule.

<Note>
  This endpoint requires Connection Admin permissions for the connection.
</Note>




# List schema refresh schedules
Source: https://docs.omni.co/api/schema-refresh-schedules/list-schema-refresh-schedules

/api/openapi.yaml get /v1/connections/{connectionId}/schedules
Retrieve all schema refresh schedules configured for the specified connection. Each schedule uses a cron expression and timezone to define when the schema should be refreshed.

<Note>
  This endpoint requires Connection Admin permissions for the connection.
</Note>




# Update schema refresh schedule
Source: https://docs.omni.co/api/schema-refresh-schedules/update-schema-refresh-schedule

/api/openapi.yaml put /v1/connections/{connectionId}/schedules/{scheduleId}
Update the schedule and/or timezone for an existing schema refresh schedule.

<Note>
  This endpoint requires Connection Admin permissions for the connection.
</Note>




# Retrieve a topic
Source: https://docs.omni.co/api/topics/retrieve-a-topic

/api/openapi.yaml get /v1/models/{modelId}/topic/{topicName}
Retrieve a topic in a model by name.



# Delete an upload
Source: https://docs.omni.co/api/uploads/delete-an-upload

/api/openapi.yaml delete /v1/uploads/{uploadId}
Delete a CSV upload by its ID. This removes the file from storage and marks the record as deleted.

<Note>
  This endpoint requires **Organization Admin** permissions.
</Note>




# List uploads
Source: https://docs.omni.co/api/uploads/list-uploads

/api/openapi.yaml get /v1/uploads
List all uploads ([CSV files and spreadsheets](/analyze-explore/data-input-csvs)) in the organization with metadata and optional filtering.

This endpoint requires **Organization Admin** permissions.




# Replace upload data
Source: https://docs.omni.co/api/uploads/replace-upload-data

/api/openapi.yaml put /v1/uploads/{uploadId}
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Replace the data in an existing CSV upload. 

The view's [`uploaded_table_name`](/modeling/views/parameters/uploaded-table-name) property and references to it (returned as `refreshedModelIds`) will automatically update, but the upload's ID will remain unchanged. This means that any documents, queries, views, etc. using the upload will be re-pointed to the new data. The previous data's artifacts are left untouched.


<Warning>
  Renaming or removing columns may break content (fields, calculations, filters) referencing the old columns.
</Warning>


# Upload a CSV file
Source: https://docs.omni.co/api/uploads/upload-a-csv-file

/api/openapi.yaml post /v1/uploads
<Note>
  To use this endpoint:
  
  - The **Upload data** setting in **Settings > Content permissions** must enabled by an **Organization Admin**
  - The authenticating user must have **Restricted Querier** permissions or higher on the model the file will be uploaded to
</Note>

Upload a CSV file to create a new [data input table](/analyze-explore/data-input-csvs). The file is parsed, converted to Arrow format, uploaded to storage, written to the connection's table upload (scratch) schema, and a view is created in the specified model.

Uploaded files:

- Must be a CSV file with `.csv` extension
- Can have a maximum of 500,000 rows. Files will be truncated if this limit is exceeded.

The returned `id` can be passed as `fileUploadId` on a `csv` or `spreadsheet` queryPresentation tab via the [Documents v2 draft-patch endpoints](/api/documents-v2/create-draft-and-patch-document#binding-an-upload-as-a-source-tab) to bind the upload as a document Source tab.




# List user attributes
Source: https://docs.omni.co/api/user-attributes/list-user-attributes

/api/openapi.yaml get /v1/user-attributes
<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Retrieve all [user attribute](/administration/users/attributes) definitions in your organization, including both custom-defined and system-defined attributes.

User attributes enable row-level security filtering, personalize dashboard content, and configure per-user database credentials. This endpoint is useful for embed integrations to discover available attributes for setting values in SSO sessions.




# Assign or update user group model role
Source: https://docs.omni.co/api/user-group-model-roles/assign-or-update-user-group-model-role

/api/openapi.yaml post /v1/user-groups/{userGroupId}/model-roles
Assign or update a model role for a user group. If the user group already has a role for the specified model, this endpoint will update it to the new role. All members of the user group will inherit this role.

Model roles control what actions user group members can perform on models and connections. To manage user groups, see the [User group APIs](/api/user-groups).




# Retrieve user group model roles
Source: https://docs.omni.co/api/user-group-model-roles/retrieve-user-group-model-roles

/api/openapi.yaml get /v1/user-groups/{userGroupId}/model-roles
Retrieve the model role assignments for a user group.




# Create user group
Source: https://docs.omni.co/api/user-groups/create-user-group

/api/openapi.yaml post /scim/v2/groups
Create a [user group](/administration/users/groups). To manage model and connection role assignments for user groups, see the [User group model role APIs](/api/user-group-model-roles).




# Delete user group
Source: https://docs.omni.co/api/user-groups/delete-user-group

/api/openapi.yaml delete /scim/v2/groups/{userGroupId}
Delete the specified user group.



# List user groups
Source: https://docs.omni.co/api/user-groups/list-user-groups

/api/openapi.yaml get /scim/v2/groups
Return a list of user groups, sorted by creation time.



# Replace user group
Source: https://docs.omni.co/api/user-groups/replace-user-group

/api/openapi.yaml put /scim/v2/groups/{userGroupId}
Replace the specified user group. Per the SCIM 2.0 specification, `PUT` replaces the entire group resource, including its membership.

To add or remove individual members without replacing the full membership list, use the [Update user group](/api/user-groups/update-user-group) endpoint, which performs a partial update via `PATCH`.




# Retrieve user group
Source: https://docs.omni.co/api/user-groups/retrieve-user-group

/api/openapi.yaml get /scim/v2/groups/{userGroupId}
Retrieves a user group using its unique ID.



# Update user group
Source: https://docs.omni.co/api/user-groups/update-user-group

/api/openapi.yaml patch /scim/v2/groups/{userGroupId}
Update the specified user group by applying a list of [SCIM 2.0 patch operations](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2). Use `PATCH` to add or remove individual members, or to rename the group, without affecting other attributes.

To replace the entire group resource (including the full membership list) in a single request, use the [Replace user group](/api/user-groups/replace-user-group) endpoint.




# Assign or update user model role
Source: https://docs.omni.co/api/user-model-roles/assign-or-update-user-model-role

/api/openapi.yaml post /v1/users/{userId}/model-roles
Assign or update a model role for a user. If the user already has a role for the specified model, this endpoint will update it to the new role.

Model roles control what actions a user can perform on models and connections. To manage users, see the [User APIs](/api/users).




# Retrieve user model roles
Source: https://docs.omni.co/api/user-model-roles/retrieve-user-model-roles

/api/openapi.yaml get /v1/users/{userId}/model-roles
Retrieve the model role assignments for a user. This includes both direct role assignments and roles inherited from user group memberships.




# Create user
Source: https://docs.omni.co/api/users/create-user

/api/openapi.yaml post /scim/v2/users
Create a user.

<Tip>
  To manage model and connection role assignments for users, see the [User model role APIs](/api/user-model-roles).
</Tip>


# Delete embed user
Source: https://docs.omni.co/api/users/delete-embed-user

/api/openapi.yaml delete /scim/v2/embed/users/{userId}
Delete the specified embed user. Use the [Delete user](/api/users/delete-user) endpoint to delete standard users.



# Delete user
Source: https://docs.omni.co/api/users/delete-user

/api/openapi.yaml delete /scim/v2/users/{userId}
Delete the specified user. Use the [Delete embed user](/api/users/delete-embed-user) endpoint to delete embed users.

<Warning>
  Deleting a user revokes their membership, which is **not reversible**: their schedules are deleted (unless transferred first) and their Personal Access Tokens are disabled. See [Revoking user memberships](/administration/users/delete) for the full list of consequences before using this operation.
</Warning>




# List email-only users
Source: https://docs.omni.co/api/users/list-email-only-users

/api/openapi.yaml get /v1/users/email-only
List email-only users and their user attributes. Supports pagination and filtering.



# List embed users
Source: https://docs.omni.co/api/users/list-embed-users

/api/openapi.yaml get /scim/v2/embed/users
List embed users in the organization, sorted by creation time. Use the [users](/api/users/list-users) endpoint to retrieve standard users.




# List users
Source: https://docs.omni.co/api/users/list-users

/api/openapi.yaml get /scim/v2/users
List users in the organization, sorted by creation time. Use the [embed users](/api/users/list-embed-users) endpoint to retrieve embed users.




# Replace user
Source: https://docs.omni.co/api/users/replace-user

/api/openapi.yaml put /scim/v2/users/{userId}
Replace the specified user. Per the SCIM 2.0 specification, `PUT` replaces the entire user resource: any optional attribute omitted from the request body is reset to its default value.

To update individual attributes without affecting others, use the [Update user](/api/users/update-user) endpoint, which performs a partial update via `PATCH`.




# Retrieve embed user
Source: https://docs.omni.co/api/users/retrieve-embed-user

/api/openapi.yaml get /scim/v2/embed/users/{userId}
Retrieve an embed user using their unique ID. Use the [Retrieve user](/api/users/retrieve-user) endpoint to retrieve standard users.



# Retrieve user
Source: https://docs.omni.co/api/users/retrieve-user

/api/openapi.yaml get /scim/v2/users/{userId}
Retrieve a user using their unique ID.



# Update user
Source: https://docs.omni.co/api/users/update-user

/api/openapi.yaml patch /scim/v2/users/{userId}
Update the specified user by applying a list of [SCIM 2.0 patch operations](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2). Attributes not referenced in the request are left unchanged.

To replace the entire user resource in a single request, use the [Replace user](/api/users/replace-user) endpoint.

<Warning>
  Omni does not have a reversible "deactivated" state for users. Setting `active` to `false` revokes the user's membership, which is **not reversible**: their schedules are deleted (unless transferred first) and their Personal Access Tokens are disabled. See [Revoking user memberships](/administration/users/delete) before using this operation.
</Warning>




# Omni API versioning
Source: https://docs.omni.co/api/versioning

Learn about the versioning strategy for and current status of Omni APIs.

Omni APIs are versioned by endpoint.

In this reference, endpoints are grouped by resource type. For example, the **AI APIs** section lists the endpoints related to the Omni Agent and other AI features.

| Resource                    | Description                                                                                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Who am I?](#who-am-i)      | Retrieve the authenticated caller's identity, permissions, and API key scope.                                                                              |
| [AI](#ai)                   | Generate queries from natural language, run AI Agent jobs and routines, manage model suggestions and evals, and configure AI credit controls and branding. |
| [API tokens](#api-tokens)   | List, inspect, enable or disable, and delete organization API tokens.                                                                                      |
| [Apps](#apps)               | List, create, and edit apps                                                                                                                                |
| [Connections](#connections) | Create and manage database connections, connection environments, dbt configuration, and schema refresh schedules.                                          |
| [Content](#content-apis)    | List documents and folders, and export or import dashboards between Omni instances.                                                                        |
| [Dashboards](#dashboards)   | Download dashboards and tiles, and manage dashboard filters and controls.                                                                                  |
| [Documents](#documents)     | Create, draft, publish, and manage documents, including favorites, labels, and permissions.                                                                |
| [Folders](#folders)         | Create and manage folders and their permissions.                                                                                                           |
| [Labels](#labels)           | Create and manage labels for organizing content.                                                                                                           |
| [Models](#models)           | Create and manage semantic models, including branches, Git configuration, topics, views, and YAML files.                                                   |
| [Queries](#queries)         | Run queries and retrieve their results.                                                                                                                    |
| [Schedules](#schedules)     | Create and manage scheduled deliveries, including their runs and recipients.                                                                               |
| [Uploads](#uploads)         | Upload CSV files as data input tables and manage existing uploads.                                                                                         |
| [Users](#users)             | Provision and manage users via SCIM, including embed and email-only users, model roles, and user attributes.                                               |
| [User groups](#user-groups) | Provision and manage user groups via SCIM and their model roles.                                                                                           |

## Who am I?

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/whoami](/api/who-am-i/get-current-identity-and-permissions)</td><td>Retrieve the authenticated caller's own identity, API key scope, organization role, and resolved per-model permissions. Supports filtering to specific models.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## AI

### Branding

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/ai/branding](/api/ai/get-ai-agent-branding)</td><td>Return the organization's AI Agent's [branding configuration](/ai/settings/branding), including display name, custom logo URL, and copy for AI Agent landing surfaces.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Conversations

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/ai/conversations](/api/ai/list-ai-conversations)</td><td>List a user's recent AI conversations, ordered by most-recent activity.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/conversations/:conversationId](/api/ai/get-conversation)</td><td>Retrieve a conversation with its full message history — alternating user and assistant turns.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Credit Controls

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PATCH /v1/ai/credit-controls/users](/api/ai-credit-controls/set-individual-users-ai-credit-limits)</td><td>Set individual users' AI credit limits in bulk.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/ai/credit-controls](/api/ai-credit-controls/update-ai-credit-controls)</td><td>Update the organization's AI credit controls.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/ai/credit-controls/entity-groups](/api/ai-credit-controls/set-individual-entity-groups-ai-credit-limits)</td><td>Set individual entity groups' AI credit limits in bulk.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/credit-controls](/api/ai-credit-controls/get-ai-credit-controls)</td><td>Get the organization's current AI credit control settings, usage for the current billing period, and the billing period bounds.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/credit-controls/users](/api/ai-credit-controls/list-individual-users-ai-credit-limits)</td><td>List the organization's active individual user AI credit limits, ordered by `userId` ascending.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/credit-controls/entity-groups](/api/ai-credit-controls/list-individual-entity-groups-ai-credit-limits)</td><td>List the organization's active individual entity-group AI credit limits, ordered by entity group ID ascending.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Credit Usage

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/ai/credit-usage/users](/api/ai-credit-usage/read-individual-users-ai-credit-usage)</td><td> List individual users' AI credit usage for the current billing period.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/credit-usage/entity-groups](/api/ai-credit-usage/read-individual-entity-groups-ai-credit-usage)</td><td> List individual embed entity groups' AI credit usage for the current billing period.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Evals

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/ai/eval/prompt-sets](/api/ai-eval/create-an-eval-prompt-set)</td><td>Create a new eval prompt set bound to a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/ai/eval/prompt-sets/:promptSetId](/api/ai-eval/update-an-eval-prompt-set)</td><td>Update a prompt set's name, description, and/or prompts.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/eval/prompt-sets](/api/ai-eval/list-eval-prompt-sets)</td><td>List eval prompt sets, sorted alphabetically by name.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/eval/prompt-sets/:promptSetId](/api/ai-eval/get-an-eval-prompt-set)</td><td>Get a single prompt set with all of its prompts.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/ai/eval/prompt-sets/:promptSetId](/api/ai-eval/archive-an-eval-prompt-set)</td><td>Archive (soft-delete) a prompt set.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/eval/prompt-sets/:promptSetId/unarchive](/api/ai-eval/restore-an-archived-eval-prompt-set)</td><td>Restore an archived prompt set.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/eval/runs](/api/ai-eval/start-an-eval-run)</td><td>Create and start a new run against an existing prompt set.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/eval/runs](/api/ai-eval/list-eval-runs)</td><td>List runs for a prompt set, newest first, filtered to runs whose model the caller can access.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/eval/runs/:runId](/api/ai-eval/get-an-eval-run)</td><td>Get an eval run with every per-prompt result row, including the underlying agentic job state and any scoring data.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/eval/runs/:runId/cancel](/api/ai-eval/cancel-an-eval-run)</td><td>Cancel an in-progress eval run.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/eval/runs/:runId/unarchive](/api/ai-eval/restore-an-archived-eval-run)</td><td>Restore an archived eval run.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/ai/eval/runs/:runId](/api/ai-eval/archive-an-eval-run)</td><td>Archive (soft-delete) an eval run.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Model Suggestions

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/models/:modelId/suggestions/generate](/api/ai-model-suggestions/generate-model-suggestions)</td><td>Trigger an AI suggestion generation run for the shared model and enqueue the async job.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/suggestions](/api/ai-model-suggestions/list-ai-generated-suggestions)</td><td>List AI-generated suggestions for a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/suggestions/:suggestionId/ignore](/api/ai-model-suggestions/dismiss-a-suggestion)</td><td>Dismiss a suggestion, removing it from the active list.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/suggestions/:suggestionId/restore](/api/ai-model-suggestions/restore-a-dismissed-suggestion)</td><td>Restore a previously dismissed suggestion back to the active list.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/models/:modelId/suggestions/:suggestionId](/api/ai-model-suggestions/delete-a-suggestion)</td><td>Permanently delete a suggestion.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/suggestions/runs/latest](/api/ai-model-suggestions/get-the-latest-generation-run)</td><td>Retrieve the most recent generation run for the shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/suggestions/runs/:runId](/api/ai-model-suggestions/get-status-for-a-generation-run)</td><td>Retrieve the status of a specific generation run.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/models/:modelId/suggestions/schedule](/api/ai-model-suggestions/enable-model-ai-suggestions-schedule)</td><td>Enable the daily generation schedule for AI model suggestions on a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/models/:modelId/suggestions/schedule](/api/ai-model-suggestions/disable-model-ai-suggestions-schedule)</td><td>Disable the daily generation schedule for AI model suggestions on a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Queries and jobs

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/ai/generate-query](/api/ai/generate-a-query)</td><td>Generate a structured Omni query from natural language using AI.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/pick-topic](/api/ai/pick-topic)</td><td>Analyze a natural language prompt and determine which topic in the model is the best fit for answering the question.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/jobs](/api/ai/create-ai-job)</td><td>Submit a new AI job for asynchronous execution.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/jobs/:jobId](/api/ai/get-ai-job-status)</td><td>Retrieve the current status and details of an AI job, including its state, progress information, and result summary.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/jobs/:jobId/cancel](/api/ai/cancel-ai-job)</td><td>Request cancellation of an AI job.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/jobs/:jobId/result](/api/ai/stream-ai-job-results)</td><td>Retrieve the full result of a completed AI job, including all actions taken by the AI and the final summarized answer.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Routines

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/ai/routines](/api/ai-routines/create-an-ai-routine)</td><td>Create a new routine that will run on the specified schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/ai/routines/:routineId](/api/ai-routines/update-an-ai-routine)</td><td>Update an existing routine.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/routines](/api/ai-routines/list-ai-routines)</td><td>List routines for the calling user, newest first.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/ai/routines/:routineId](/api/ai-routines/get-an-ai-routine)</td><td>Retrieve details for a specific routine by ID, including the status of its most recent completed run.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/ai/routines/:routineId/trigger](/api/ai-routines/trigger-ai-routine)</td><td>Run an existing routine immediately, in addition to its schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/ai/routines/:routineId](/api/ai-routines/delete-an-ai-routine)</td><td>Delete a routine.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Search Omni Docs

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/ai/search-omni-docs](/api/ai/search-omni-docs)</td><td>Search the Omni docs using AI to answer questions about Omni features, configuration, modeling, dashboards, and more.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## API tokens

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PUT /v1/api-keys/:id](/api/api-tokens/enable-or-disable-api-token)</td><td>Disable or re-enable an API token.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/api-keys](/api/api-tokens/list-api-tokens)</td><td>List API token in the organization - including Organization API keys, Personal Access Tokens, and MCP OAuth grants - with optional filtering by type.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/api-keys/:id](/api/api-tokens/retrieve-an-api-token)</td><td>Retrieve a single API token by ID.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/api-keys/:id](/api/api-tokens/delete-api-token)</td><td>Permanently delete an API token.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Apps

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PUT /v2/documents/:documentId/draft/app](/api/apps/createreuse-draft-and-replace-app-content)</td><td>Create (or reuse) the document's main draft and replace the app on it.</td><td><Badge>v2 (alpha)</Badge></td></tr>
    <tr><td>[PUT /v2/documents/:documentId/draft/:draftIdentifier/app](/api/apps/replace-app-content-on-a-draft)</td><td>Replace the app HTML or settings on an existing draft.</td><td><Badge>v2 (alpha)</Badge></td></tr>
    <tr><td>[GET /v2/documents/:documentId/app](/api/apps/read-app-content)</td><td>Read the published app content.</td><td><Badge>v2 (alpha)</Badge></td></tr>
    <tr><td>[GET /v2/documents/:documentId/draft/app](/api/apps/read-app-content-on-main-draft)</td><td>Read the app content on the document's main draft.</td><td><Badge>v2 (alpha)</Badge></td></tr>
    <tr><td>[GET /v2/documents/:documentId/draft/:draftIdentifier/app](/api/apps/read-app-content-on-a-draft)</td><td>Read the app content on a named draft.</td><td><Badge>v2 (alpha)</Badge></td></tr>
    <tr><td>[DELETE /v2/documents/:documentId/draft/:draftIdentifier/app](/api/apps/remove-app-from-a-draft)</td><td>Remove an app from a draft.</td><td><Badge>v2 (alpha)</Badge></td></tr>
  </tbody>
</table>

## Connections

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/connections](/api/connections/create-connection)</td><td>Create a new database connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/connections/:connectionId](/api/connections/update-connection)</td><td>Update connection properties including credentials.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/connections](/api/connections/list-connections)</td><td>Retrieve a list of database connections with optional filtering and sorting.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/connections/:connectionId](/api/connections/get-connection)</td><td>Fetch a single connection by ID.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/connections/:connectionId](/api/connections/delete-connection)</td><td>Archive a connection (moves it to trash).</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Connection environments

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/connection-environments](/api/connection-environments/create-connection-environments)</td><td>Create a connection environment and associate it with a base connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/connection-environments/:connectionEnvironmentId](/api/connection-environments/update-connection-environment)</td><td>Associate user attribute values with a specific connection environment to determine when the environment is used.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/connection-environments/:connectionEnvironmentId](/api/connection-environments/delete-connection-environment)</td><td>Delete a connection environment by ID.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### dbt configuration

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PUT /v1/connections/:connectionId/dbt](/api/dbt/update-dbt-configuration)</td><td>Update the dbt configuration for the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/connections/:connectionId/dbt](/api/dbt/get-dbt-configuration)</td><td>Retrieve the dbt configuration for the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/connections/:connectionId/dbt](/api/dbt/delete-dbt-configuration)</td><td>Remove the dbt configuration for the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### dbt environments

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/connections/:connectionId/dbt/environments](/api/dbt/create-dbt-environment)</td><td>Create a new dbt environment on the specified connection, enabling programmatic environment management.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/connections/:connectionId/dbt/environments/:environmentId](/api/dbt/update-dbt-environment)</td><td>Update an existing dbt environment on the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/connections/:connectionId/dbt/environments](/api/dbt/list-dbt-environments)</td><td>Retrieve a list of all dbt environments configured for the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/connections/:connectionId/dbt/environments/:environmentId](/api/dbt/delete-dbt-environment)</td><td>Delete an existing dbt environment from the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Schema refreshes

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/connections/:connectionId/schedules](/api/schema-refresh-schedules/create-schema-refresh-schedule)</td><td>Create a new schema refresh schedule for the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/connections/:connectionId/schedules/:scheduleId](/api/schema-refresh-schedules/update-schema-refresh-schedule)</td><td>Update the schedule and/or timezone for an existing schema refresh schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/jobs/:jobId/status](/api/jobs/get-job-status)</td><td>Retrieve the current status of an asynchronous job.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/connections/:connectionId/schedules](/api/schema-refresh-schedules/list-schema-refresh-schedules)</td><td>Retrieve all schema refresh schedules configured for the specified connection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/connections/:connectionId/schedules/:scheduleId](/api/schema-refresh-schedules/get-schema-refresh-schedule)</td><td>Retrieve the details of a connection's specific schema refresh schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/connections/:connectionId/schedules/:scheduleId](/api/schema-refresh-schedules/delete-schema-refresh-schedule)</td><td>Delete a schema refresh schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Content

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/content](/api/content/retrieve-content)</td><td>Retrieve a paginated list of documents and folders.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/content/search](/api/content/search-dashboards)</td><td>Search dashboards by free-text keywords.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /unstable/documents/:dashboardId/export](/api/content-migration/export-dashboard)</td><td>Export a dashboard for migration between Omni instances.</td><td><Badge>unstable (beta)</Badge></td></tr>
    <tr><td>[POST /unstable/documents/import](/api/content-migration/import-dashboard)</td><td>Import a dashboard to an Omni instance.</td><td><Badge>unstable (beta)</Badge></td></tr>
  </tbody>
</table>

## Dashboards

### Downloads

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/dashboards/:dashboardId/download](/api/dashboard-downloads/initiate-download)</td><td>Start an asynchronous download job for a dashboard or single tile with support for multiple output formats.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/dashboards/:dashboardId/download/:jobId/status](/api/dashboard-downloads/check-download-status)</td><td>Retrieve the current status of a dashboard or tile download job. Poll this endpoint to determine when the file is ready.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/dashboards/:dashboardId/download/:jobId](/api/dashboard-downloads/download-file)</td><td>Retrieve the completed dashboard or tile download file.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Filters

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PATCH /v1/dashboards/:dashboardId/filters](/api/dashboard-filters/update-dashboard-filterscontrols)</td><td>Set or reset values for filters and/or controls on a dashboard.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/dashboards/:dashboardId/filters](/api/dashboard-filters/get-dashboard-filters-and-controls)</td><td>Retrieve the filter and control configuration for a dashboard.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Documents

### Draft and publish

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v2/documents](/api/documents-v2/create-document)</td><td>Create a brand-new document and publish it.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v2/documents/:documentId/draft](/api/documents-v2/create-draft-and-patch-document)</td><td>Create a new draft on the published document and apply the patch.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v2/documents/:documentId/draft/:draftId](/api/documents-v2/patch-draft)</td><td>Apply a patch to an existing draft addressed by `draftId`.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[POST /v2/documents/:documentId/draft/publish](/api/documents-v2/publish-draft)</td><td>Publish the document's current main (non-branch) draft, promoting it to the published version.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/documents/:documentId/upgrade](/api/documents/upgrade-dashboard-layout)</td><td>Upgrade a classic document to the new dashboard editor.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v2/documents/:documentId](/api/documents-v2/get-document-state)</td><td>Read the document's published state.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/documents/:documentId/drafts](/api/documents/list-document-drafts)</td><td>List all drafts attached to a published document.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v2/documents/:documentId/draft/:draftId](/api/documents-v2/get-draft-state)</td><td>Read the named draft's state.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/documents/:documentId/draft](/api/documents/archive-draft)</td><td>Archive the current draft of the specified document.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v2/documents/:documentId/draft/:draftId/dashboard](/api/documents/remove-dashboard-from-document)</td><td>Remove the dashboard from an existing draft, leaving a workbook-only document.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/documents/:documentId](/api/documents/delete-document)</td><td>Delete document (moves to Trash).</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Favorites

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PUT /v1/documents/:documentId/favorite](/api/document-favorites/favorite-document)</td><td>Add a document to a user's favorites.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/documents/:documentId/favorites](/api/document-favorites/list-document-favoriters)</td><td>List users who have favorited a published document, paginated and sorted by `favoritedAt`.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/documents/:documentId/favorite](/api/document-favorites/unfavorite-document)</td><td>Remove a document from a user's favorites.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Labels

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PATCH /v1/documents/:documentId/labels](/api/document-labels/bulk-update-document-labels)</td><td>Add and/or remove multiple labels from a document in a single atomic operation.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/documents/:documentId/labels/:labelName](/api/document-labels/apply-label-to-document)</td><td>Apply an existing label to a document.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/documents/:documentId/labels/:labelName](/api/document-labels/remove-label-from-document)</td><td>Remove an existing label from a document.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Management

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/documents](/api/documents/list-documents)</td><td>List documents with pagination and filtering.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/documents/:documentId/queries](/api/documents/list-document-queries)</td><td>Retrieve queries associated with a document by its identifier.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v2/documents/:documentId/identifier](/api/documents-v2/rename-document-identifier)</td><td>Rename a published document's identifier.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/documents/:documentId/move](/api/documents/move-document)</td><td>Move document to new folder or change scope.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/documents/:documentId/duplicate](/api/documents/duplicate-published-document)</td><td>Duplicate a published document.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/documents/:documentId/transfer-ownership](/api/documents/transfer-document-ownership)</td><td>Transfer ownership of a document to another user in the organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Permissions

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/documents/:documentId/permissions](/api/document-permissions/grant-document-permissions)</td><td>Grant document permissions to users or groups.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/documents/:documentId/permissions](/api/document-permissions/update-document-permission-settings)</td><td>Update the permission and [interactivity settings](/share#controlling-document-interactivity) for a document.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/documents/:documentId/permissions](/api/document-permissions/update-document-permissions)</td><td>Update existing document permissions for users or groups.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/documents/:documentId/access-list](/api/document-permissions/list-all-users-and-groups-with-document-access)</td><td>List all users and groups with access to a document.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/documents/:documentId/permissions](/api/document-permissions/get-document-permissions)</td><td>Retrieve the document-level ability values, plus the resolved permits for a specific user when `userId` is provided.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/documents/:documentId/permissions](/api/document-permissions/revoke-document-permissions)</td><td>Revoke document permissions for users or user groups.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Deprecated (v1)

<Warning>
  `PUT /v1/documents/:documentId` and `PATCH /v1/documents/:documentId` have been removed as of July 31, 2026 and always return a `410` error.

  The remaining endpoints below are deprecated.

  Use the `/v2/documents` APIs instead.
</Warning>

<table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>Description</th>
      <th>Version + Status</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[POST /v1/documents](/api/documents/create-document)</td>
      <td>Create a new document.</td>
      <td><Badge>v1 (deprecated)</Badge></td>
    </tr>

    <tr>
      <td>[POST /v1/documents/:documentId/draft](/api/documents/create-draft)</td>
      <td>Create a [draft](/content/develop/drafts) of the specified document.</td>
      <td><Badge>v1 (deprecated)</Badge></td>
    </tr>

    <tr>
      <td>PUT /v1/documents/:documentId</td>
      <td>Update a document with the specified identifier.</td>
      <td><Badge>v1 (removed)</Badge></td>
    </tr>

    <tr>
      <td>PATCH /v1/documents/:documentId</td>
      <td>Update the name, description, and/or identifier of a document.</td>
      <td><Badge>v1 (removed)</Badge></td>
    </tr>

    <tr>
      <td>[GET /v1/documents/:documentId](/api/documents/get-dashboard-document)</td>
      <td>Retrieve dashboard document configuration in a format compatible with PUT for round-trip editing.</td>
      <td><Badge>v1 (deprecated)</Badge></td>
    </tr>
  </tbody>
</table>

## Folders

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/folders](/api/folders/list-folders)</td><td>Retrieve a paginated list of folders within an organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/folders](/api/folders/create-folder)</td><td>Create a new folder.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/folders/:folderId](/api/folders/update-folder)</td><td>Update a folder's name and/or path segment.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/folders/:folderId](/api/folders/delete-folder)</td><td>Delete a folder.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Labels

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PATCH /v1/folders/:folderId/labels](/api/folder-labels/bulk-update-folder-labels)</td><td>Bulk add and remove labels on a folder.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Permissions

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/folders/:folderId/permissions](/api/folder-permissions/grant-folder-permissions)</td><td>Grant folder permissions to users or groups.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/folders/:folderId/permissions](/api/folder-permissions/update-organization-level-folder-permissions)</td><td>Set the organization-wide role and/or AccessBoost on a folder.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/folders/:folderId/permissions](/api/folder-permissions/update-folder-permissions)</td><td>Update existing folder permissions for users or groups.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/folders/:folderId/permissions](/api/folder-permissions/get-folder-permissions)</td><td>Retrieve folder permissions for a user.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/folders/:folderId/permissions](/api/folder-permissions/revoke-folder-permissions)</td><td>Revoke folder permissions from users or groups.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Labels

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/labels](/api/labels/create-label)</td><td>Create a new label in the organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/labels/:labelName](/api/labels/update-label)</td><td>Update an existing label.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/labels](/api/labels/list-labels)</td><td>Retrieve all labels in the organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/labels/:labelName](/api/labels/get-label)</td><td>Retrieve a single label by name.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/labels/:labelName](/api/labels/delete-label)</td><td>Delete a label from the organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Models

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/models](/api/models/create-model)</td><td>Create a new model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/models/:modelId](/api/models/rename-model)</td><td>Rename a model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/models/:modelId](/api/models/archive-shared-or-extension-model)</td><td>Move a shared or shared extension model to the trash.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/refresh](/api/models/refresh-schema)</td><td>Refresh the schema of the specified model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models](/api/models/list-models)</td><td>Retrieve a paginated list of models with their metadata.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/validate](/api/models/validate-model)</td><td>Retrieve validation issues for a model and its branches.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Branches

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/models/:modelId/branch/:branchName/merge](/api/model-branches/merge-a-branch)</td><td>Merge a model branch into the shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/branch/:branchName/dbt](/api/dbt/set-dbt-environment-on-model-branch)</td><td>Set the active dbt environment on a model branch.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/models/:modelId/branch/:branchName](/api/models/delete-branch)</td><td>Delete a branch associated with the specified shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Content validator

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/models/:modelId/content-validator](/api/content-validator/validate-content)</td><td>Validate all content against the model and return documents with queries and any validation issues.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/content-validator](/api/content-validator/find-and-replace-content)</td><td>Perform find/replace operations on content using the specified model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Management

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/models/:modelId/ai-agent-actions](/api/models/get-model-ai-agent-actions)</td><td>Return AI agent actions configured for a model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/cache\_reset/:cachePolicyName](/api/models/reset-cache)</td><td>Reset the cache for the specified cache policy.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/schemas](/api/models/list-model-schemas)</td><td>Retrieve a sorted list of all available schema names for the specified model, including physical, virtual, and dynamic schemas.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/dbt-exposures](/api/dbt/get-dbt-exposures)</td><td>Retrieve dbt exposures for the specified model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Git

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/models/:modelId/git](/api/model-git-configuration/get-git-configuration)</td><td>Retrieve the Git configuration for a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/git](/api/model-git-configuration/create-git-configuration)</td><td>Create a new Git configuration for a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PATCH /v1/models/:modelId/git](/api/model-git-configuration/update-git-configuration)</td><td>Update the Git configuration for a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/models/:modelId/git](/api/model-git-configuration/delete-git-configuration)</td><td>Remove the Git configuration from a shared model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/git/sync](/api/model-git-configuration/sync-model-with-git-repository)</td><td>Trigger a sync operation between the model and its configured Git repository.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/git/commit](/api/model-git-configuration/create-or-update-a-pull-request-for-a-model-branch)</td><td>Push a branch's model contents to Git and create or update a pull request.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/models/:modelId/migrate](/api/models/migrate-a-model)</td><td>Copy a model from one Omni connection to another by reading the source model's YAML at a specific Git ref and writing it to the target model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Topics

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/models/:modelId/topic/:topicName](/api/topics/retrieve-a-topic)</td><td>Retrieve a topic in a model by name.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Views

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[DELETE /v1/models/:modelId/view/:viewName](/api/models/delete-view)</td><td>Delete or ignore a view in a model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### YAML files

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/models/:modelId/yaml](/api/models/create-or-update-yaml-files)</td><td>Create or overwrite a YAML file for a model.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/models/:modelId/yaml](/api/models/get-model-yaml)</td><td>Retrieve the YAML representation of a model with optional filtering and mode selection.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/models/:modelId/yaml](/api/models/delete-a-yaml-file)</td><td>Delete a topic or view YAML file from a model.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Queries

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/query/run](/api/queries/run-query)</td><td>Run the query specified in the request body.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/query/wait](/api/queries/wait-for-query-results)</td><td>Poll for the results of one or more query jobs.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Schedules

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/schedules](/api/schedules/create-schedule)</td><td>Create a scheduled task for the specified dashboard.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/schedules/:scheduleId](/api/schedules/update-schedule)</td><td>Update the specified task. Changes are applied to future runs; in-progress jobs are unaffected.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/schedules/:scheduleId/transfer-ownership](/api/schedules/transfer-schedule-ownership)</td><td>Immediately transfer ownership of a schedule from one user to another user in the same organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/schedules](/api/schedules/list-schedules)</td><td>Retrieve a list of scheduled tasks.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/schedules/:scheduleId](/api/schedules/get-schedule)</td><td>Return the details of a single schedule, including its delivery destinations, recurrence configuration, and current status.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/schedules/:scheduleId](/api/schedules/delete-schedule)</td><td>Delete a schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Runs

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/schedules/:scheduleId/trigger](/api/schedules/trigger-schedule)</td><td>Trigger the execution of a schedule on demand.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/schedules/:scheduleId/pause](/api/schedules/pause-schedule)</td><td>Pause a schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/schedules/:scheduleId/resume](/api/schedules/resume-schedule)</td><td>Resume a schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Recipients

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[PUT /v1/schedules/:scheduleId/add-recipients](/api/schedule-recipients/add-schedule-recipients)</td><td>Add one or more recipients to an existing scheduled email task.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/schedules/:scheduleId/remove-recipients](/api/schedule-recipients/remove-schedule-recipients)</td><td>Remove one or more recipients from an existing scheduled email task.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/users/email-only](/api/schedule-recipients/manage-email-only-user)</td><td>Create or update an [email-only user](/share/deliveries/email).</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[POST /v1/users/email-only/bulk](/api/schedule-recipients/bulk-manage-email-only-users)</td><td>Create or update up to 20 [email-only users](/share/deliveries/email).</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/schedules/:scheduleId/recipients](/api/schedule-recipients/list-schedule-recipients)</td><td>Retrieve the list of recipients for the specified schedule.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Uploads

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/uploads](/api/uploads/upload-a-csv-file)</td><td>Upload a CSV file to create a new [data input table](/analyze-explore/data-input-csvs).</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[PUT /v1/uploads/:uploadId](/api/uploads/replace-upload-data)</td><td>Replace the data for an existing CSV upload.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/uploads](/api/uploads/list-uploads)</td><td>List all uploads ([CSV files and spreadsheets](/analyze-explore/data-input-csvs)) in the organization.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[DELETE /v1/uploads/:uploadId](/api/uploads/delete-an-upload)</td><td>Delete a CSV upload by its ID.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## Users

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /scim/v2/users](/api/users/create-user)</td><td>Create a user.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PUT /scim/v2/users/:userId](/api/users/replace-user)</td><td>Replace the specified user.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PATCH /scim/v2/users/:userId](/api/users/update-user)</td><td>Update the specified user by applying a list of [SCIM 2.0 patch operations](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2).</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[GET /scim/v2/users/:userId](/api/users/retrieve-user)</td><td>Retrieve a user using their unique ID.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[GET /scim/v2/users](/api/users/list-users)</td><td>Return a list of users, sorted by creation time.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[DELETE /scim/v2/users/:userId](/api/users/delete-user)</td><td>Delete the specified user.</td><td><Badge>v2 (latest)</Badge></td></tr>
  </tbody>
</table>

### Email-only users

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/users/email-only](/api/users/list-email-only-users)</td><td>Retrieve email-only users with their user attributes, with support for cursor-based pagination and filtering.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### Embed users

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /scim/v2/embed/users](/api/users/list-embed-users)</td><td>Retrieve a list of embed users, sorted by creation time.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[GET /scim/v2/embed/users/:userId](/api/users/retrieve-embed-user)</td><td>Retrieve an embed user using their unique ID.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[DELETE /scim/v2/embed/users/:userId](/api/users/delete-embed-user)</td><td>Delete the specified embed user.</td><td><Badge>v2 (latest)</Badge></td></tr>
  </tbody>
</table>

### Model roles

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/users/:userId/model-roles](/api/user-model-roles/assign-or-update-user-model-role)</td><td>Assign or update a model role for a user.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/users/:userId/model-roles](/api/user-model-roles/retrieve-user-model-roles)</td><td>Retrieve the model role assignments for a user.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

### User attributes

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[GET /v1/user-attributes](/api/user-attributes/list-user-attributes)</td><td>Retrieve all [user attribute](/administration/users/attributes) definitions in the organization, including custom-defined and system-defined attributes.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>

## User groups

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /scim/v2/groups](/api/user-groups/create-user-group)</td><td>Create a [user group](/administration/users/groups).</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PUT /scim/v2/groups/:userGroupId](/api/user-groups/replace-user-group)</td><td>Replace the specified user group.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[PATCH /scim/v2/groups/:userGroupId](/api/user-groups/update-user-group)</td><td>Update the specified user group by applying a list of [v2 patch operations](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2).</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[GET /scim/v2/groups](/api/user-groups/list-user-groups)</td><td>Return a list of user groups, sorted by creation time.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[GET /scim/v2/groups/:userGroupId](/api/user-groups/retrieve-user-group)</td><td>Retrieve a user group using its unique ID.</td><td><Badge>v2 (latest)</Badge></td></tr>
    <tr><td>[DELETE /scim/v2/groups/:userGroupId](/api/user-groups/delete-user-group)</td><td>Delete the specified user group.</td><td><Badge>v2 (latest)</Badge></td></tr>
  </tbody>
</table>

### Model roles

<table>
  <thead>
    <tr><th>Endpoint</th><th>Description</th><th>Version + Status</th></tr>
  </thead>

  <tbody>
    <tr><td>[POST /v1/user-groups/:userGroupId/model-roles](/api/user-group-model-roles/assign-or-update-user-group-model-role)</td><td>Assign or update a model role for a user group.</td><td><Badge>v1 (latest)</Badge></td></tr>
    <tr><td>[GET /v1/user-groups/:userGroupId/model-roles](/api/user-group-model-roles/retrieve-user-group-model-roles)</td><td>Retrieve the model role assignments for a user group.</td><td><Badge>v1 (latest)</Badge></td></tr>
  </tbody>
</table>


# Get current identity and permissions
Source: https://docs.omni.co/api/who-am-i/get-current-identity-and-permissions

/api/openapi.yaml get /v1/whoami
Retrieve the authenticated caller's own identity, API key scope, organization role, and resolved per-model permissions. Useful for allowing a caller to determine if they can execute a specific action without attempting it. Pass `modelId` to scope `rolesByModel` to specific models.

This endpoint can be used by any user with a valid API key.




# 2023 Changelog
Source: https://docs.omni.co/changelog/2023

A chronological list of new features, improvements, and bug fixes shipped to the Omni platform during 2023.

<Update label="December 1, 2023">
  * **dbt Integration**. Omni now closely integrates with dbt! By connecting your dbt git repository to Omni, we can pull in metadata from dbt such as field descriptions and even the code powering dbt models making it easier to trace logic and keep everyone in the business on the same page. We've also added a 'push' integration - allowing you to author dbt models directly from Omni queries.

    Learn more in our [docs](https://docs.omni.co/integrations/dbt/) and read about our [vision for Omni and dbt](https://omni.co/blog/three-ways-to-use-our-dbt-integration).

  * **Transpose tables**. Ever wanted to put the columns where the rows go and the rows where the columns go? Now you can with a new 'swap columns and rows' toggle on tables.

  * **Schema parameterization**. Using user attributes, you can now have each user dynamically query a different schema. Particularly useful in embed setups where there's one schema per client and each client needs to see their own.

  * **Easier to find download button**. A small but useful improvement! We've added a button directly to the workbook toolbar to download results to either CSV or Excel.
</Update>

<Update label="November 3, 2023">
  * **SSO Embedding**. Single sign-on (SSO) embedding enables delivering data to users outside of your organization by embedding Omni in other applications. User information such as permissions is passed from your application to Omni to construct a special authorized URL that can be used in an iframe. Read more about it in our [docs here](https://docs.omni.co/embed).

  * **Timezone Conversion**. You can now configure how you want Omni to convert timezones. On the connection page, there are 2 new settings: one to tell us what your database timezone is, and a second to tell us what timezone you want us to convert to when querying data.

  * **Ignoring Views**. New model parameter `ignored_views` so you can, well, ignore the views you don't want to see. This will remove those views from the file list in the IDE (and make them un-queryable in the workbook). It accepts wildcards as well so you can finally remove those hundreds of arielle\_dev\_\* tables.

  * **Visualization Upgrades**. Measures can now be stacked - finally can create that stacked bar + line chart everyone wants to see!

    KPI charts got a little smarter too - now you can change the colors for positive and negative values (or set them to whatever color you'd like). Now you can show off how good that reduction in the churn KPI looks.
</Update>

<Update label="October 13, 2023">
  * **Map Visualizations**. Have geo data? Now you can plot it on a map visualization!

  * **Topic Organization**. New topic-level model parameter (`group_label`) to group topics together in the UI, making it easier for end users to find the exact dataset they are looking for.

  * **Dashboard Settings**. More dashboard stylistic controls. You can now remove tile titles or backgrounds and borders for that 'floating' tile look.

  * **More Scheduler Options and Formats**. Choose between receiving the dashboard inline in the email, attached as a PDF, or maybe just a link-only to see the dashboard live. You can now also choose to hide filters on the dashboard PDF or PNG.

  * **Download to Excel**. Now you can choose between CSV or Excel as download options.

  * **Embed Settings**. When you're trying to get that perfect embedded look, sometimes you just need a few more controls. Now you can set the theme and light/dark mode for embedded content.

  * **Vis Improvements**. New options for the KPI vis - can now show the comparison number as an absolute, percent, or both!

    And if you're looking to add a little visual flair to your tables, you can now add in column bars.

    We've also made some sizing changes to legends to automatically fit the space much better and prevent legends from being cut off.

  * **Modeling Improvements**. Lots of new model goodies this week!
    * **`order_by_field `**- order a field by another field. Great for setting custom sort orders
    * **topic level \*\*\*\*`always_where_sql `**- always apply a filter to any query run on a topic
    * \*\*`where_sql `\*\*\*\*for relationships \*\*- insert a condition into the `where `clause when that specific join is used
    * \*\*query views nest into schema folders in the IDE \*\*- instead of query views hanging out solo in the IDE, they'll now be nested into the appropriate schema folder for \*enhanced \*file organization
</Update>

<Update label="September 22, 2023">
  * **SQL Super Powers**. SQL editing gets a new boost - start out writing raw SQL, then convert your query to be 'auto-modeled' to save all those new logic bits back to your data model for reuse.

  * **Internal Embeddable Dashboards**. Tired of trying to convince your stakeholders to log in to Omni to check out the insightful dashboard you built them? Instead, plop that dashboard right into the line of business app they are looking at every day anyways with Omni's new embeddable URLs. Easy-peasy to drop a dashboard inside Salesforce, Notion, Confluence.. and even Chrome extensions if you want to get really fancy.

  * **Copy tab to existing workbook**. Previously you could take a workbook tab and copy it to a new workbook. Now you can copy a tab to an existing workbook. Moving queries around has never been easier!

  * **New Vis Options**. New options to make your visualizations useful and visually delightful:
    * Trend lines
    * Line and area chart styles - points, line thickness, transparency, and more

  * **App Appearance Controls**. Add a little personal flair to your Omni experience! You can now control the appearance of the app - switch between light and dark mode, and change the app color theme.

  * **More Schedule Frequencies**. No need to futz with cron strings to get that dashboard sent to you on just the right schedule. We added new UI options for configuring daily, weekly, and monthly schedules.
</Update>

<Update label="August 31, 2023">
  * **KPI Visualizations**. A new WYSIWYG [visualization type](https://docs.omni.co/visualize-present/visualizations/types/kpi) that combines numbers, charts, change arrows, progress bars, text, and more to build flexible KPI tiles.

  * **Visualization Timeframe Switcher**. Swap out the timeframe granularity directly inside the visualization editor. No more need to go back to the query to change out the field.

  * **Dashboard Edit Toolbar**. Getting dashboard tiles sized exactly right is easier than ever with a change to dashboard edit mode. Rather than the edit bar being on the side of the screen, it's now at the top so the size of your tiles always stays consistent regardless of whether you're in edit or view mode.

  * **Row-level Data Permissions**. With user attributes and a new topic-level [`access_filters`](https://docs.omni.co/modeling/topics/parameters/access-filters) parameter, you can now control what rows of data a user can see. This allows you to build the same query or dashboard, but depending on an individual users' attribute value, they will only see the rows applicable to them. One example of this in use is if you want to restrict a sales rep's visibility to only their accounts. Also very useful for serving up analytics to your external clients where you want to build a dashboard once, but ensure each client can only see their rows of data.

  * **Microsoft SQL Server Support**. New dialect alert! Omni can now connect directly to Microsoft SQL server.
</Update>

<Update label="August 24, 2023">
  * **Drag-and-Drop Visualization Editor**. Visualizations just got way easier to create and edit with a new drag-and-drop interaction inside the vis editor.

  * **Visualization Reference Lines**. Adding goals or targets to your charts is now possible with vertical reference lines.

  * **More Mustache Markdown Fun**. Mustache can now be used in even more places - query elements can be inserted inside chart text (like axis titles) and dashboard filters can be inserted into dashboard text tiles.

  * **Drilling and Context Menus Move to Left-Click**. While we love a good right-click menu… drilling is just too important an action to be relegated to a secondary click. Drilling and context menus are now accessible with left clicks (don't worry - it still works if you got used to the right-click!)

  * **Field Aliases**. Following on the [view aliases parameter](https://docs.omni.co/modeling/views/parameters/aliases), fields can now also have `aliases`. Makes it easy to preserve content when a field name changes in the database.

  * **Other Improvements**.
    * **Control calculation direction for pivots:** choose if the calculation should be computed down the column or across the row
    * **Date fill for "on or after filters"**: dates can now be filled in when an on or after filter is applied, filling rows up to the current date
    * **Unpin axis from zero:** new Y-axis visualization setting
    * **Add existing join to topic**: from the workbook join modal, new option to add the join to the current Topic (without having to go to the IDE)
    * **Filters can be referenced in dashboard text tiles:** call out filter values on a dashboard using [mustache syntax](https://docs.omni.co/visualize-present/visualizations/types/markdown)
</Update>

<Update label="July 26, 2023">
  * **Scheduled dashboards**. [Dashboards can now be scheduled](https://www.omni.co/blog/scheduling-dashboards-to-email) so you can keep up with your most important metrics from anywhere. We also released new admin and management controls to make it easy to manage all your scheduled content from one central spot, and you can even navigate usage by sender *or* recipient (to help you curate a seamless experience for folks who aren't in Omni yet!

  * **Dashboard text tiles**. Add text, links, images, and more to your dashboard with a new markdown-based text tile.

  * **Markdown visualization**. A whole new viz type that makes it possible to create beautiful, info-dense tiles with a combo of text, markdown elements, and query variables. Check out some of our favorite examples.

    [Read all about Markdown visualization in our documentation](https://docs.omni.co/visualize-present/visualizations/types/markdown)

  * **Visualization updates**. We've made a bunch of viz updates to help you easily communicate results - totals on stacked bars, conditional formatting, and a new color palette picker.

  * **Create filtered measures from pivot tables**. Often we want to compare components of a group to the group itself - purchases by region, opportunities by stage, traffic by channel, and so on. Filtered measures make this easy, but they can be tricky to build if you need complex case statement logic (or even don't want to look up syntax). Now, you don't need to do either because we've made it trivial to **create filtered measures** from pivot tables (shown below) and reference totals for **custom calculations**.

  * **Other Improvements**.
    * **Default\_drill\_fields model parameter**: global control for defining a default drill path for every measure on a view
    * **Custom view\_label parameter on fields**: group fields under a different view label in the field picker
    * **Context menus on IDE files**: right click on a file in the IDE to save, rename, or delete
    * **Pie chart improvements**: expose data labels and option to hide the legend
    * **Wide visualization legends**: expand the width of legends for easier readability
    * **Log scale for visualizations**: change the axis scale between linear or log
    * **Expand cells on table**: can right-click on a table cell to expand the text and copy/paste (useful to see the full contents when a cell is super long!)
</Update>


# 2024 Changelog
Source: https://docs.omni.co/changelog/2024

A chronological list of new features, improvements, and bug fixes shipped to the Omni platform during 2024.

<Update label="December 19, 2024">
  * **Now in beta: the dbt IDE!** With the now-in-beta dbt IDE, you can interact with your entire dbt repo right inside Omni! Navigate your models and edit and run dbt SQL, all without toggling between tools.

    [Check out the demo](https://docs.omni.co/demos/2024/20241206#dbt-reader) and let us know if you're interested in taking it for a spin.

  * **Color modeling for dimensions**. In [last week's demos](https://docs.omni.co/demos/2024/20241213#color-modeling-launch), we showed off the ability to maintain consistent coloring for dimensions.

    To do this, use the [new colors parameter](https://docs.omni.co/modeling/dimensions/parameters/colors).

    And then, in the workbook, add the field to the chart's **Color** field.

    **Note that this feature is currently in beta; the parameter syntax may change.** We also plan to add a UI-based option for defining colors, which will push down into the model.

  * **Topic files**. Each topic you create will now have its own dedicated file, viewable in the Topics section of the IDE.

    This change allows you to access and modify topics without needing to scroll through a potentially long model file.

    Additionally, to support this update, the model file topics parameter has been deprecated. Topics created before this change will continue to function as they always have, meaning you don't have to migrate to dedicated topic files to keep working. However, you won't be able to add the topics parameter to any new models.

    Check out the [updated topic documentation](https://docs.omni.co/modeling/topics) for more info.

  * **Reference raw columns in filters**. We've added a new filter type that allows you to model injected SQL and create flexible column pickers.

    Once defined, the filter-only field will then display in the field picker and can be used like any other filter. In this example, we can quickly change the dimension in the analysis...

    ... And get an updated measure value, all without needing to add additional fields first!

  * **View results and charts, together!** The new **Both** button in the workbook, accessible in drafts and published documents, allows you to view the results of a query and its visualization at the same time.

  * **Create custom reports in your instance's Analytics section (and a new out of the box embed usage dashboard)**. Custom reports are now supported for your instance's **Analytics** section. We've also opened up the ability to add schedules and alerts to any analytics content.

    And as an added bonus for our customers leveraging embed capabilities, there's a new out of the box dashboard specific to embed adoption.

  * **Add context to tabs and tiles with descriptions**. You can now add descriptions to workbook tabs and dash tiles. Click the tab, **Rename**, and enter a description.

    The descriptions will show when you hover over a tab in the workbook.

    And on the associated dashboard tile after you click the tile's options menu (three dots), then **Show description**.

  * **And now, some honorable mentions:**
    * New option for KPI visualizations allows you to select the **2nd from last** value to compare against
    * Two new table/Excel-style calculations are available:
      * [EOMONTH](https://docs.omni.co/analyze-explore/calculations/date-time#eomonth) - Finds the end of the month for a given date or datetime
      * [IFERROR](https://docs.omni.co/analyze-explore/calculations/logic#iferror) - Returns a specified value if a formula returns null due to an error
    * You can now sort data in results tables when subtotals are enabled!
    * Sections in IDE files can be collapsed for easier viewing. Hover over the caret next to a section and click to fold/unfold. You can also use keyboard shortcuts to fold or unfold all sections in a file:
      * **Fold** - `Command` + `K`, `Command` + `0`
      * **Unfold** - `Command` + `K`, `Command` + `J`
</Update>

<Update label="December 5, 2024">
  * **New editing workflow!** In the very near future, the editing workflow for documents will change. This new workflow utilizes drafts, allowing you to make changes to documents before they're published and iterate without commitment.

    Drafts come with the ability to view and revert to individual changes, archiving, and more. Check out [the docs](https://docs.omni.co/content/develop/drafts) or [our demo](https://docs.omni.co/demos/2024/20241108#more-drafts-preview) to learn more. If you just can't wait, reach out to [Omni support](mailto:support@omni.co) (email or in your Slack channel) to take the beta for a spin!

  * **Customizable column totals**. You can now customize how totals are displayed for dimensions, measures, and calculated columns!

    When column totals are enabled, Omni will automatically use the column's calculation as the default total. However, you can adjust this to suit your specific needs, giving you greater flexibility and control over your data summaries. Totals won't display by default for dimensions, but you can opt to add one if needed. Check out [the docs](https://docs.omni.co/analyze-explore/point-click-queries) for more details.

  * **Interactivity for SQL query results**. Previously in SQL queries, sorting and calculations had to be done inside the query itself. With this update and just a few clicks, you can sort data or add calculated fields right in the **Results** table, just as you would with a non-SQL query.

  * **Dynamic database connection switching**. Switch between database connections on the fly with our latest connection enhancement. Using user attributes, you can specify which connection environment users will query against in Omni.

    For example, you could:

    * **Simplify your development workflow.** If you follow a development workflow such as dev-staging-production, connection switching enables you to effortlessly change environments with just a few clicks in Omni's IDE.
    * **Support multi-tenant database setups.** If you're an embed customer that whitelabels Omni, connection switching can be used to dynamically point each company or user at their own database.

  * **Inline validation in the IDE**. Trying to find the cause of a mistake in your code can be time-consuming and frustrating. The built-in model validator in the IDE will highlight your mistakes, but it's not always obvious where in the code the issue is - especially if you have a particularly large model file.

    This week, we added inline validation to the model IDE. This will make it easier to quickly find and fix issues without needing to scroll through the file or click into the validator.

  * **And now, some honorable mentions**. Over the Thanksgiving break in the US, our team focused on some quality of life projects. We were delighted by these small but meaningful enhancements, and hope you will be too!
    * Easily resize panels by dragging the edges
    * Drilling into [dimension fields](https://docs.omni.co/modeling/dimensions/parameters/drill-fields) may not be brand new, but being able to drill right from a chart is!
    * Calculated fields can now have descriptions, which will display as a tooltip in the column header in the **Results** table.
</Update>

<Update label="November 14, 2024">
  * **Teachable + Conversational Blobby AI**. Omni's query AI helper (Blobby) just got smarter! Blobby (like any great analyst) works best when they have some context about a dataset. So now you can teach Blobby just that with a new topic-level `ai_context` parameter and field-level context via descriptions.

    The `ai_context` parameter can give Blobby sample questions and answers, background information about the dataset, instructions for what to do (or not do), and any other information you think Blobby should know when answering questions.

    Further, Blobby is now able to hold a conversation. Next time you take Blobby for a spin, try asking them questions like "what should I ask about this data? what follow-up questions should I ask next? can you explain how you got this answer?" See the [demo here](https://docs.omni.co/demos/2024/20241108).

    Tip: admins can also check out the types of questions users are asking by heading over to the Analytics dashboard - this can help guide what additional context Blobby might benefit from to best serve your users' questions.

  * **New Editing Workflow (Beta)**. Coming soon to all Omni customers, a [new editing workflow](https://docs.omni.co/demos/2024/20241108#more-drafts-preview) that allows users to make edits to documents as a draft before publishing changes. This will replace the current editing workflow. If you'd like to take the beta for a spin to get an early look at this workflow, reach out to `support@omni.co` (or message us in your Slack channel).

  * **SQL Enhancements**. Love SQL? So do we! We've improved autocomplete functionality in the SQL box to make it even more delightful to write ([check out the demo](https://docs.omni.co/demos/2024/20241108#sql-autocomplete-improvements)). We've also introduced [SQL tabs](https://docs.omni.co/analyze-explore/sql) so that users can write the dialect of their database in a new and improved experience. Keep watching this space, our SQL results will soon become interactive too!

  * **Visualization Updates**.
    * **Out of the box region maps**. Omni now offers region-based mappings for countries and US states out of the box, and you can create custom maps by specifying an endpoint that returns region data complying to either the GeoJSON or TileJSON specifications. [Read more in our documentation](https://docs.omni.co/visualize-present/visualizations) about all the options.
    * **X/Y - Axis Improvements**. Lots of new toggles to make axes exactly right. Now you can hide/show ticks, the axis line, and more. We also polished up the default date time formats on x-axis to make it more intelligent and easier to read.
    * **Size controls in our advanced Vega Lite spec available**. This opens up the opportunity for trellising with some hand tuning of sizing. This is a precursor to trellis / grid visualization controls natively in vis. [Check out the demo](https://docs.omni.co/demos/2024/20240927#trellising-in-advanced-vis).

  * **White-labeling Scheduled Emails**. By setting up a "Custom sender email", you can now send customer facing emails from Omni with your own email domain. ([Check out the demo](https://docs.omni.co/demos/2024/20241101#scheduler-sender-name-and-email-controls)) To enable the functionality for your organization reach out to [support@omni.co](mailto:support@omni.co).

  * **Single Select Filters in Model**. Now string fields in the model can explicitly be set to single-select dropdowns by inserting `filter_single_select_only: true` in the field. This allows for cleaner usage of items like filter-only fields for templated filters or parameterization. [Check out the demo](https://docs.omni.co/demos/2024/20241101#single-select-filters-in-model).

  * **User Specific Timezones**. By enabling "Allow User-Specific Timezones" on a connection, users can explicitly set their own timezones from their Account page in Omni. This also includes controls for setting user-specific timezones on the fly in embedded contexts. [Watch the demo](https://docs.omni.co/demos/2024/20241101#user-specific-timezones).

  * **Change to "Between" Date Filters**. We've updated the behavior of "between" date filters a bit - the start + end times are now \*\*inclusive \*\*for dates. If you have time included in the filter, the end date is still **exclusive**. Don't worry - this won't change anything for existing content you have saved.
</Update>

<Update label="October 29, 2024">
  * **Embed users can use deliveries and alerts**. All of the functionality you know and love for internal users with our [scheduling and alerting](https://docs.omni.co/share/deliveries) is now possible for embed users. Leverage the document settings and a new "email" SSO URL parameter to build the experience you want.

  * **New Document Settings**. Admin and users can now decide how users can interact with content by assigning the [document abilities](https://docs.omni.co/share#controlling-document-interactivity): schedule, download, drill, or view-only functionality. The choice is yours!

    This work opens up the ability to make **view-only workbooks** and dashboards.

  * **Global Palettes for Downloads and Deliveries**. The exciting color palette work continues! Our global palettes now will persist when downloaded or scheduled. We've also added even [more controls for customizing your themes](https://docs.omni.co/demos/2024/20241018#more-dashboard-css-filters-popovers-buttons-more): border details and element details (like control background color and popover colors).

    Speaking of color palettes, here is a fun example of what you can create ([watch the demo](/demos/2024/20241011#nba-dashboard-demo)).

  * **Enhanced Filter Modeling Capabilities**. A brand new set of controls to label filter values, and pass said labels through as dynamic text. Now filter text can be explicitly set and these values can pass through to fields for things like period-over-period or other filter-only field use case.

    * **Suggestion lists**. Explicitly define what the filter values should be along with what labels could go with those values by using.
    * **Filter Value Labels**. Then take it step further and using `{{'{{ filters.my_view.my_field.filter_value_label }}'}}` you can reference the suggestion\_list "label" for a filter selected value

    See a [demo how these work together](https://docs.omni.co/demos/2024/20241011).

  * **Better Content Validator**. More functionality to understand the current overall state in the content validator - how much is errored and filtering to only errored content (it's not a secret, but it feels like one, just click the red x to filter to only errors). [Watch the demo](https://docs.omni.co/demos/2024/20241011#better-content-validator).

  * **Default Timeframes**. New controls to set default time frames from the default set in Omni (date, week, month, quarter, year). Now can be modeled explicitly. In the model use `default_timeframes` to set the ones that matter most for your use case.

  * **Schema Organization in IDE**. Clearer distinction between static schemas and dbt schemas in the IDE for easier model management. Check out the[ demo](https://docs.omni.co/demos/2024/20241011#better-dbt-schemas-in-ide).
</Update>

<Update label="October 3, 2024">
  * **New Embed Functionality**.
    * **Self-service reports for embed (beta)**. Introducing a [new mode for embedding Omni called Application](https://docs.omni.co/embed/customization/create-mode) that allows embed users to create and share custom content with others in their group. Now you can open up the full power of Omni for all of your customers.

      Check out a [recent demo](https://docs.omni.co/demos/2024/20240927#embed-content-sharing-and-saving).

    * **Dashboard Linking Inside the iFrame**. Building on the [Link Access](https://docs.omni.co/embed/setup/test-urls) parameter for embedded content, now links between embedded dashboards will be *inside* the iframe. No more tearing down and rebuilding iframes, just super fast linking to make navigation feel 100% native - [read more in our docs](https://docs.omni.co/embed/customization/link-content).

  * **Global Chart Palettes**. Admin now have the ability to set palettes for the Omni environment including divergent and gradient palettes with a full admin UI. [Check out the Demo](https://docs.omni.co/demos/2024/20240927#global-color-palettes-launch).

  * **Reference Cells Across Tabs**. Why isn't calling data from another query as easy as Excel or Sheets? Just reference the field and put data next to each other. Now you can with [simple cross-sheet cell references](https://docs.omni.co/demos/2024/20240913#cross-tab-cell-references) to bring queries next to each other without joins or models or lookups, just "=' "

  * **Flatten Pivots**. Simplify your pivoted data tables by replacing each existing pivot value with a filtered measure. Also makes it easy to add 'other' buckets on the fly. [Watch the demo](https://docs.omni.co/demos/2024/20240913#grouping-measures-outside-pivots) (note we refined the name).

  * **Update Query Views from the Workbook UI**. When modeling data in your workbook, users now have the choice to Update a query view for some better workflows for tuning query views while retaining the model underneath.

  * **New Delivery and Download Formats**. Users can now choose to hide the title for downloaded or delivered content and we have two new format types: [SFTP](https://docs.omni.co/share/deliveries/sftp) and [JSON](https://docs.omni.co/demos/2024/20240830#schedule-without-titles-json-download-and-scheduling).
</Update>

<Update label="September 12, 2024">
  * **Dashboard Themes**. Now Admins can edit and apply themes to both internal as well as embedded dashboards. [Custom Themes](https://docs.omni.co/visualize-present/dashboards/theming) are now also reusable and reference-able without needing to copy and paste JSON.

  * **Set up facet filters in workbooks**. Previously default behavior, faceted filters are now something that can be [enabled on dashboards](https://docs.omni.co/visualize-present/dashboards/filters#faceted-filters) with a new setting, and for [workbooks it is enabled in the model](https://docs.omni.co/demos/2024/20240823#workbook-filter-faceting-controls) by adding "facet\_workbook\_filters:true"

  * **Improvements to Downloading in Workbooks**. In workbooks there are a few [new options for downloading data](https://docs.omni.co/analyze-explore/point-click-queries#downloading-results).
    * A new File Type is supported: JSON
    * Under the Advanced panel, users can now choose if they want the data to be formatted or unformatted as well as how many rows they want to download.
    * One other change to the download behavior, if you have hidden columns, they will no longer show up in the downloaded data.

  * **Custom Visualizations with iframes**. New functionality that allows markdown tiles to serve completely custom visualizations (non-Vega) using data in results + [postMessages](https://developer.mozilla.org/en-US/Web/API/Window/postMessage) framework to render custom iframes.

  * **Dynamic Database Connections**. New functionality that allows for [dynamically swapping the database connection](https://docs.omni.co/demos/2024/20240823#dynamic-db-connections-in-the-ui) from a branch. Easily switch between prod or staging schemas (not just dbt) in the UI - great for testing data models across mirrored databases during migration or other more complex deployment use cases.

  * **Streamlined filter options**. Filters options have now been streamline to show only the most common choices above the fold, the rest of the more advanced options are in a "More" menu.
</Update>

<Update label="August 14, 2024">
  * **Improvements in workbook ergonomics**.
    * **Reorder Tabs**. Drag and drop your workbook tabs to your heart's content! We've also improved the scrolling of the tab bar for workbooks with a large amount of tabs. \[[Watch the demo with some sneak peaks of other features](https://docs.omni.co/demos/2024/20240621#workbook-ux-tab-reordering-dashboard-search-before-july-1)]
    * **In-use toggle for the Field Picker**. Streamlining the field picker experience, users can now use a toggle under the search bar to see which fields are in-use. \[[Read more](https://docs.omni.co/analyze-explore/point-click-queries#searching-fields)]

  * **Visualization Improvements**.
    * **Auto-vis Improvements**. Enormous improvements to stickiness in visualization settings and auto-vis. Now chart settings will retain even after query changes; toggling visualization types will retain settings; and auto visualization will retain tuned settings. \[[Watch the demo](https://docs.omni.co/demos/2024/20240809#better-stickier-visualization-settings-autovis-soon)]
    * **More table options**. Customize tables to meet your needs, we've added new styling and functionality options. Change column widths, truncate or wrap text, customize the colors, and more!
    * **Adding Boxplot**. A favorite custom visualization now comes out of the box! Users can find the option directly from the chart selector. Use the visualization controls to choose if it is Quantitative or Nominal (under X) and the sort order (under both X + Y).
    * **More styling options for KPIs**. From the visualization controls in a workbook users can now customize the alignment and text sizes for each component of the KPI to make sure they layout just how you want.

  * **Dynamic Dashboards**.
    * **Dashboard Vanity Urls**. New settings for vanity dashboard URLs, making navigation simple and contextual - now it's as easy as dashboard/CorporateDash instead of dashboard/1 or dashboard/lkjdfs (unless you want that!). This also means that you can more easily make updates to an embedded dashboard without requiring an engineer to point from one identifier to another, by instead pointing to a fixed, immutable URL.
    * **Single value dropdown filters**. A new filter type is available on dashboards where a user can only select one value for the filter. To create this, go to 'Edit Filter' and see the new option called 'Filter control'. By default Omni uses Advanced filters, but you can now select 'Single value dropdown' as a new filter experience.
    * **More Controls now available on dashboards**. When editing dashboards, select the 'Add control' option to now create more powerful dashboard experiences by leveraging[ parent controls](https://docs.omni.co/visualize-present/dashboards/controls) as well as[ period over period controls](https://docs.omni.co/analyze-explore/point-click-queries#period-over-period-analysis) directly on the dashboard.
    * **Faceted filters on dashboards**. There's a new dashboard setting to enable or disable faceted filters. When filter faceting is on, one filter's selection will limit the values suggested in other filters. For example, the 'State' filter will limit the results in a 'City' filter to show only relevant city names.

  * **Downloads**.
    * **Unlimited CSV Downloads**. The world's your oyster! Now you can take as much data as you want (with some time out limits) out of the Omni app in a csv format.

  * **Modeling Magic**.
    * **IDE Auto Error Fixing**. To speed up development, many of the errors in the IDE now have a button on the right hand side of the error to automatically fix them. This works in branches as well! ([Watch the demo](https://docs.omni.co/demos/2024/20240719#model-automatic-error-fixing-coming-soon))
    * **Scheduled Schema Refresh**. After establishing a database connection, Admin can use a cron string to schedule a soft refresh of the schema which merges the newly generated schema with the existing one without overwriting it. This will automatically keep your Omni model in sync with changes in your database. ([Read more](https://docs.omni.co/modeling/develop/schema-refreshes))
    * **Semi-additive measures/Omni dimensionalize**. Working with data that doesn't aggregate over time (MAUs, credit balances, etc) can be painful. Now we have native operators that can handle all that nuance with minimal effort by creating a field that leverages `omni_dimensionalize`. ([Read more](https://community.omni.co/t/semi-additive-measures/120))
    * **Improvements to the Git Integration**. We're streamlining the integration between Git and Omni by allowing users to commit changes from outside Omni in Git as long as the changes are in valid Omni YAML.
</Update>

<Update label="July 2, 2024">
  * **New AI Features (beta)**. We're adding a bit more magic to our repertoire of analysis tools this week with a new AI-based query experience. Users can ask natural language questions and Omni AI will return answers scoped within the confines of a Topic (which means it leverages data model definitions, joins, and permissions to reduce hallucination). Blobby also remembers the context of your question so you can keep iterating until it's just right. If you'd like to give it a spin, contact us in your Slack support channel or at [support@omni.co](mailto:support@omni.co).

  * **Alerts**. Alerts let you trigger a delivery to send based on a condition being met. It works with all our delivery destinations (email, slack, webhook) so now you can get that notification *just* when you need it.

  * **Email Bursting and Personalization**. Now you can personalize emails based on a user's user attribute value. Makes it easy to configure 1 dashboard and personalize and scope the results to 100s of recipients. User attributes can be set up for any email address, whether or not they are a user in Omni, making this useful for partners, clients, internal employees, and more.

  * **Controls**. Controls are new UI elements that let users swap out parts of a query, making for a more dynamic (while constrained) exploratory experience. Swap out time grains, dimensions, or measures (or all of the above!). Available on both the workbook and dashboard.

  * **Content Search and Navigation Refresh**. Finding stuff is now easier with content search, and we've paired that with a slick new navigation refresh.

  * **Embeddable Workbooks (and custom Analytics analyses!)**. First you could embed dashboards… now you can embed workbooks! This makes it easy to give your customers the power of Omni's ad-hoc querying experience so they can build their own custom analyses. We're also working on the ability for embed users to save their own custom reports.. stay tuned for more on that. And as a quick recap, we've been running fast to build out our Embedded Analytics product - other recent features in this arena were dashboard theming, custom domains, and a git integration. Much more to come!

    As we eat our own dogfood, we've also opened up the Analytics data in an embedded workbook so *you*, dear reader, can run your own custom analyses in the Analytics section of the app to better understand your company's Omni usage.

  * **Other Stuff**. But wait, there's more!
    * [Inline links and images in tables](https://docs.omni.co/demos/2024/20240621#inline-images-and-markdown-in-tables-launched)
    * [dbt environment variables](https://docs.omni.co/demos/2024/20240614#environment-variables-for-dbt-launched)
</Update>

<Update label="June 12, 2024">
  * **Period Over Period Comparison**. Built-in support makes it easy to compare metrics across time periods!

  * **Embed Event Signaling + Listeners**. Check out our new [event listening framework for embedded applications](https://docs.omni.co/embed/events) designed to monitor activity within the Omni iframe, enabling the orchestration of experiences outside of Omni.

  * **Filter By Another Query**. You can [filter one tab by the values that appear in another](https://docs.omni.co/analyze-explore/point-click-queries#filtering-by-another-query) by first creating the query by which you want to filter (e.g. "Users who bought Calvin Klein in the past 30 days") and then creating the query you want to filter with your first query. For our SQL folks, this generates WHERE clauses that look like `WHERE IN (SELECT...)` where that SELECT is the filtering query.

  * **Branch Mode + Git Integration**. [Branch mode](https://docs.omni.co/modeling/develop/model-management#branch-mode) and the [git integration](https://docs.omni.co/integrations/git) features are generally available for all! Looking to test your changes before promoting them to the shared model? Try out branch mode. Additionally, you can pair branch mode with a git integration (currently only supports GitHub) to add version control to your Omni model changes.

  * **Single-tile Scheduling**. Expands the options for scheduling beyond scheduling an entire dashboard. This is also the foundation for future alerting features, stay tuned!

  * **New Analytics Dashboard Tiles - Schedules & Permissions**. Added more analytics for you to see usage metrics on schedules and user permissions!

  * **Other great updates!**
    * Enable in-app logging capabilities to enhance observability for the most critical actions. Reach out to us to get this feature enabled on your Omni environment!
    * Move legends to the left, right, or bottom of a chart.
    * Access filters can now be set globally which provides even better data control in embedded environments.
    * Improvements made to Omni AI for better filtering and error handling.
    * [`default_topic_access_filters`](https://docs.omni.co/modeling/develop/data-access-control##default-access-filters-for-topics) and `default_topic_access_grants `apply access filters or access grants to all topics, even if not explicitly specified.
    * Support for `IDENTIFIER` function (in databases dialects that support it, including Snowflake) paired with filter from parameter.
</Update>

<Update label="May 14, 2024">
  * **`XLOOKUP` calculations function (beta)**. Execute cross-tab analysis to create time series joins across tabs or use fact lookups in another query tab of the same workbook. Check out the [`xlookup` function documentation to learn more.](https://docs.omni.co/analyze-explore/calculations/position#xlookup)

  * **Filter updates**. We have quite a few updates for different types of filter options!
    * **Compound filters**. Have you been waiting for the day you can require two filter conditions in your queries? That day is here!
    * **Filters as parameters**. Filters can now be used as parameters by passing through a single-value filter reference to create parameterized reporting. This brings in handy use cases like dynamic formatting, forecasting, or passing filters into calculations.
    * **Filters between dashboards**. A field's `link:` parameter can dynamically pass values from fields or user attributes into a linked dashboard, enhancing the workflow experience of navigating directly to a filtered dashboard from a value in a query or a dashboard.

  * **Dimensional drilling**. Users can now drill into a particular value for fields that have defined drill fields to dig deeper while they are querying their data.

  * **Excel downloads keep formulas**. Now when you download your content in `.xlsx` format, the formulas are saved in the download. Making it even easier to keep working in other excel tools!

  * **Other awesome updates:**
    * More color customization options as well as zebra-striped tables
    * New column header description tooltips giving users more context on the fields in a query.
    * [Field selector](https://docs.omni.co/demos/2024/20240503#dynamic-fields-select-fields-from-filters-launched): Allows users to change queries to dynamically swap between fields allowing users to further curate the querying experience in a workbook. Note: this is currently available in workbooks; support from dashboards coming soon!
    * In-table bars now have conditional formatting for more visual styling options.
    * Workbook URL schema changes now provider finer grain control to reorder workbook tabs via the URL. Those changes are kept in sync with the associated dashboard for seamless operation.
</Update>

<Update label="April 19, 2024">
  * **New Table Features and Updates**. We've separated the results table and table visualization, meaning not all options will exist between the two. The results table is now focused around query manipulation and spreadsheet calcs, and the table visualization leans more into styling (like the new dimension grouping feature!).

    Implemented frozen columns in tables, allowing users to freeze columns to the left of any non-pivoted value.

    Users can now be able to leverage subtotals to enable dimension grouping and create collapsible table layouts - note this will be live next week!

  * **New Omni App Theme: Omni-98**. Head over to your account settings and look for the slightly pixelated Omni logo for a blast from the past with the Omni-98 theme for your Omni app! :omni-98:

  * **Incremental Promotion in Workbooks**. Users can now incrementally promote changes they create from their workbooks into their models. This feature allows users to move quickly in an analysis and decide which fields, relationships, views or topics should be contributed to the rest of the organization or left in the workbook layer with just a few clicks.

  * **Impersonate User Mode**. We've introduced an **Impersonate User** mode for admins to step into the shoes of any non-admin user within the app. This gives admin insights into how another user's particular permissions, user attributes and filters may affect their Omni experience firsthand.

  * **New Custom Visualizations**. [Check out the sample code for these custom visualizations in our docs](https://docs.omni.co/visualize-present/visualizations/types/custom)!
    * **Gauge charts**. Gauge charts, also known as dial charts or speedometer charts, for visualizing your goal targets, health metrics, or monitoring performance.
    * **Word cloud**. Are you doing some text analysis? Take advantage of our Word Cloud custom visualization.

  * **Funnel**. Are you looking to display your sales pipelines, marketing campaign analysis, customer journeys? Consider using the Funnel custom visualization.

  * **Jump from a Dashboard Vis into a New Workbook**. The `New analysis from here...` option on a dashboard tile's menu allows users to start a new workbook from an existing dashboard tile - so users can riff on queries and dive in deeper without impacting the saved piece of content.

  * **Other Improvements**.
    * A new field \*\*Copy Reference \*\*menu option allows users to quickly copy a field name from the field selector in the workbook making custom field creation or SQL a little bit faster and easier!
    * Made improvements to speed up the SQL IDE on gigantic schema models where auto-complete was slowing typing and deletion.
    * Button styling control for embedded content - now your embedded dashboard's buttons can be any desired color - [learn more about custom embed options in this doc](https://docs.omni.co/embed/customization/themes)
    * We now have case insensitive filtering (for when the database isn't as clean as you wished!).
</Update>

<Update label="March 28, 2024">
  * **Modeling: Branch Mode**. Users can now seamlessly switch between branches and merge changes into a shared model, streamlining collaborative workflows. This functionality mirrors typical developer workflows, enhancing efficiency and organization.

  * **Embed Updates**.
    * **Custom Theming**. Users can now enjoy custom themes, including background gradients and border radius stylings. Custom theme properties such as dashboard background and tile styling are now available, providing greater flexibility in embedded dashboard customization.
    * **Vanity Domains**. Users can implement vanity domains for privately embedded implementations of Omni. Vanity domains solve third-party cookie issues in certain use cases enabling a seamless login experience for users using browsers like Safari. If you're interested in enabling this feature on your Omni app, reach out at [support@omni.co](mailto:support@omni.co), we would love to set this up for you!

  * **dbt Schema Switching (beta)**. dbt Schema Switching empowers users to transition between Omni pointing at either development or production schemas, facilitating coordination of changes across dbt and Omni models and content.

  * **Download Dashboards**. Introducing the ability to download dashboards. Users can conveniently download dashboards as a PDF or a ZIP of CSV files.

  * **Workbook: Table Updates**. Users can now resize values in a column by using the "wrap" option in the calculations menu. Offers users better presentation of fields that contain values that may have multiple lines or have long text.

    Conditional value formatting allows users to select a single color or a color gradient to highlight value differences with color.
</Update>

<Update label="March 13, 2024">
  * **Promote Calculations to the Model**. Ever made an excel syntax calculation you wished you could reuse again? Now you can! Calculations can now be promoted to dimensions for reuse first into to the workbook, then optionally into the shared model (depending on the type of calculation some limitations will exist).

  * **Content Validator (beta)**. The Content Validator allows users to visualize broken content when the model or downstream database references inevitably change. This can be accessed from the left-hand navigation in the model IDE and allows users to update content in bulk when those downstream dependencies change. Another bonus use case is you can use the validator to find all content that uses a certain field, view, or topic to understand how much something is being used *before* you update or remove it.

  * **SCIM User Management**. Omni now supports SCIM, or System for Cross-domain Identity Management. This streamlines user identity management. It enables user management to be deferred to the authentication provider, like Rippling or Okta, and absorbed by Omni dynamically. This ensures consistency in user attributes, supports real-time synchronization of identity data, and enhances security and interoperability, facilitating efficient and secure user identity management across multiple systems and platforms.

  * **Other Improvements**.
    * \*\*Content Permissions and folders are now generally available: \*\*Check out this [quick video](https://www.loom.com/share/4b4d85530f1f4d9ea825d2e34840c45b) on how it works or [view our docs](https://docs.omni.co/share#content-access-permissions) to see what's included.
    * \*\*Model History: \*\*The model history feature now displays events from other layers, including shared models, offering a comprehensive overview. Users can compare arbitrary version events across different layers, enhancing flexibility. Navigation options have been added for easier version selection.
    * \*\*Percentiles: \*\*Introducing percentiles as a new aggregate type that users can create for measures. This aggregate type is specifically accessible through the IDE with an additional parameter for aggregate measures, as shown in the example below. [Learn more](https://docs.omni.co/modeling/measures/parameters/aggregate-type)
    * \*\*Group Names as User Attributes: \*\*Users can now utilize user groups for user attributes in order to limit access to data through implementation of user attributes with [Access Filters](https://docs.omni.co/modeling/topics/parameters/access-filters) and [Access Grants](https://docs.omni.co/modeling/models/access-grants)
    * **Table Visualization Updates:**
      * Column widths can be adjusted and there is a new fixed width mode that makes every column the same size (like a spreadsheet)
      * Column alignment options for left/right/center
      * New toggle to display or hide row numbers
    * \*\*Dashboard Filters: \*\*Filters can now be re-ordered on a dashboard by dragging them around in edit mode.
</Update>

<Update label="February 20, 2024">
  * **Content Permissions and Organization (beta)**. Now you can organize and set permissions on all your content! Content can be kept in a personal space or shared with the organization, and access is managed via folders or directly on the piece of content itself. There are 3 content permission roles (Viewer, Editor, Manager), plus a bonus AccessBoost option that allows you to give users access to run all the queries on a dashboard regardless of their connection role (that means you can now share SQL queries with non-SQL users!).

    There are many ways to flexibly design the content system of your dreams - if you're interested in testing out the beta, let us know in your support slack channel.

  * **Filterable Schedules**. Send customized dashboards to all your coworkers, partners, and clients with new schedule filters. When setting up a scheduled delivery, you can now customize the filters to ensure each recipient gets the data relevant to them.

  * **Send to Slack**. Schedule Omni content direct to Slack rooms. Whether it's that KPI dashboard going to the company channel each week, a CSV export of new leads to the Sales room, or a DM to yourself of your favorite dashboard, the possibilities are endless to get the data you need right where your team is working and collaborating everyday.

  * **Send to Webhook**. Webhooks open up a whole world of new possibilities by sending data to any 3rd party system.

  * **Dashboard Auto-refresh**. Putting a dashboard up on the big screen? Or embedding a real-time dashboard for your clients? Now you can have the data automatically update with the latest results on a cadence of your choosing.

  * **Analytics for Admins**. Take a closer look at Omni usage across your organization - which users are most active, most popular dashboards, top fields and tables used, and more! If you're an admin, you can access this from the Analytics tab in the Admin panel. And let us know [what other Omni usage information you'd like to see](https://google.com/forms/d/1bVcMwR5D6PnFREFqmpV91HD-yIAH3LFe_XeEka1bVUs/viewform?edit_requested=true) - we're always looking to add more data.
</Update>

<Update label="January 26, 2024">
  * **New Table Calculation Goodies**. We have lots of fun new calculation capabilities this week.

    **Free text entry** Arbitrary text can be entered in a calc column which opens up a whole bunch of new possibilities such as tagging and regrouping data, adding annotations to a row, adding new data to a query like rep quotas, creating static variables that can be used in other calcs, and the list goes on! See a demo [here](https://www.youtube.com/watch?v=5zjQrUOpsvg).

    **Calc GPT** Use the power of ChatGPT to help you write calculations - it has the knowledge of the full web of excel calculations at its disposal! Watch a demo [here](https://www.youtube.com/watch?v=-TWEXNNFCiQ).

    **Pivots** New pivot functions (PIVOT(), PIVOTINDEX(), PIVOTOFFSET()) are now available in the calculation syntax, unlocking new use cases like cohorts and period over period.
</Update>


# 2025 Changelog
Source: https://docs.omni.co/changelog/2025

A chronological list of new features, improvements, and bug fixes shipped to the Omni platform during 2025.

<Update label="December 28, 2025">
  * Added support for two new Spanish language locales: es-CL (Chile) and es-ES (Spain).
  * Added a button to re-run all queries in an AI chat session. This allows you to refresh stale query results when revisiting previous conversations.
  * Added automatic visualization generation in workbook AI. The AI now suggests and creates appropriate visualizations based on query results. Click the **magic wand icon** in the **Chart selector** to try it out.
</Update>

<Update label="December 21, 2025">
  * Renamed the **AI Summary Visualization** setting to **AI Visualization Summary** and updated the description to clarify that it also controls AI-generated subtitles and descriptions on charts.
  * Added `workbookUrl` as an optional parameter to the `GET /api/generate-query` endpoint. When set, the API returns a workbook URL in the response.
</Update>

<Update label="December 14, 2025">
  * Added a **Views in-use** filter option to the field picker. This shows all fields in views that have any in-use fields, making it easier to find related fields when building queries.
  * Added UI support for creating and editing duration fields in workbooks. In a workbook, right-click on a timestamp field to set it as the start timestamp, then select an end timestamp and choose which intervals to generate.
  * Added a [`GET /api/v1/users/email-only`](https://docs.omni.co/api/users/list-email-only-users) endpoint to retrieve email-only users with their user attributes. Supports cursor-based pagination and filtering by email.
  * Added a `POST /api/unstable/models/:modelId/branch/:branchName/merge` endpoint to programmatically merge a branch into the shared model. Supports options for deleting the branch after merge, publishing drafts, custom commit messages, and overriding git settings.
  * Added clipboard copy functionality to dashboard tile descriptions. Click the information icon to copy the description text to your clipboard.
  * Added a [`DELETE /api/v1/documents/{identifier}/labels/{labelName}`](https://docs.omni.co/api/document-labels/remove-label-from-document) endpoint to remove a label from a document by name.
  * Rolled out the new pie chart visualization, providing improved rendering and interactivity.
  * The Dashboard export/import API now includes spreadsheet file data. Spreadsheets are exported as base64-encoded JSON and restored during import.
  * Added granular model role permissions for AI access. Administrators can now control AI feature access and workbook access at the model role level, providing more fine-grained permission management.
  * Added support for duration type dimensions in the semantic model. Duration fields calculate the difference between two timestamps in configurable intervals (days, weeks, months, etc.).
  * Added support for including custom Omni emojis in query tab names.
</Update>

<Update label="December 7, 2025">
  * Added support for using Bitbucket with the git integration.
  * Added a new **Simple Totals** option to configuration option for stacked multi-measure charts. Enabling this setting will display simple totals on all measure series in the chart.
  * Added support for Brazilian Real (`R$`) currency formatting. To set as the default for a model, use [`default_numeric_locale: br_BR`](https://docs.omni.co/modeling/models/default-numeric-locale) in a model file.
  * Added an endpoint ([`PUT /api/v1/documents/{identifier}/labels/{labelName}`](https://docs.omni.co/api/document-labels/apply-label-to-document)) for adding labels to documents.
  * Added support for displaying percentages in pie chart tooltips.
  * Updated API endpoints to return `405 - Method not allowed` errors when an illegal method is used.
  * Added [API endpoints](https://docs.omni.co/api/labels/list-labels) for creating, updating, listing, and deleting document labels.
  * Added a new dimension modeling property ([`mask_unless_access_grants`](https://docs.omni.co/modeling/dimensions/parameters/mask-unless-access-grants) that allows you to mask data in a dimension when a user doesn't satisfy the specified access grants. Unlike [`required_access_grants`](https://docs.omni.co/modeling/dimensions/parameters/required-access-grants), this parameter doesn't block data access entirely - it only allows users to see masked values.
  * Added two new buttons to the model IDE, located next to the property documentation button: one toggles inline code search and the other toggles code folding in the current file.
  * Fully released the linked query tabs feature in workbooks! This feature allows you to create multiple visualizations from a single query tab.
  * Added options to configure border radius for slices and the padding between slices.
  * Added support for creating visualizations to the workbook Query Helper. You can now ask Blobby to make a chart from a query!
  * Added support for using filters with Level of Detail (LoD) and Top N fields. To specify filters in the model IDE, use the `filters` parameter with `level_of_detail` and `dynamic_top_n`.

    Filters are added to filters already on the query. Additionally, LoD filters work with `cancel_query_filters`, in which case Omni will cancel the query filters and apply the field specific filters when aggregating.
  * Renamed the **Size** tab to **Style** for pie/donut charts. This tab now contains radii controls for this visualization type.
</Update>

<Update label="November 30, 2025">
  * Added an endpoint for [removing a document from a user's favorites](https://docs.omni.co/api/document-favorites/unfavorite-document). If using an organization-scoped API key, requests can be made on behalf of a specific by including the userId query parameter (`DELETE /api/v1/documents/{documentId}/favorite?userId={membershipId}`).
  * Added an endpoint for [renaming documents](https://docs.omni.co/api/documents/update-document). If the optional request body `clearExistingDraft` parameter is `true`, any existing draft will also be cleared.
  * Added support for defining descriptions for topic groups. When the `topic_group_descriptions` parameter is set in a model file, group descriptions will display in the topic selector in workbooks.
  * Added the ability to have the AI summarize a chat and automatically name it.
  * Added two new skills to the AI Query Helper. Blobby can now search database schemas and generate Omni model extensions based on the results. Blobby will prompt for review before promoting its changes to the workbook.
  * Added an endpoint for [adding a document to a user's favorites](https://docs.omni.co/api/document-favorites/favorite-document). If using an organization-scoped API key, requests can be made on behalf of a specific by including the userId query parameter (`PUT /api/v1/documents/{documentId}/favorite?userId={membershipId}`).
  * Improved error messages returned by the [Run query API ](https://docs.omni.co/api/queries/run-query)when a document is missing a dashboard. Responses will now include a `Document with identifier "<identifier>" needs a dashboard to return queries` message.
  * Renamed the `group_by` parameter to `level_of_detail`.
  * Added a **View All** link to the **Favorites** page.
  * Added support for a few Snowflake and Databricks AI functions, which can be used in Omni as table calculations:

    * `AI_SUMMARIZE(text)` - Summarize text content
    * `AI_COMPLETE(prompt)` - Generate text completions (model selected automatically)
    * `AI_EXTRACT(text, labels)` - Extract structured data from text
    * `AI_CLASSIFY(text, categories) `- Classify text into categories
    * `AI_SENTIMENT(text)` - Analyze sentiment of text

    **Note:** These functions will only display as suggestions when workbooks are based on Snowflake or Databricks databases.
</Update>

<Update label="November 23, 2025">
  Added support for connecting to Snowflake via AWS PrivateLink.
</Update>

<Update label="November 16, 2025">
  * Added a new **Sort stack by** option to stacked bar charts that allows you to sort stacks by size (value).
  * Added support for changing the IDs of dashboard filters. To change a filter ID, open the **Edit filter** panel while in a draft dashboard and locate the **Advanced** section.
  * Added a **Base access section** to the new connection setup page. This allows you to specify the base level of access for a connection during the initial setup.
  * Added support for restoring previous versions of documents even when the associated branch has been deleted. Note: Archived drafts can't be restored if the associated branch has been deleted.
  * Moved content permission settings from **General > Content permissions tab** to **Settings > Content permissions**.
  * Added a new `dynamic_top_n `dimension parameter that allows you to generate `Top N` and `Bottom N`-type queries based on the sort and limit of a measure.
  * Updated the **Settings** navigation to be easier to navigate. Pages are now grouped by section; additionally, the **Billing** page has been moved to the **General** settings page as a new tab.
  * Added scope prefix labels (e.g., "My Documents", "Shared with me") to document titles in folder breadcrumbs, improving navigation clarity by showing users the ownership context of documents. The changes support both personal and shared scope documents.
  * Added support for passing user attributes to the AI Assistant via the `ai_context` parameter. Additionally, Blobby can now utilize user-specific information about the user in the chat. For example, if you say *"How are my accounts?"* Blobby will know to query data only for accounts assigned to you.
</Update>

<Update label="November 9, 2025">
  * Added support for Mustache syntax in email delivery file names.
  * Added API endpoints that allow you to manage model roles for [users](https://docs.omni.co/api/user-model-roles) and [user groups](https://docs.omni.co/api/user-group-model-roles).
  * Added support for the branch parameter to standard and 2-step SSO embed logins. This allows you to specify a branch as the starting point for an embed session, assuming the user has the permissions required for access.
  * Added the ability to create model roles with custom permissions. For example, you now can create a Querier role that doesn't have the ability to upload CSVs.
  * Added APIs that allow you to programmatically manage the dbt repository configuration for a specific Omni connection.
  * Added pagination support to the My Documents page.
  * Fully released AI file uploads! **Note**: The **File uploads** setting in [**AI Hub > General > Features**](https://docs.omni.co/ai/settings/features#file-uploads) must be enabled to use this feature.
</Update>

<Update label="November 2, 2025">
  * Added support for using opacity in map visualizations. Also added support for specifying an outline color for point and region maps.
  * Added functionality that allows users to switch between branches using URL query parameters. This enables navigation to specific branch-attached drafts directly from URLs (`?branch=<id>`), with the optional ability to pin a branch (`?branch-pin=true`).
  * Added a new workbook query tab type that allows you to create new tabs that link to a single source query tab. This enables creating multiple visualizations from the same query without duplicating the query itself.
  * Added information about delivery times to the **Edit** schedule panel. Delivery times will happen within 15 minutes of the specified time.
  * Implemented functionality that prevents triggering the same email schedule when it has more than 50 recipients AND fan-out is enabled. If using the Trigger schedule API, a `409 Conflict` error will be returned when this is attempted.
  * Removed autocomplete from the `join_from_view_as` parameter.
  * Added support for specifying custom error messages for dashboard errors and charts without results in **Dashboard > Settings**.
  * Added APIs that allow you to refresh the schema for a given connection, along with setting and listing schema refresh schedules. Give the APIs a try at `/api/connections/:connectionId/schedules`.
</Update>

<Update label="October 26, 2025">
  * Added support for filtering by ID (membership ID) to the Users API. For example: `GET /api/scim/v2/users?filter=id eq "8ae8223f-48b1-4f82-b49f-8f9ab491a59f"`

    only supports `eq` for exact matching. Additionally, this filter can also be used to retrieve embed users (`/api/scim/v2/embed/users`).
  * Added support for required dashboard filters, which must be set for the dashboard queries to run. This can be enabled for individual filters by opening the filter's Edit panel and enabling the Require a value for this filter toggle.
  * Renamed Dashboard themes to Document themes. The functionality of theming has not changed - this change is intended to clarify that themes are applied not only to documents with dashboards, but the document as a whole.
  * Updated the Dashboard AI Assistant to only require the **Summarize data** AI permission.
  * Added a `value_url_encoded` property to filters and controls in Mustache templates for Markdown tiles. This allows you to use filter and control values in URL query parameters within Markdown links.
  * Fixed an issue with applying list formatting to multi-line selections in Markdown. Previously, list formatting would only be applied to the first selected line.
  * Added a Queries menu to Markdown tiles, allowing you to access the values of queries on the dashboard in Markdown tiles.
  * Changed spreadsheet downloads to be a ZIP file containing an XLSX file for each tab in the spreadsheet.
</Update>

<Update label="October 19, 2025">
  * Previously, the `WEEKDAY` calculation treated `1` as Sunday. The calculation now mirrors Excel behavior, where `1` is Monday. **Note**: This change does not affect existing calculations, only those created after this change.
  * Updated the **Edit filter** panel on dashboards to include an **ID** field for the filter. Going forward, filter IDs should be used when referencing filters in Markdown or URLs. **Note**: This update is backwards compatible, meaning that references to filters created before this change aren't affected.
  * Added support for using LogRocket to record user sessions in embedded instances. This requires the use of a vanity domain. Reach out to Omni support to have this feature enabled.
  * Consolidated the **Add filter**, **Add tile**, and **Add control** options in draft dashboards into a single **Add** menu.
  * Fixed an issue in schedules with setting period over period and control values. Now, you can correctly set PoP and all control values.
</Update>

<Update label="October 12, 2025">
  * Added a `dashboard:filter-changed` embed event that indicates when a filter has been changed.
  * Added an `includeChecksums` query parameter to the Retrieve model YAML API. When used, the API will return the checksums for the files in the model. This is useful for reducing conflicts while a model is being developed - for example, if a teammate saves a file in your branch, but in a different browser tab.
  * Added `__omni_embed_vanity_session`, a special, Javascript accessible cookie when a user logs into embed through a vanity domain. If you use a vanity domain, this allows you to skip the server handshake by validating if a session is present before you log the user in.
  * Added in-app documentation for modeling parameters to the model IDE. Click a parameter in a file and the parameter's documentation will display in the new Property Documentation panel on the right side of the IDE.
  * Added information about the topics the AI dashboard assistant has access to the **File > Document Settings > AI on dashboard** setting description.
  * Added the ability to copy a link to a dashboard tile's underlying workbook tab to the additional options (three vertical dots) menu for dashboard tiles. Open the menu, then select **Copy > Link** to workbook tab.
  * Fixed an issue where spreadsheet downloads were enabled even if the **Downloads** content setting was disabled.
  * Added a `urlId` property to the payloads of `dashboard:filter` events, which will contain the ID of the dashboard where the event took place.
  * Added support for searching for workbook tabs to the workbook tab menu. In a workbook, click the caret on a tab to open the menu. You can then use the search box to search across the names of the tabs in the workbook.
  * Added the ability to specify custom source paths (now the **Model path** setting) using leading slash syntax to the git integration. Now, you can specify paths like `/blobsrus/models/sales` for models instead of being limited to `/omni/model_name`.
  * Added tooltips that display on hover to dashboard control fields. Now, when in the control editor, you can hover over a field and see the name of the underlying field in the database.

    Also added drag-to-reorder functionality to field picker controls.
  * Fixed an issue that was causing dashboards with large CSV uploads to load slowly.
  * Previously, documents created using invalid model IDs could not be archived. Now, document owners can correctly archive these invalid documents in their personal spaces.
  * Added a **Preview** button to the **Themes** tab (**Settings > Themes > Application Themes**. When clicked, Omni will generate a preview version using the defined theme settings.
  * Fixed an issue where calculations performed on a SQL tab were not included in PDF/PNG downloads. Calculations will now be correctly included in these download types.
  * Updated the settings for the AI dashboard assistant to include information about what the assistant does, who can use it, and accessible topics. Use the **AI Chat** tab while in a draft dashboard to view the changes and the enable/disable setting.
  * Added support for self-hosted git instances to the git integration. Use the new **Git provider** setting to select your git provider if Omni fails to detect the correct provider from your instance URL.
  * Implemented a new organization setting that allows completely disabling email magic link authentication, including for administrators. This addresses the security requirement from organizations that want SSO to be the only authentication method.
</Update>

<Update label="October 5, 2025">
  * Improved the navigation for the **Trash** page by adding tabbed navigation, which will group deleted items into **Documents**, **Branches**, and **Connections**.
  * Added `sql_preamble` as a model-level parameter, which, when set, will run as a setup step before executing any query against the model. Mustache is accepted and can be used to access user attributes.
  * Updated how dimensions are handled when a multi-field picker control is in use. Now, Omni will dynamically group and reorder fields on the dashboard without requiring changes in **Edit** mode.
  * Added a topic-level `warehouse_override` parameter, which can be used to specify a different warehouse for a specific topic.
</Update>

<Update label="September 28, 2025">
  * Added support for creating branches to the Create a model endpoint. To create a branch, set `modelKind` to `BRANCH` and specify a name with `modelName`. Branches can be created from shared or extension models.
  * Added a `dashboard:tile-drill` embed event that emits the metadata needed to generate a drill. This includes the origin of the drill interaction and the URLs needed to navigate back to the resulting drill query.
  * Added a `format` parameter to the response from the List schedules API.
  * Added a `skipParentLabel` parameter for dimensions, which allows you to control how labels are created for child fields generated from parent JSON.
  * Added support for dynamic content to webhook deliveries, specifically file names. Webhooks currently support the same date/time and schedule variables as SFTP.
  * Added support for setting a static color to region maps. Use the new **Color** property in the visualization's configuration to set a static color.
  * The Dashboard AI assistant is now GA! Check out the [docs](https://docs.omni.co/ai/dashboard-assistant) for more information.
  * Added support for using geoJSON data in a field in map visualizations.
</Update>

<Update label="September 21, 2025">
  * Added a limit parameter to the Run query API that allows the API to support unlimited queries and row limits beyond the app's current limit of 50,000. Note: This change only affects the API, not parts of the Omni app.
  * Added a **Rename** option to the column options menu. Click the three dots in any column heading in a workbook results table, then **Rename**.
  * Added support for specifying Omni user groups as email delivery recipients. **Note**: User groups will not display as an option in embed sessions.
  * Added an optional `formatResults` parameter to the Run query endpoint that controls whether spreadsheet exports (CSV, XLSX, JSON) include formatting. When set to `false`, unformatted values will be returned.
  * Updated the git settings page to display provider-specific instructions. For example, if Omni determines that a repository is hosted on GitHub, the page will display the set up instructions specific to GitHub.
</Update>

<Update label="September 14, 2025">
  * Added a history view to the model IDE. Similar to git blame, this view displays metadata about how and when lines in a model file were changed. Add `mode=history` to the URL while in the model IDE to access the view. **Note that this feature is still in development and may change.**
  * Added support for specifying a file name for webhook deliveries.
  * Added a `defaultSchema` field to List connections API responses.
  * Added a planOnly parameter to the Run query API that, when set, will return the query execution plan without running the actual query. This allows you to validate and inspect the SQL that would be generated before query execution.
  * Added support for dashboard filter validation to the Content Validator. When a field that is used in a filter is removed from a topic, the validator will now show an error.
  * Fixed an issue with the List content API where the path filter was not being correctly applied. Now, the API will return an error if a folderId and a path are specified.
  * Added support for Germany (`de_DE`) as a `default_numeric_locale`.
  * Added support for specifying cross-dialect connection environments, such as a Snowflake connection with a PostgreSQL environment. This can be useful when performing database migrations, as the environment can allow you to identify and mitigate issues in the new database.
  * Improved the Snowflake settings page by cleaning up the authentication-focused fields. The option to specify keypair authentication is now included in the Authentication menu instead of a separate toggle.
  * Fixed an issue with duplicate view file names in the model IDE. Now when Omni detects a duplicate, it will use the actual (raw) view name for all views with the conflicting view file name.
</Update>

<Update label="September 7, 2025">
  * Added support for negative (`NOT IN`) query filters, which can be specified using the `field_name_not_in_query` parameter. This filter type can be created using AI or the workbook UI.
  * Added support for using `AND` operators within groups in access grants. For example, `is_admin&is_omni|blobby` means `(is_admin AND is_omni) OR blobby`.
  * Improved the editing experience for dashboard Markdown tiles by moving the editor into a larger, resizable sidepanel. You can also now preview the appearance of tiles without needing to save and exit the editor.
  * Added a **Labels** tab to the options for small multiples / trellis charts.
  * Added troubleshooting details about failed deliveries to **Settings > Deliveries**.
  * Added a new **Styles** section to **Settings > Themes** that allows you to specify styles across your Omni application. Currently only a few button styles are supported, but more will be added in the future.
  * Added a success field to the audit logs for query execution events, which is used to indicate if a query executed successfully.
  * Removed the feature flag for the **Settings > AI** page. All Organization Admins will now have access.
  * Moved the **Edit** option to the top level of the field options menu. Previously, this option was located in **Modeling > Edit**.
</Update>

<Update label="August 31, 2025">
  * Added support for drilling to spreadsheet tabs. To use, right-click on a cell in a spreadsheet tab and select **Drill**.
  * Fully released dashboard AI! Users can now use AI chat to ask follow up questions about visualizations on dashboards. Reach out to Omni support to have this feature enabled.
  * Added a new `folder` parameter to schema views, which allows you to nest schemas in folders in the model IDE.
  * Added an option to the refresh schema dialog that allows you to skip validating views that use `SELECT *` statements during the refresh. This allows you to perform a quicker refresh, but note that the views in Omni will not reflect any schema changes.
  * Added support for inferring relationships from foreign key constraints in Postgres and Snowflake database connections. This feature allows Omni to automatically detect and create model relationships based on the foreign key definitions in the underlying database schema.
  * Fixed an issue in the Content Validator that made content metadata visible to Queriers who didn't have access to that content. Now, Queriers will only see metadata for content they can access.
</Update>

<Update label="August 24, 2025">
  * Added the ability to specify context for AI-generated visualization subtitles and descriptions.
  * Fixed an issue in Google Sheets deliveries where only the rightmost column's values were appearing when a delivery containing pivoted columns contained duplicate column names. Now, all columns will be correctly preserved.
  * Added support for selecting a drive to the Google Sheets delivery destination.
  * Added support for refreshing a specific schema and/or table. The new form for triggering a schema refresh accepts wildcards, for example `*.products`, `sales*`, etc.
  * Fully released the new Google Sheets destination for schedules. Check it out by creating a new single tile schedule in a dashboard.
</Update>

<Update label="August 17, 2025">
  * Added a new **AI on dashboard** document setting that controls whether users can access the dashboard AI in a document. To use in documents, the setting must be enabled at the organization level in **Settings > General > Content permissions**. The dashboard AI can then be enabled and disabled for individual documents in the document's settings.

  * Added two new **Move to start** and **Move to end** options to the query tab action menu. Click the caret in a query tab to open the menu and view the options.

  * Fixed a bug in the dbt integration related to pulling in `accepted_values` from dbt. Previously, if an `accepted_values` test contained a `where` condition, the values would be put into `all_values` in Omni. These values will now be placed in `sample_values`.

  * Rearranged the items in the left panel navigation in the app. The **New** button is now in the top right corner of the panel and the **AI Assistant** is slightly higher in the menu.

    **Note**: Embed users will still see the **New** button to the right of the search bar.

  * Updated **New analysis** to **Explore** throughout the Omni app. This also changed related terminology like **New analysis from here** to **Explore**.

  * Added a new option to [spreadsheet tabs](https://docs.omni.co/analyze-explore/spreadsheet-tabs) that unlocks the protected sheets in a spreadsheet tab.

  * Added support for auto-populating a specified number of groups to a new group field. Access this feature by right-clicking on a dimension in the workbook's field browser, then selecting **Group**. Use the **Auto-add** menu to open and configure the setting.

  * Added support for using [Mustache syntax](https://docs.omni.co/share/deliveries/dynamic-content) in the filenames of SFTP deliveries.

  * Added support to the AI query helper/chat that allows Blobby to create filtered measures.

  * Added support for `to:` and `to_columns:` foreign key syntax constraints to the dbt integration.

  * Added support for the SCIM contains (`co`) filter operator to the [Users API](https://docs.omni.co/api/users). This operator can be used for case-insensitive matching on `userName`s or case-sensitive matching for `embedEternalId`s.

  * Fixed a bug in spreadsheet tabs that prevented the usage of filters and sorts when interacting with an unlocked sheet on a dashboard in edit mode.

  * Updated the **Tab** menu in the workbook to display as **Query view** when looking at a **View** tab.

  * Added a button in the model IDE that allows you to open and edit a topic in a workbook, similar to how views are handled.

  * Added a new **Offloaded Schemas** connection setting which allows you to make schemas available in workbooks and SQL without fully loading them into your schema model. This setting can be used for dbt dev schemas or large info schemas you want to browse without slowing down your model.

  * Added support for syncing Databricks metric views into Omni. After a successful schema refresh, the views will be visible in the model IDE.

    To enable, check the **Enable DB semantic layer integration** box in a Databricks connection's **Settings** tab and then trigger a schema refresh.
</Update>

<Update label="August 10, 2025">
  * Fixed an issue in the dashboard editor that made editing a chart's title, subtitle, or description slow.
  * Added a new setting that allows you to specify if users can use a shared extension model as the base model in a workbook. If **Allow new analyses from this model** is checked when creating a new extension model, the model will display in the list of available models when creating a new analysis. Additionally, the options to create a new analysis from the model in the model IDE will be disabled.

    To change the settings for an existing model, navigate to **Model > Analysis source settings** when in the model IDE.
  * Added support for OpenID Connect (OIDC) authentication. Reach out to Omni support to have this featured enabled, or check out the [demo](https://omni.co/demos#oidc-launch) for more details.
  * Added support for dbt exposures to the dbt integration. Connection Admins can now create a metadata file that, when pushed to dbt, will surface where a model is used in Omni in dbt.
</Update>

<Update label="August 3, 2025">
  * Added support for drag-and-drop sorting to the field picker. Now you can click and drag individual fields to rearrange them!
  * Added support for resetting a cache policy in the model IDE via **Model > Reset cache policy**. If the model has more than one cache policy, hovering over this option will open a submenu containing the policies.
  * Added support for syncing Snowflake semantic views into Omni. After a successful schema refresh, the views will be visible in the model IDE.

    To enable, check the **Enable DB Semantic Layer integration** in a Snowflake connection's **Settings** tab and then trigger a schema refresh.
  * Updated the response from the [List users API](https://docs.omni.co/api/users/list-users) to include an `embedEmail` property, which will contain the user's embed email address.
  * Added an API for [Editing a schedule](https://docs.omni.co/api/schedules/update-schedule).
  * Updated the descriptions for connection properties to make it clearer that input tables (table upload) schemas shouldn't be included in **Include schemas**.
  * Added a new **Subtitle** field to the **chart options**, which will display a subtitle beneath the chart's main title. You can also click the ✨ (sparkles) icon to have Omni's AI generate a subtitle for you.
  * Added a new **Type** field to the configuration for X and Y axes in Cartesian charts. This allows you to override the default axis type Omni selects.
  * Added support for the [`NETWORKDAYS`](https://docs.omni.co/analyze-explore/calculations/date-time#networkdays) calculation. This calculation will return the number of whole working days between the provided `start_date` and `end_date`. **Note**: Unlike the Excel implementation, Omni does not support the `holidays` argument.
</Update>

<Update label="July 27, 2025">
  * Added support for a new [**Modeler** connection role](https://docs.omni.co/administration/users/permissions), which allows users to edit a shared model without touching the connection.
  * Added support for [defining user permissions at the model level](https://docs.omni.co/administration/users/permissions). The **Connection access** section of each connection's **Permissions** tab is now **Model access**, where you can assign permissions for users and user groups to specific models.
  * Updated queries to retain their visualization configuration when added as AI sample queries. Previously, the configuration wasn't added to the underlying `sample_queries` parameter, which resulted in needing to re-build visualizations when the sample query was used.
  * Added a `hasDashboard` property to responses from the [document APIs](https://docs.omni.co/api/documents). If `true`, the document has a workbook and a dashboard. If `false`, the document only has a workbook.
  * Added functionality to visualization legends for single measure charts that will scale the visualization to the selected metric upon clicking. Multiple metrics can be selected using `cmd + click`. **Note:** This doesn't apply to multi-measure charts... *yet!*
  * Updated the `query` parameter in `sample_queries` to be optional. This can be used to seed prompts on the blank `/chat` screen without requiring the full query specification.
  * Added a new `sets` model parameter that allows you to define reusable lists of fields. These sets can be used in other parameters that accept fields, like `drill_fields`.
  * Added support for searching for a user's name and email to the **Settings > Deliveries** page and the **Standard**, **Embed**, and **Support** tabs in **Settings > Users**.
</Update>

<Update label="July 20, 2025">
  * Added a panel for managing charts to dashboards in draft mode. Click **Charts** on the dashboard to open the panel, where you can show/hide charts.
  * Adds a new [`preserveEntityFolderContentRole` parameter](https://docs.omni.co/embed/setup/url-parameters/preserveEntityFolderContentRole) to embed. When `true`, Omni will not use the `entityFolderContentRole` to overwrite the embed user's existing content role on the entity folder.
  * KPI visualizations that use Period over Period (PoP) will no longer break when a new **Compare to** value is selected. For example, if **Compare to** is first `Previous Month` and then changed to `Previous Year`, the visualization will now correctly use `Previous Year` to display the correct value.
  * Added an API for retrieving schedule recipients and destination details. Try it out at `GET /api/v1/schedules/:scheduleId/recipients`.
  * Added support for [Mustache references](https://docs.omni.co/share/deliveries/dynamic-content) in the delivery subject and body for email and Slack deliveries. For example, `{{currentYear}}` will display the current year.
  * Added a [model-level `sample_queries` parameter](https://docs.omni.co/modeling/models/sample-queries) that allows you to define a list of sample queries that could be performed using the data in the model. This parameter is used to present example queries on the AI Assistant page and improve overall results.
  * Added an API for deleting a document draft. Deleting a draft from a branch is also supported. Give it a try at `DELETE /api/v1/documents/:identifier/draft`, providing a `branchId` with the branch's UUID in the request body if the document is on a branch.
</Update>

<Update label="July 13, 2025">
  * Added an API for creating document drafts. Creating a draft on a branch is supported. Give it a try at `POST /api/v1/documents/:identifier/draft`. To create a draft on a branch, include a `branchId` with the branch's UUID in the request body.
  * Added color and size (radius) settings to the configuration option for point map visualizations. The **Size** setting controls the radius, or spread, of displayed data points. If using a heatmap, you can use the **Color** setting to create or select an existing continuous palette.
  * Added an API for [transferring ownership of a schedule](https://docs.omni.co/api/schedules/transfer-schedule-ownership) from one organization member to another.
  * Trellis charts - also known as small multiples - are now generally available! Give this new feature a try with the **Small multiples** section in a chart's configuration.
  * Updated deliveries to stream attachments directly from S3 when webhooks, Slack, or SFTP is used as the destination.
  * Improved how the [AI Assistant / chat selects topics](https://docs.omni.co/guides/embed/ai-chat-agent) in a session and added the ability to let the AI dynamically switch between topics. Now, if you ask the AI about the data in a model, it will tell you about the available topics. **Note**: This only applies to the AI Assistant, not to the in-workbook query helper.
</Update>

<Update label="July 6, 2025">
  * Added support for duplicating dashboard themes and setting a default theme for the organization.

    In **Settings > Themes**, use the options menu (three dots) next to a theme to access the new options. **Note**: The **Apply default theme to all dashboards** will apply the selected theme to existing dashboards that don't already have an assigned theme.
  * Added the ability to sort to small multiples / chart facets. Access this in the **Small multiples** section of a chart's configuration by clicking the configuration icon in the top-right corner of the section. Then, use the **Sort** field. [Check out the demo here](https://docs.omni.co/demos/2025/20250711#buncha-trellis-improvements).
  * Fixed an issue where `{{ .value }}` references in filters would only render the first value in a multi-value string. Now, all values will correctly be included.
  * Moved the **Analyze from here** button that displayed in the top-right corner of the AI Assistant page to display next to the feedback buttons at the bottom of a message. **Note**: This only applies to the AI Assistant - the in-workbook query helper has not changed.
  * Added a new `entityFolderGroupContentRole` parameter for embedding. This parameter is used to set an embed entity group's permission level on its corresponding entity folder.
  * Added an option to Mercator map projections that will render the map as continuous when scrolling horizontally. [Check out the demo here](https://docs.omni.co/demos/2025/20250711#single-flat-map).
  * Added the ability to fill in missing values for datetimes even if a filter isn't specified. Previously, a filter was required to determine the beginning and end bounds of a time range in order to fill missing dates. With this change, Omni will use the `MIN` and `MAX` values of the field in the query result set to determine the bounds for the fill. [Check out the demo here](https://docs.omni.co/demos/2025/20250703#fill-gaps-in-any-date-series).
  * Added the ability to independently define axes for small multiples / chart facets. Access this in the **Small multiples** section of a chart's configuration by clicking the configuration icon in the top-right corner of the section. Then in the **Charts** section, use **Independent scales** setting. [Check out the demo here](https://docs.omni.co/demos/2025/20250711#buncha-trellis-improvements).
  * Updated the dbt setup flow to no longer require configuring an environment before the repository is connected. Now, you'll be directed to set up an environment after Omni successfully connects to the repository, making it easier to separately troubleshoot repository and environment issues. [Check out the demo here](https://docs.omni.co/demos/2025/20250711#dbt-environment-improvements).
  * Added a new `owners` parameter to topics, which accepts a list of email addresses indicating who the owners of a given topic are. This information can be used by the Omni AI to determine who is the best person to answer questions about a query or its results.
  * Adds a new [`ai_chat_topics`](https://docs.omni.co/modeling/models/ai-chat-topics) parameter that defines a list of topics in the model to make accessible to the AI Assistant / [embedded chat](https://docs.omni.co/ai/chat). Previously, a topic needed an `ai_context` parameter to be visible in the Assistant's topic picker. The `ai_context` will now just be context. [Check out the demo here](https://docs.omni.co/demos/2025/20250703#topic-restriction-for-ai-query).
  * Updated the [document](https://docs.omni.co/api/document-permissions) and [folder permission APIs](https://docs.omni.co/api/folder-permissions) to accept the mini UUID of a user group instead of the full UUID. This resolves the mismatch between the [User group APIs](https://docs.omni.co/api/user-groups) which returns mini IDs and the permission APIs that expected the full UUIDs.
</Update>

<Update label="June 29, 2025">
  * Added new functionality to the dbt health check dialog that will automatically compile the dbt manifest when the integration's settings are saved. This allows you to view the health check results from the run right away, making it easier to understand how the integration is set up and how to fix it. Additionally, the new dialog will notify you when a schema refresh is required to incorporate the results into Omni.
  * Fully released the new **Expand table** option for deliveries & alerts! Up to 1,000 rows in table visualizations will now be included when this option is checked.
</Update>

<Update label="June 22, 2025">
  * Added a `privateKey` parameter for Snowflake connections to the [Connection APIs](https://docs.omni.co/api/connections). This allows you to provide Snowflake private keys for keypair auth using the API.
  * Added support for Entra (Active Directory) authentication to the MSSQL database connector.
  * Added support for expanding table tiles to show all rows (up to 1,000) in deliveries and downloads. Note that there are some limitations, which are necessary to create consistent layouts:
    * In paginated deliveries, filters and controls won't be shown
    * Tile titles will be truncated
    * Font size overrides and text wrapping in cells will be disabled
    * If using PDF as the delivery/download format, single column will be unavailable
  * Updated the table migration tool (**Model IDE > Model > Migrate tables**) to now display views that have been modified in the extension model. For example, views that have been deleted or had their name changed.
  * Added a new **Small multiples** section to chart configuration, which allows you to create multiple charts from a single dataset in an Omni query.

    For example, you want to analyze total orders over time by order status and US state. Using small multiples, you can facet the data by status to create a mini chart for each status.
  * Updated Blobby to generate a query and then have the option to summarize that query.
  * Updated the full page AI chat (**AI Assistant**) feature to be enabled by default for new Omni organizations. This feature can be enabled or disabled using the **Chat** setting in [**AI Hub > General > Features**](https://docs.omni.co/ai/settings).
  * Added an [MCP Server](https://docs.omni.co/ai/mcp) to Omni's AI tooling suite. This allows you bring Omni's AI into tools like [Claude Desktop](https://docs.omni.co/ai/mcp/claude-desktop), [Cursor](https://docs.omni.co/ai/mcp/cursor), and [VSCode](https://docs.omni.co/ai/mcp/vscode) and use natural language to create and run queries - just like you would inside the Omni app.
  * Added a new `ignore_from_extended` parameter to dimensions which enables fine-grained control over field omission in explicit extensions. When set, fields with `ignored: true` are hidden only during explicit extension, but still appear in combined mode (e.g., in YAML and git), helping prevent confusion from unexpected field disappearance.
  * Added a [model-level `ai_context` parameter](https://docs.omni.co/modeling/models/ai-context), which enables adding context for AI in model files. This can be useful for providing context to Blobby for topic selection and sharing context across topics.
</Update>

<Update label="June 15, 2025">
  * Added a new **Source model name** setting to git settings which, if used, will specify the path to model files in the git repository. This can be used to assign a different name to a follower model when using follower mode.
  * Added support for specifying page sizes and orientation for [PDF downloads](https://docs.omni.co/visualize-present/dashboards/download) and [scheduled deliveries](https://docs.omni.co/share/deliveries).
</Update>

<Update label="June 8, 2025">
  * Added a new page at [**Settings > Billing**](https://docs.omni.co/administration/billing) that allows you to view past invoices for your Omni instance.
  * Added support for creating `FIXED` level of detail fields using the workbook UI.
  * Updated auto-fix suggestions in the modeling IDE to display in a tooltip that will display when hovering over an error.
  * Added an option to chart palette settings that allows you to hide palettes from palette selectors. **Note**: Hiding a palette only removes it as an option - it doesn't disable its use. Charts where the palette is applied will continue to use it.
  * Updated several dbt-related fields in the UI to use `default` instead of `target` to align more closely with dbt's terminology and reduce confusion.
</Update>

<Update label="June 1, 2025">
  * Moved the settings for AI features from **Settings > General > AI** to [**Settings > AI**](https://docs.omni.co/ai/settings) and cleaned up some of the setting names to be a bit clearer.
  * Added new shortcut options that enable starting a workbook from a specific point, such as a topic, CSV, or SQL query. To access, click the **New Analysis** button and then right-click a model or hover over the hint icon in the dropdown menu.
  * Added a new model [`slot_reservation`](https://docs.omni.co/modeling/models/slot-reservation) parameter that allows you to choose a BigQuery slot reservation to use for query runs. **Applicable only to Google BigQuery connections.**
  * Added pagination to the **Administration > Users** pages, making it easier to navigate long lists of users.
  * Updated how [PNGs in email deliveries](https://docs.omni.co/share/deliveries/email) are sent. Now, PNG files that are larger than 2MB will automatically be sent as email attachments instead of inline images, to ensure that emails are delivered successfully.
</Update>

<Update label="May 25, 2025">
  * Added support for editing topics directly in workbooks! In a draft, open a topic in the workbook and click **Model > Edit topic**. **Note**: Changes made to topics in this editor still have to be promoted from the workbook to be reflected in shared models.
  * Added functionality that automatically populates a field's `all_values` parameter using a dbt test's [`accepted_values`](https://getdbt.com/reference/resource-properties/data-tests#accepted_values).
  * Updated the location of the **Aggregation** options for fields when working in the **Chart options** sidepanel. Aggregations are now available as a shortcut on the dropdown menu for the field, instead of in **Field > Aggregation** after opening the field's options menu.
  * Added a new **Collapsible filters** dashboard setting - in a draft dashboard: **Edit > Dashboard settings** - that controls the collapsing behavior of dashboard filters.
  * Updated the AWS Bedrock model used for query generation to Claude 4 Sonnet. **Applicable only to US-based instances.**
</Update>

<Update label="May 18, 2025">
  * Added an API for [creating schedules](https://docs.omni.co/api/schedules/create-schedule).
  * Added two new embed parameters - [`entityGroupLabel`](https://docs.omni.co/embed/setup/url-parameters/entityGroupLabel) and [`entityFolderLabel`](https://docs.omni.co/embed/setup/url-parameters/entityFolderLabel) - that allow you to override the default names for folders and group names for embedded entities.
  * Added APIs for [creating and updating email-only users](https://docs.omni.co/api/schedule-recipients/bulk-manage-email-only-users) who are recipients of deliveries.
  * Added an API for [deleting a schedule](https://docs.omni.co/api/schedules/delete-schedule).
  * Added an API for [retrieving a topic in a model](https://docs.omni.co/api/topics).
</Update>

<Update label="May 11, 2025">
  * The majority of APIs are now v1! The `/unstable` routes will continue to work for the time being, but we recommend migrating existing calls to and using v1 for new development. Refer to the [API docs](https://docs.omni.co/api) for the statuses of available endpoints.
  * Added a `hide-header` search parameter which will hide the header when present on an embedded dashboard URL.
  * Moved the [AI admin settings](https://docs.omni.co/ai/settings) from **Settings > General** to its own page, **Settings > AI**.
  * Added an API for [removing recipients from a scheduled email task](https://docs.omni.co/api/schedule-recipients/remove-schedule-recipients).
  * Added an API for [retrieving a list of validation issues for a model](https://docs.omni.co/api/models/validate-model).
  * Added support for embedding the AI query helper (Blobby chat) into embedded applications. Check out the [step-by-step guide](https://docs.omni.co/guides/embed/ai-chat-agent) to get started!
  * Added APIs for [pausing](https://docs.omni.co/api/schedules/pause-schedule), [resuming](https://docs.omni.co/api/schedules/resume-schedule), and [adding recipients](https://docs.omni.co/api/schedule-recipients/add-schedule-recipients) to schedules.
  * Added an API for [retrieving a list of schedules](https://docs.omni.co/api/schedules/list-schedules). This endpoint supports filtering, sorting, and pagination.
  * Updated the [reset cache policy API](https://docs.omni.co/api/models/reset-cache) to allow empty request bodies and to return timestamps in responses.
  * Added an [`ai_context`](https://docs.omni.co/modeling/views/parameters/ai-context) property to database views.
</Update>

<Update label="May 4, 2025">
  * Added an API for [creating or overwriting model YAML files](https://docs.omni.co/api/models/create-or-update-yaml-files).
  * Added a section about [disabling caching](https://docs.omni.co/analyze-explore/performance/caching#disabling-caching) to the Caching guide.
  * Added support for pushing descriptions to dbt from Omni, accessible in the Model IDE in **Model > Push descriptions to dbt.**
  * Updated the Snowflake connector to support customer-provided private keys, if you don't want Omni to generate a keypair for you.
</Update>

<Update label="April 27, 2025">
  * Added an API for deleting YAML files from model extensions.
  * Added an API for [managing folder permissions](https://docs.omni.co/api/folder-permissions).
  * Added a new embed event, [`FilterChangeByUrlParameter`](embed/events/dashboard-filter-change-by-url-parameter), that allows parent applications to programmatically update filter values on a child iframe dashboard.
  * Refreshed the search UI in the model IDE. Now supports options to search only metadata or fields.
  * Added a section about [Filter suggestions](https://docs.omni.co/analyze-explore/point-click-queries#filter-suggestions) to the Workbook querying documentation.
  * Added support for [MariaDB](https://docs.omni.co/connect-data/setup/mariadb) as a database connection.
  * Added an API for [managing document permissions](https://docs.omni.co/api/document-permissions).
  * Added a [vertical heatmap Markdown visualization](https://docs.omni.co/showcase/visualizations/calendar-heatmaps) to the Examples gallery.
  * Added a guide about [inviting, impersonating, and deleting users](https://docs.omni.co/administration/users) in Omni. Also cleaned up the [Connection permissions](https://docs.omni.co/administration/users/permissions) guide.
  * Replaced the `include.viewCount` parameter in the [List content API](https://docs.omni.co/api/content/retrieve-content) with a new `_count` option, which will return view counts for folders and documents.
  * Updated the AI workbook calculation button to use AWS Bedrock for processing. Refer to the [documentation](https://docs.omni.co/ai/security) for more information.
  * Updated the [Create a delivery](https://docs.omni.co/share/deliveries) guide to include info about the current maximum frequency for cron schedules. Spoiler: It's an hour.
</Update>

<Update label="April 20, 2025">
  * Added a [subtotal table Markdown visualization](https://docs.omni.co/showcase/visualizations/simple-subtotal-table) to the Examples gallery.
  * Added a new [`case_insensitive` parameter](https://docs.omni.co/modeling/filters/operators/case-insensitive) to the filtering parameters, which allows you to enable case insensitive matching in string filters.
  * Added support for connection role changes to the [audit logs](https://docs.omni.co/administration/audit-logs). Now, when a connection role changes for a user, user group, or the default role changes for a connection, the event will be logged in the audit logs.
  * Updated AI query generation to use AWS Bedrock. Refer to the [updated documentation](https://docs.omni.co/ai/security) for more information.
  * Added information about how Omni generates table relationships when models are created to the [Relationships reference](https://docs.omni.co/modeling/relationships).
  * Updated the [SCIM setup guides](https://docs.omni.co/administration/authentication) to reflect that Omni organization admins must be created in the Omni UI - they can't be provisioned using SCIM.
  * Added support for editing charts directly on dashboards! On a dashboard tile, click the ⠇(three dots), then **Edit chart**.
  * Added an inbound event, [`navigate`](embed/setup/url-parameters/navigate), to embed. When sent from a parent frame to a child Omni iframe, the event triggers a redirect to the path specified in the event payload.
</Update>

<Update label="April 13, 2025">
  * Add [calendar heatmaps](https://docs.omni.co/showcase/visualizations/calendar-heatmaps) to markdown visualization example library.
  * Added support to the Athena database connector to allow for cross-account authentication.
  * Added info about UI-based SQL joins to the [Relationships reference](https://docs.omni.co/modeling/relationships/build#creating-joins-in-the-workbook).
  * Added more detail to the [dashboard tile anchors Markdown example](https://docs.omni.co/showcase/visualizations/dashboard-tile-anchors) on how to reference different anchors in a dashboard when making in-page links, table of contents, etc.
  * Added support for specifying a `roleDefinitionName` value to the Connection APIs, allowing users to specify a default connection role when creating or updating connections.
  * Added an API for [deleting a branch associated with a model](https://docs.omni.co/api/models/delete-branch).
  * Added an API for [retrieving a model's YAML specification](https://docs.omni.co/api/models/get-model-yaml).
  * Added an [AI category](https://docs.omni.co/ai) to the docs and guides for [generating AI queries](https://docs.omni.co/ai/queries) and [creating formulas](https://docs.omni.co/analyze-explore/calculations/index#ai-generated).
  * Updated the [List models API](https://docs.omni.co/api/models/list-models) to support filtering by model name.
  * Updated the [List models API](https://docs.omni.co/api/models/list-models) to support including active branches in responses.
  * Added a `viewCount` parameter to the [List content](https://docs.omni.co/api/content/retrieve-content) and [List documents](https://docs.omni.co/api/documents/list-documents) APIs.
  * Added a section to the [Dimensions parameter reference](https://docs.omni.co/modeling/dimensions) that describes how fields are ordered.
  * Added two new parameters to the [`sample_queries` topic parameter](https://docs.omni.co/modeling/topics/parameters/sample-queries): `hidden` and `exclude_from_ai_context` parameters.\\
  * Added an API for [retrieving models](https://docs.omni.co/api/models/list-models).
  * Updated the [Dashboard theming guide](https://docs.omni.co/visualize-present/dashboards/theming) to include all currently-possible properties.
  * Released the dashboard performance page, which allows you to analyze the query performance of the tiles on a given dashboard. Document editors can access this feature in a published dashboard by navigating to **View > Performance profile**.
</Update>

<Update label="April 6, 2025">
  * Added an API that supports programmatically [adding recipients to an existing scheduled email task](https://docs.omni.co//api/schedule-recipients/add-schedule-recipients). The endpoint accepts a comma-separated list of membership IDs and adds those users as recipients to the scheduled task's email destination.
  * Split the [AI summary settings](https://docs.omni.co/ai/settings) into two to allow for more granular control of AI summary features: **Allow data summarization**, which allows Blobby to summarize trends, and **AI summary visualization**, which enables the **AI summary** visualization type.
  * Added support for [editing query views in the UI](https://docs.omni.co/analyze-explore/saved-views).
  * Added support for filtering to calculated fields.
  * Updated the [AWS PrivateLink guide](https://docs.omni.co/connect-data/aws-privatelink) to clarify the types of VPCs Omni supports: only normal endpoints, not Redshift-managed.
  * Added an API for [listing database connections](https://docs.omni.co/api/connections/list-connections).
  * Cleaned up the sidebar in the docs to focus more on "jobs to be done" and less on product features. This change also removes some old categories and consolidates a few others.
  * Moved the [API docs](https://docs.omni.co/api) into a top-level section of the docs, now accessible in the top navigation as **API**.
  * Renamed the **Jobs** page to **Running queries** to make it clearer what the page contains.
  * Updated the code for some Markdown examples to correctly render when exported to PDF or PNG.
</Update>

<Update label="March 31, 2025">
  * **Data inputs now available!** - The wait is over! You can now upload CSV and XLSX files or manually enter data into Omni to create source tables. This highly requested feature makes it easier than ever to bring external data into your analyses - database optional.

    Once created, data input tables can be queried and modeled just like any other table in your database. [Check out the docs to learn more](https://docs.omni.co/analyze-explore/data-input-csvs).

  * **New workbook starter now in beta** - As part of our mission to eliminate analysis paralysis, we're developing a new query tab experience that makes it easier to get started with your data.

    Now, when you create a new workbook or query tab, you can browse database views and topics, write a SQL query, or add a data input table.

  * **dbt tooling enhancements** - The new **dbt environment health dialog**, accessible by clicking **Health** in the footer of the IDE, can help you monitor issues in your dbt environment.

    Additionally, you can now bring your dbt metadata in Omni up to date with just a few clicks. In the dbt IDE, navigate to **Model > Sync dbt metadata** and Omni will kick off a metadata sync.

  * **Promote color modeling from the workbook** - Color modeling is now complete for both dimensions and measures! In the **Color options** for charts, you can set colors for multiple measures, including those that already have a color defined in the model.

    Once set, you can then promote the colors to the workbook model, which will apply the colors across the entire workbook.

  * **Connect to StarRocks** - If you're using StarRocks, you can now connect it to Omni! Check out the [StarRocks setup guide](https://docs.omni.co/connect-data/setup/starrocks) for more information.

  * **M2M authentication for Databricks** - We've added another authentication option, machine-to-machine (M2M), to the Databricks integration. You also have the option to use a personal access token (PAT). Refer to the [Databricks setup guide](https://docs.omni.co/connect-data/setup/databricks) for more information.

  * **Dashboard control enhancements** - We added a new control type, **Field picker**, that allows you to select one or more fields to include in the control.

    Additionally, dashboard controls are now accessible in text tiles using Mustache syntax. Check out [the docs](https://docs.omni.co/visualize-present/dynamic-content) for more info and examples.

  * **All the APIs!** - We've expanded our library of APIs over the last few weeks with a bunch of new endpoints:

    * [List content](https://docs.omni.co/api/content/retrieve-content)
    * [Create a document](https://docs.omni.co/api/documents/create-document)
    * [Delete a document](https://docs.omni.co/api/documents/delete-document)
    * [Trigger a schedule](https://docs.omni.co/api/schedules/trigger-schedule)
    * [Reset a cache](https://docs.omni.co/api/models/reset-cache)
    * [Generate an AI query](https://docs.omni.co/api/ai/generate-a-query)

  * **Lots of documentation updates!**:
    * [Revised AI data security guide](https://docs.omni.co/ai/security) now includes information about AWS Bedrock and recently-added [AI features](https://docs.omni.co/ai/settings)
    * New guide for connecting databases using [Amazon Web Services (AWS) PrivateLink](https://docs.omni.co/connect-data/aws-privatelink)
    * New guide about [working with dbt models in Omni](https://docs.omni.co/integrations/dbt/models)
    * Updated [dbt setup guide](https://docs.omni.co/integrations/dbt/setup)
    * New and improved videos in the [Model IDE developer guide](https://docs.omni.co/modeling/develop/guides/model-ide)
    * Revised [database setup guides](https://docs.omni.co/connect-data/setup), now with info about user permission requirements
    * New visualization examples!
      * [Pie chart with custom legend](https://docs.omni.co/showcase/visualizations/pie-donut-custom-legend)
      * [Candlestick card](https://docs.omni.co/showcase/visualizations/card-target-candlesticks)

  * **Honorable mentions**:
    * New [heatmap projection type](https://docs.omni.co/visualize-present/visualizations/types/map) for point maps
    * New [`NOT()` formula](https://docs.omni.co/analyze-explore/calculations/logic#not)
    * Expanded options for copying values in a workbook
</Update>


# Product updates
Source: https://docs.omni.co/changelog/index

Stay current with the latest Omni product updates, including new features, platform improvements, and bug fixes for 2026.

<Tip>
  **Want to be notified about new updates?** Click the **Subscribe** button and use the URL to set up an RSS feed in [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) or an [RSS aggregator](https://feeder.co/).
</Tip>

<Update label="Week of August 31, 2026">
  **Administration**

  * Added support for [customizing the main navigation](https://docs.omni.co/administration/settings/sidebar) in Omni.
  * Skills can now be enabled and disabled at the [organization level](https://docs.omni.co/ai/settings/features#skills).
  * Omni now supports Canada Central, UAE North, and Southeast Asia cloud regions for Azure deployments.

  **AI**

  * You can now [download a dashboard as a PNG file](https://docs.omni.co/ai/mcp/tools#start-dashboard-download) directly from an MCP client, using three new tools: `startDashboardDownload`, `checkDashboardDownload`, and `fetchDashboardDownload`.
  * Apps are now generally available.
  * Chat now defaults to the [Standard model tier](https://docs.omni.co/ai/chat#selecting-an-ai-model-tier) when no model or organization tier is configured, rather than starting on Smartest.
  * Added the [**Allow clipboard copy**](https://docs.omni.co/visualize-present/apps/settings#clipboard-copy) app setting, which grants an app's iframe permission to copy text or values to the user's clipboard.
  * Apps are now enabled by default in embedded Omni instances.
  * The Omni Agent can now automatically identify and fix console errors when modifying an app in draft mode.
  * Organization Admins will now receive [email notifications](https://docs.omni.co/ai/settings/usage#org-notifications) when AI credit usage reaches 75% and 100% of organization-level thresholds.
  * Renamed the Dashboard Agent to [Chat with Content](https://docs.omni.co/ai/dashboard-assistant).

  **API**

  * You can now set a folder's organization-wide role and/or turn on [AccessBoost](https://docs.omni.co/api/folder-permissions/update-folder-permission-settings) for that access using the API, without naming individual users or groups.
  * Added API endpoints to [read, create, and replace](https://docs.omni.co/api/apps) an app's HTML and settings on a document draft, so apps can be built and updated programmatically before publishing. These endpoints are currently in development and may change.
  * Added an [endpoint to read a document's published app content](https://docs.omni.co/api/apps/read-app-content), including its HTML and sandbox settings. This endpoint is still in development and may change.
  * Fixed an issue where the document and folder permissions APIs let a user-scoped API key enable [AccessBoost](https://docs.omni.co/share#boosting-permissions-with-accessboost) without the required permission. These endpoints now enforce the same organization and per-user AccessBoost provisioning rules as the Omni UI.
  * Added an endpoint that [moves a shared or shared extension model to the trash](https://docs.omni.co/api/models/archive-shared-or-extension-model).
  * Added support for v2 documents APIs to recognize app documents.
  * The [List document queries endpoint](https://docs.omni.co/api/documents/list-document-queries) no longer requires that a document have a dashboard.
  * Removed the deprecated v1 document write endpoints.
  * You can now use the [Create AI job endpoint](https://docs.omni.co/api/ai/create-ai-job#dashboard-creation-and-publishing) to create and publish dashboards.

  **Content**

  Apps can be embedded using the [Share dialog](https://docs.omni.co/share#sharing-content-externally).

  **Dashboards**

  Updated the [cross-filtering documentation](https://docs.omni.co/visualize-present/dashboards/filter-interactivity#cross-filtering) to correctly describe how tiles appear when a focused cross-filter can't be used.

  **Embedding**

  * Removed the `hideHeader` and `hideNavigation` settings from the `uiSettings` embed URL parameter.
  * Added the ability for [embed users to provision AccessBoost](https://docs.omni.co/share#accessboost-in-embedded-omni) when the appropriate organization settings are enabled.
  * Released v1 of the Omni Embed SDK, which includes a new signing format for standard SSO. This format replaces the deprecated v0 format, which will be unsupported after October 1, 2026, and removed by January 1, 2027. See [Migrating to the v1 embed signing format](https://docs.omni.co/embed/setup/standard-sso/migrate-to-latest) for more information.

  **General UI**

  * Clicking **Develop** now opens the model IDE directly for organizations with only one model, skipping the model list. Organizations with multiple models, or a model with shared extensions, still see the list as before.
  * Dashboards and apps now have a **Model** menu, which you can use to access the underlying model.

  **Integrations**

  * [Snowflake semantic views](https://docs.omni.co/connect-data/snowflake-semantic-views) now import as topics on a schema refresh, with their logical tables, relationships, metrics, filters, and AI instructions. See the [limitations](https://docs.omni.co/connect-data/snowflake-semantic-views/limitations) for what doesn't import.
  * Added a **Models** tab to the connection settings page, listing the shared models scoped to that connection.

  **Modeling**

  * Added support for [`required_access_grants`](https://docs.omni.co/modeling/composite-topics/parameters/required-access-grants) on composite topics.
  * Added support for custom calendars, so a model can define its own year, quarter, month, and week boundaries from a calendar table in the warehouse (for example, a retail 4-5-4 calendar) instead of using the Gregorian calendar. Docs coming soon.
  * You can now specify `week_start_day` configuration option at the [topic](https://docs.omni.co/modeling/topics/parameters/week-start-day) and [dimension](https://docs.omni.co/modeling/dimensions/parameters/week-start-day) level.

  **Workbook**

  * The AI input option will no longer display in empty workbook tabs.
  * Added **List** and **Count distinct** as quick aggregations options for date fields.
</Update>

<Update label="Week of August 24, 2026">
  **Omni Agent memory support**

  Users can now [save information as personal context](https://docs.omni.co/ai/chat#memory) to use with the Omni Agent. Organization Admins can enable and disable this feature in **AI Hub > General > Features**.

  **Improved Omni Agent workbook editing**

  Previously, the Omni Agent would auto-apply generated queries and charts to the active tab when used in workbooks. Now new queries and charts will be first shown in chat, so the active tab isn't overwritten.

  **Omni CLI v1.2**

  [Omni CLI v1.2](https://github.com/exploreomni/cli/releases/tag/v1.2.0) is out, with a few new capabilities and a round of fixes to output and help-text accuracy. See the **CLI** section below for a detailed look at what's in the release.

  **Administration**

  * Added support for [Canada, UAE, and Southeast Asia cloud regions](https://docs.omni.co/administration/security/cloud-regions) for Azure-based deployments.
  * Added Korean (ko-KR) [localization support](https://docs.omni.co/administration/localization).
  * Added a `connection_id` property to the [`QUERY_EXECUTE` audit log event](https://docs.omni.co/administration/audit-logs/event-types#query-execution-events).
  * [Connection Admin permissions](https://docs.omni.co/administration/users/permissions-reference#modeling) are now required to rename a shared model or shared model extension.
  * You can now view per-user AI credit usage in the [**AI Hub > General > Credit usage** tab](https://docs.omni.co/ai/settings/usage#user-entity-usage).
  * You can now set the per-user default AI credit limit cap from the [**AI Hub > General > Credits** tab](https://docs.omni.co/ai/settings/usage#per-user-default).

  **AI**

  * You can now edit dashboards using the [MCP Server](https://docs.omni.co/ai/mcp/tools#ask-omni), [Omni Slack Agent](https://docs.omni.co/integrations/omni-slack-agent#editing-dashboards), or [Create AI job API](https://docs.omni.co/api/ai/create-ai-job#dashboard-creation-and-publishing).
  * You can now navigate between workbook tabs by asking the Omni Agent.
  * Added the [Open to buy app](https://docs.omni.co/library?q=buy\&item=open-to-buy) to the Library.

  **API**

  * Added a [`cache` parameter](https://docs.omni.co/api/dashboard-downloads/initiate-download#body-cache) to the Download dashboard endpoint.
  * Added user impersonation support to the [Search dashboards API](https://docs.omni.co/api/content/search-dashboards#parameter-user-id).
  * Added the [Search Omni docs API](https://docs.omni.co/api/ai/search-omni-docs) to the REST API reference.

  **CLI**

  * `--body` now accepts `@path/to/file.json` to read a request body from a file, or `-` to read it from stdin, and validates it as JSON client-side before sending.
  * `--schema` is now available on every command, printing that command's arguments, flags, request body, and response shape without making an API call. See [output formats](https://docs.omni.co/developers/cli/commands#api-commands) for examples.
  * Required query parameters are now validated before a request is sent, and a `--query key=value` escape hatch is available for parameters not yet reflected in the CLI's generated flags.
  * Fixed several correctness issues: `-p`/`--profile` is now honored by `config login` and `config logout`, broken configs and unknown profiles no longer get misreported as a missing API token, stdout stays clean on failed requests, unrecognized subcommands now error instead of doing nothing, and flag names and help text are more reliably in sync with the generated commands.

  **Embedding**

  Added an [organization-level setting](https://docs.omni.co/embed/admin/security#user-credit-usage) that allows you to opt in to showing embed users their AI credit usage.

  **Integrations**

  Added a guide about [embedding dbt health tiles](https://docs.omni.co/guides/dashboards/dbt-data-health-tiles) into Omni dashboards.

  **Modeling**

  Added support for specifying [cache policies](https://docs.omni.co/modeling/composite-topics/parameters/cache-policy) on composite topics.
</Update>

<Update label="Week of August 17, 2026">
  **Apps can now be embedded**

  [Apps can be embedded](https://docs.omni.co/visualize-present/apps/index#embedding-apps) in your own product with the same SSO embed flow used for dashboards and workbooks.

  **Administration**

  * Added an [**AI credit usage** section](https://docs.omni.co/administration/users/your-account#ai-credit-usage) to the **Your Account** page.
  * Moved organization-level settings for apps to [**Settings > Apps**](https://docs.omni.co/administration/settings/app-policy).

  **AI**

  * You can now [delete an AI Routine](https://docs.omni.co/ai/routines#deleting-routines) while chatting with the Omni Agent, as long as the routine is currently open alongside the chat.
  * Added support to the MCP [`askOmni` tool](https://docs.omni.co/ai/mcp/tools#ask-omni) that allows targeting a specific branch.
  * Added a [`listBranches`](https://docs.omni.co/ai/mcp/tools#list-branches) tool to the MCP server.

  **API**

  Deprecated the [Transfer document ownership API](https://docs.omni.co/api/documents/transfer-document-ownership) and updated to demote existing `OWNER` users to `MANAGER` upon successfully transferring ownership to the named user.

  **This endpoint will continue to function**, but use the [Document permissions](https://docs.omni.co/api/document-permissions/grant-document-permissions) APIs to manage document ownership going forward.

  **Content**

  * Added the ability to undo access removal in the [**Share** content dialog](https://docs.omni.co/share#assigning-access-roles-to-content).
  * Users can now be assigned the [**Owner** role](https://docs.omni.co/share#ownership) from a document's **Share** dialog.

  **Dashboards**

  If you attempt to navigate away from dashboard settings before saving, Omni will now prompt you for confirmation so you don't lose your changes.

  **Deliveries & Alerts**

  Added a notice to the [**Slack** scheduling form](https://docs.omni.co/integrations/omni-slack-agent#optional-scopes-2) that explains when Omni deliveries will be sent as secure, expiring links instead of file attachments.

  **Embedding**

  * Embedded apps now emit an [`app:event`](https://docs.omni.co/embed/events/app-event) event when the app's code calls `omni.emit`.
  * Embedded apps now emit an [`app:filter-changed` event](https://docs.omni.co/embed/events/app-filter-changed) when a filter on one of its queries is changed after the app loads.
  * Added a [`showHeader`](https://docs.omni.co/embed/setup/url-parameters/uiSettings#param-show-header) option to the embed `uiSettings` URL parameter.
  * Embedded apps and dashboards now emit a [`size`](https://docs.omni.co/embed/events/size) event when the iframe loads or is resized.
  * Embedded apps and dashboards now emit a [`fullscreen:changed`](https://docs.omni.co/embed/events/fullscreen-changed) event when the fullscreen state changes.
  * Added support for programmatically controlling embedded content's fullscreen state with the [`fullscreen:set`](https://docs.omni.co/embed/events/fullscreen-set) event.

  **Integrations**

  * Omni now tags Databricks queries with Omni identifiers.
  * Updated the [dbt environment form](https://docs.omni.co/integrations/dbt/environments) to better explain how values are copied from a project's `profiles.yml` file.
  * Added support for wildcards and exclusions in the **Include Other Databases** connection setting.
  * Refreshed the [dbt integration docs](https://docs.omni.co/integrations/dbt) and added a [dbt metadata reference](https://docs.omni.co/integrations/dbt/metadata-reference) describing what metadata can be synced into Omni.

  **Modeling**

  Forecasting can now be disabled in a model's [`ai_settings.disabled_tools`](https://docs.omni.co/modeling/models/parameters/ai-settings/disabled-tools).
</Update>

<Update label="Week of August 10, 2026">
  **Administration**

  * Omni will now prompt for confirmation when updating the **Delivery personalization** setting. Additionally, changing this setting will now add an [audit log entry](https://docs.omni.co/administration/audit-logs/event-types#delivery-personalization-updated).
  * Added the ability to manage a user's group memberships directly from the [**Groups** tab on the user's settings page](https://docs.omni.co/administration/users/groups#user-profile-group).
  * Added [**Create Apps**](https://docs.omni.co/administration/users/custom-roles#permissions-reference) as a granular permission for custom roles.

  **AI**

  * Apps now respect formatting applied to workbook fields, such as currency or decimal places.
  * AI credit usage can now be viewed in the AI Hub in the **Credit tracking** tab.
  * Fixed an issue where apps were not correctly identifying totals and subtotals in query results.
  * [Default discrete and continuous chart palettes](https://docs.omni.co/visualize-present/apps/styling#charts) can now be used in charts in apps.
  * The Omni Agent can now create composite topics.
  * The Omni Agent now uses the settings in [`ai_settings.build_configuration`](https://docs.omni.co/modeling/models/parameters/ai-settings/build-configuration) to create dashboards instead of inferring them from the prompt context.
  * Updated the [Library](https://docs.omni.co/library) with several new apps:
    * [Omni Migration Tracker](https://docs.omni.co/library?q=migr#omni-migration-tracker)
    * [Survivor](https://docs.omni.co/library?q=survi#survivor-app)
    * [Reorder planner](https://docs.omni.co/library?q=reor#reorder-planner)
    * [Marketing channel performance and forecast](https://docs.omni.co/library?q=marketing#marketing-channel-performance-and-forecast)
    * [dbt health and data lineage](https://docs.omni.co/library?q=dbt#dbt-health-and-data-lineage)
    * [Guided Omni tour](https://docs.omni.co/library?q=guid#omni-the-guided-tour)
    * [Signal desk](https://docs.omni.co/library?q=signal#signal-desk)

  **API**

  Added an [`explorable`](https://docs.omni.co/api/models/list-models#parameter-explorable) filter option to the List models API.

  **Content**

  * Personal content that has been shared with you is now visible in the [**Shared with me** page](https://docs.omni.co/content/navigate).
  * Added the ability to [share personal content](https://docs.omni.co/share#organization) with an entire organization.
  * The **Shared with me** page now displays the highest-level folder you have access to instead of adding an item for each subfolder. Click a folder to access subfolders.

  **Dashboards**

  * Added the ability to [stop dashboard queries](https://docs.omni.co/administration/running-queries#dashboard-queries).
  * [Dashboard preview mode](https://docs.omni.co/visualize-present/dashboards/preview-mode#entering-preview-mode) now supports full-screen editing.

  **Deliveries & Alerts**

  * The [email recipient domain allowlist](https://docs.omni.co/share/deliveries/email/domain-allowlist) now accepts up to 1,000 email domains.
  * Added a guide about [personalization for email deliveries](https://docs.omni.co/share/deliveries/email/personalization) to the docs.

  **Embedding**

  Added support for setting [entity AI credit limits](https://docs.omni.co/embed/setup/url-parameters/entityAiCreditLimit) through an embed URL parameter.

  **Integrations**

  * Renamed the **Development** page in the dbt IDE to [**Sync**](https://docs.omni.co/integrations/dbt/syncing-dbt).
  * Added guides for [managing dbt environments](https://docs.omni.co/integrations/dbt/environments) and [debugging dbt sync issues](https://docs.omni.co/integrations/dbt/debugging-sync-issues) to the dbt docs.

  **Modeling**

  * Added support for [`default_filters`](https://docs.omni.co/modeling/composite-topics/parameters/default-filters) on composite topics.
  * The `@` prefix is no longer required for [SQL references in shared measures](https://docs.omni.co/modeling/composite-topics/parameters/shared-measures).
  * Added documentation explaining how to use sketch-based approximate aggregates (such as HyperLogLog and APPROX\_PERCENTILE) with [aggregate awareness routing](https://docs.omni.co/analyze-explore/performance/aggregate-awareness#using-sketch-based-approximate-aggregates) in Snowflake, BigQuery, and Databricks.
  * Added a guide for [customizing filter suggestions](https://docs.omni.co/guides/modeling/filter-suggestions).

  **Workbook**

  Changes in [spreadsheet tabs](https://docs.omni.co/analyze-explore/spreadsheet-tabs#saving-your-work) are now autosaved.
</Update>

<Update label="Week of August 3, 2026">
  **Administration**

  * [Localization settings](https://docs.omni.co/administration/localization) are now available in all Omni instances.
  * Added the ability for admins to customize the label of the SAML login button on the login page.
  * Added the ability to filter user attributes by value on the [**User attributes**](https://docs.omni.co/administration/users/attributes#assigning-attributes-to-users) page.
  * Organization Admins can now [impersonate pending user invites](https://docs.omni.co/administration/users/impersonate#impersonating-a-pending-invite).
  * Added the [**Trash visibility window** general setting](https://docs.omni.co/administration/settings#trash-visibility-window), which controls how long archived content is visible in the **Trash**. Content older than the retention window is automatically hidden.
  * Added additional event types to the [Audit log event types](https://docs.omni.co/administration/audit-logs/event-types) reference.
  * Added a new [**Opt out of product announcements** setting](https://docs.omni.co/administration/settings#opt-out-of-product-announcements) that lets Organization Admins disable in-app product announcements from Omni.

  **AI**

  * Added a new [`searchDashboards` MCP tool](https://docs.omni.co/ai/mcp/tools#search-dashboards). Enable or disable in **AI Hub > MCP** with the [**Content access**](https://docs.omni.co/ai/settings/mcp#content-access) setting.
  * Added [**Navigation** settings](https://docs.omni.co/visualize-present/apps/settings#navigation) to apps, allowing you to control how Omni apps open links.
  * Added the ability to use the Omni Agent to build an app directly within your current workbook.
  * Fixed an issue where the Omni Agent would overwrite workbook tabs when generating new queries or applying updates to existing queries.
  * When hard caps are defined for AI usage, Organization Admins must now [enable overage billing](https://docs.omni.co/ai/settings/usage#hard-cap) to continue using AI features.

  **Deliveries & Alerts**

  Updated the organization-level [**Delivery personalization**](https://docs.omni.co/administration/content-permissions#delivery-personalization) content permission setting to use three modes: **Per delivery**, **Always**, and **Never**.

  **General UI**

  * Added a full-screen presentation mode for apps, dashboards, and workbooks that hides the interface and displays content in full screen.
  * You can now sort **My documents** in the content library, and your sort preference will be remembered for future sessions.

  **Integrations**

  * Field names that contain Unicode characters are now supported for connections created after August 3, 2026. For connections created before this date, Unicode field names are disabled to prevent breaking existing content. Contact support if you need to enable this feature for older connections.
  * Added dbt environment management capabilities to the modeling IDE.
  * Updated the [Dynamic connection environments guide](https://docs.omni.co/connect-data/dynamic-environments) to include information about environment resolution order and multi-value user attribute behavior.
  * Updated the [Amazon Redshift setup guide](https://docs.omni.co/connect-data/setup/redshift#connecting-to-redshift-datashares) to include information about connecting to Redshift datashares.

  **Modeling**

  * Added support for disabling dashboard generation through the [`ai_settings.disabled_tools`](https://docs.omni.co/modeling/models/parameters/ai-settings/disabled-tools) model-level setting.
  * Added a new [`bind_outer_context`](https://docs.omni.co/modeling/query-views/parameters/bind-outer-context) parameter to query views, which will resolve `is_selected`, `is_filtered`, and `in_query` template variables against the outer query instead of the view's own query.

  **Visualization**

  Added an option to revert relabeled table visualization fields to the label defined in the model.
</Update>

<Update label="Week of July 27, 2026">
  **Administration**

  [AI credit controls for embed entity groups](https://docs.omni.co/embed/admin/ai-credits) are now generally available.

  **AI**

  * Fixed an issue where the Workload Identity Federation (WIF) role prefix wasn't properly configured across all AI-calling services, which could cause authentication failures when using [Google Gemini Enterprise Platform (Vertex)](https://docs.omni.co/ai/settings/model-providers/google-vertex-ai) as a custom AI model provider.
  * AI Evals are now supported for [Omni instances hosted on Azure](https://docs.omni.co/administration/security/cloud-regions).
  * Added the ability to [inspect and annotate elements](https://docs.omni.co/visualize-present/apps/inspect) in Apps.
  * Apps will now persist their state to shareable URL parameters, allowing you to share specific views of apps with other users.

  **API**

  * Added an endpoint for [bulk adding and removing folder labels](https://docs.omni.co/api/folder-labels/bulk-update-folder-labels).
  * Added an endpoint for [retrieving an embed entity group's AI credit usage](https://docs.omni.co/api/ai-credit-usage/read-individual-entity-groups-ai-credit-usage).
  * Added a new API endpoint that allows you to [replace data in an uploaded dataset](https://docs.omni.co/api/uploads/replace-upload-data).
  * Added support for `.composite_topic` file names in model YAML endpoints.
  * Added an endpoint for [retrieving individual users' AI credit usage](https://docs.omni.co/api/ai-credit-usage/read-individual-users-ai-credit-usage).

  **Content**

  Added type filters to the [**My Activity** page](https://docs.omni.co/content/activity) to help you narrow down activity records by type, and removed the classic view option.

  **Dashboards**

  * Added a **Mapping** tab to the properties panel for dashboard query tiles. This centralized tab allows you to map filters and controls to the query.
  * Increased the [maximum number of queries allowed in an app](https://docs.omni.co/visualize-present/apps/index#limitations) from the previous limit to 100.
  * [Embedded dashboards will now use the new dashboard editor by default](https://docs.omni.co/visualize-present/dashboards/containers-items#requirements). Reach out to Omni support if you need to disable this for your instance.

  **Embedding**

  * Added [`dashboardGeneratedAt`](https://docs.omni.co/embed/setup/url-parameters/uiSettings#param-dashboard-generated-at) and [`tileRanTimestamp`](https://docs.omni.co/embed/setup/url-parameters/uiSettings#param-tile-ran-timestamp) as embed URL [`uiSettings`](https://docs.omni.co/embed/setup/url-parameters/uiSettings) options.
  * Per-user AI credit limits can now be set through the [`userSettings` embed URL parameter](https://docs.omni.co/embed/setup/url-parameters/userAttributes#manage-ai-credit-limits).

  **General UI**

  Personal appearance preferences (theme and display settings) will now persist across sessions.

  **Integrations**

  * Added instructions for [GitHub App authentication](https://docs.omni.co/integrations/git/setup/github#github-app) to the GitHub integration setup guide.
  * Added instructions for authenticating a dbt git repository with the Omni GitHub App to the [dbt setup guide](https://docs.omni.co/integrations/dbt/setup#github-app).

  **Modeling**

  * Added [`default_group_by`](https://docs.omni.co/modeling/models/default-group-by) as a model-level parameter. This allows you to control how measureless queries in the model are grouped by default.
  * Updated the [Content Validator documentation](https://docs.omni.co/modeling/develop/content-validator#suppressing-validator-issues) with information about automatic issue suppression in the model IDE.

  **Visualization**

  Added the ability to position and hide the legend in map visualizations.
</Update>

<Update label="Week of July 20, 2026">
  **Administration**

  * Added support for [Arabic (ar-SA) localization](https://docs.omni.co/administration/localization#locale).
  * Added a [**Chat panel side** user setting](https://docs.omni.co/administration/users/your-account#chat-panel-side), which allows you to select your preferred side for the AI chat panel.
  * Added support for [Thai (th-TH) localization](https://docs.omni.co/administration/localization#locale).
  * Added support for [Simplified Chinese (zh-CN) localization](https://docs.omni.co/administration/localization#locale).
  * Updated the [Authentication settings reference](https://docs.omni.co/administration/settings/authentication) to reflect the recent change to per-method sign in toggles.

  **AI**

  * Added support for [enabling and disabling AI integrations](https://docs.omni.co/ai/chat#managing-ai-integrations) in the chat interface.
  * AI Routines can now be created from chat.
  * Added persistence of [app filter values to URL parameters](https://docs.omni.co/visualize-present/apps/index#filters).
  * Dashboards returned in AI chat search results or in Slack responses will now be hyperlinked.
  * AI-powered semantic model generation is now generally available.
  * Updated the [AI context management guide](https://docs.omni.co/modeling/develop/ai-optimization) to reflect the current order of context pruning in Omni.

  **API**

  * Added `fileUploadId` to the Documents v2 endpoints, allowing you to access file upload identifiers for source tabs.
  * Added APIs that allow you to change a tile's query model binding.
  * Added a `workbookUrl` parameter to the [Run query API](https://docs.omni.co/api/queries/run-query#body-workbook-url) that, when set, tells the API to return an ephemeral workbook URL in successful responses.
  * Updated the Connections APIs to return full connection details when creating and updating connections.
  * Added a `model_extension_id` property to the `queryPresentations` schema used in Documents v2 endpoints, which identifies a query tile's bound query model and is returned on read (omitted for linked-type tiles).
  * Added support for including image and PDF attachments in requests made to the [Create AI job API](https://docs.omni.co/api/ai/create-ai-job).
  * Added a new API endpoint to update embed entity-group AI credit limits. **This feature is still in development.**
  * Added support for entity-group default credit limits on the AI credit-controls endpoints. **This feature is still in development**.
  * Added a new API endpoint that allows you to retrieve a list of embed entity-group AI credit limits. **This feature is still in development.**
  * The [Create AI job endpoint](https://docs.omni.co/api/ai/create-ai-job) now uses the supplied `branchId` parameter as the modeling write target, allowing you to specify which branch model changes should be written to instead of automatically creating a new branch.
  * Updated the Document permission APIs to include all currently supported document abilities.
  * Revamped API documentation with reorganized navigation by resource area, a new landing page, and a per-endpoint [versioning reference](https://docs.omni.co/api/versioning).

  **Content**

  * Apps can now be rendered as homepage content.
  * Added a [new setting that allows you to configure the root folder](https://docs.omni.co/content/organize#scoping-folder-navigation-with-breadcrumb-roots) displayed in the breadcrumb navigation for folders.
  * Added support for [displaying a specified dashboard on users' homepages](https://docs.omni.co/content/navigate#custom-homepage-dashboard).

  **Dashboards**

  Added documentation for per-dashboard container [mobile behavior overrides](https://docs.omni.co/visualize-present/dashboards/containers-items#mobile-behavior).

  **Integrations**

  * Added GitHub App authentication as an option when setting up dbt connections.
  * Added support for exclusion patterns in the [**Include schemas**](https://docs.omni.co/connect-data/schema-restriction) and [**Offloaded schemas**](https://docs.omni.co/connect-data/offloading-schemas) connection settings.
  * Added support for using a GitHub app to authenticate a GitHub repository to Omni.
  * Added a new guide explaining how to [safely rename a git-connected shared model's display name](https://docs.omni.co/guides/modeling/rename-git-connected-shared-model).
  * Added support for using your own [SSH deploy keys with Git and rotating them with the API](https://docs.omni.co/guides/api/rotate-ssh-deploy-keys).
  * Updated the [SSH tunnels guide](https://docs.omni.co/connect-data/ssh-tunnels#maintaining-host-keys) to include information about maintaining host keys.

  **Modeling**

  * Added a new [`required_fields`](https://docs.omni.co/modeling/measures/parameters/required-fields) parameter to measures, allowing you to specify fields that must be included in a query when a particular measure is used.
  * Added a [Level of Detail (LOD) comparison guide](https://docs.omni.co/guides/patterns/level-of-detail-build-comparison) to help you understand the differences between LOD expressions and when to use each one.

  **Users & permissions**

  Added **View SQL** as a granular permission to [custom roles](https://docs.omni.co/administration/users/custom-roles#permissions-reference).

  **Visualization**

  * Added support for referencing pivot values in Markdown visualizations using Mustache.
  * Fixed an issue where faceting was not working correctly for multi-measure (trellis) charts.
</Update>

<Update label="Week of July 13, 2026">
  **Administration**

  Added support for [UK and Australia regions](https://docs.omni.co/administration/security/cloud-regions) to Azure deployments.

  **AI**

  * Added a new **AI calculations** setting in **AI Hub > General > Features**. When enabled, AI calculations will run on Omni's hosted model instead of using Snowflake or Databricks native functions. **This feature is still in development**.
  * Updated the [Forecasting with AI](https://docs.omni.co/ai/forecasting) documentation to clarify that the Omni Agent uses an internal statistical library and does not have access to the web.
  * Added documentation for [per-user AI credit limits](https://docs.omni.co/ai/settings/usage#user-level-credit-controls).
  * Added documentation for setting up [Google Gemini Enterprise Agent Platform (formerly Vertex AI)](https://docs.omni.co/ai/settings/model-providers/google-vertex-ai) as a BYO LLM provider.

  **API**

  * Added an endpoint for [manually triggering an AI model suggestion run](https://docs.omni.co/api/ai-model-suggestions/generate-model-suggestions).
  * Added an endpoint for [retrieving the status of a specific model suggestion generation run](https://docs.omni.co/api/ai-model-suggestions/get-status-for-a-generation-run).
  * Added an endpoint for [retrieving the status of the latest model suggestion generation run](https://docs.omni.co/api/ai-model-suggestions/get-the-latest-generation-run).
  * Added an [endpoint](https://docs.omni.co/api/documents/remove-dashboard-from-document) that allows you to remove the dashboard from a document.
  * Added a `workbookModelId` field to responses from the Documents v2 APIs.
  * Added support to the API for supplying your own git SSH deploy keys.
  * Added an [API endpoint](https://docs.omni.co/api/ai-credit-controls/set-individual-users-ai-credit-limits) to update individual users' AI credit limits.
  * Added a new [API endpoint](https://docs.omni.co/api/ai-credit-controls/list-individual-users-ai-credit-limits) for retrieving individual users' AI credit limits.
  * Removed invalid `createdAt` and `updatedAt` fields from the [List Folders API response](https://docs.omni.co/api/folders/list-folders).
  * Added a [guide for migrating Looker dashboards to Omni](https://docs.omni.co/guides/migrations/looker-to-omni-skill).

  **Dashboards**

  * Added a **Mobile** setting to the dashboard properties panel. This setting controls how a specific dashboard container behaves when viewed on mobile.
  * Added a [**Control manages field order** setting](https://docs.omni.co/visualize-present/dashboards/controls#multi-field-reordering) to multi-field picker controls. When enabled, dashboard viewers can reorder fields in a chart by the order they select them.
  * Added a [**Safe Domains** setting](https://docs.omni.co/visualize-present/apps/settings#safe-domains) to Apps, enabling app editors to extend the app’s security model by specifying additional trusted hosts for loading images, scripts, stylesheets, fonts, and network connections.
  * Added support using [`data:` and `blob:` image URLs](https://docs.omni.co/visualize-present/apps/index#security) in Apps.
  * Added documentation for the [**Allow map providers** App setting](https://docs.omni.co/visualize-present/apps/settings#allow-map-providers).

  **Deliveries & Alerts**

  * Added [Mustache template](https://docs.omni.co/share/deliveries/dynamic-content) support to the **Path** field for Amazon S3 deliveries.
  * Updated the [Deliveries overview](https://docs.omni.co/share/deliveries#use-cached-results-if-available) to include information about the **Use cached results if available** setting.

  **Embedding**

  Added support for limiting AI credit usage for specific embed entity groups.

  **General UI**

  * Added support for setting a default dashboard to display on Omni users' homepages.
  * Added support to [the in-app search](https://docs.omni.co/content/search#param-hub) for restricting results to Hub/published content.

  **Integrations**

  * Added support for importing [Snowflake semantic view filters](https://docs.omni.co/connect-data/snowflake-semantic-views/sync/metadata-reference) as filter dimensions.
  * [OAuth for database connections](https://docs.omni.co/connect-data/oauth/index) is now generally available.
  * Added support for [Workload Identity Federation as an authentication method](https://docs.omni.co/connect-data/setup/bigquery-workload-identity) for BigQuery database connections.
  * Updated the [Git settings documentation](https://docs.omni.co/integrations/git/settings) to reflect the names of settings currently in the Omni UI.
  * Updated the [Git troubleshooting guide](https://docs.omni.co/integrations/git/troubleshooting#merging-a-pr-reverted-changes-from-another-branch) to explain how merging stale pull requests can overwrite changes from other branches in your shared model, including symptoms, causes, and prevention strategies.
  * Updated the [Dynamic connection environments guide](https://docs.omni.co/connect-data/dynamic-environments) to include information about how connection base roles should be configured.

  **Modeling**

  * Added [`allow_ctes`](https://docs.omni.co/modeling/models/parameters/ai-settings/allow-ctes) and [`allow_custom_fields`](https://docs.omni.co/modeling/models/parameters/ai-settings/allow-custom-fields) to the model-level [`ai_settings`](https://docs.omni.co/modeling/models/parameters/ai-settings) parameter. These settings control whether the Omni Agent can generate CTEs and custom fields. **Omni does not recommend disabling these settings - see the docs for more information.**
  * Added support for suppressing Content Validator issues by adding `!suppress(issue_slug)` comments on properties or objects.
  * Updated the [schema refresh documentation](https://docs.omni.co/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) to clarify that a connection can only have a single model when **Branch-based schema refresh** is enabled.
  * Added [documentation explaining the scope of join aliases](https://docs.omni.co/modeling/views/alias#alias-scope) created with `join_to_view_as` and `join_from_view_as`, including a troubleshooting guide for common errors when referencing these aliases outside their intended scope.

  **Visualization**

  * Added support for [pinning color values to min/mid/max values](https://docs.omni.co/visualize-present/visualizations/configuration/color#gradient-color-scale-values) in gradient color scales.
  * Updated the [Markdown Dashboard tile anchors guide](https://docs.omni.co/showcase/visualizations/dashboard-tile-anchors#linking-to-another-dashboard-with-filters-and-controls-retained) to include information about passing filters and controls through cross-dashboard Markdown links.

  **Workbook**

  * Input columns now support boolean (Yes/No) as a data type.
  * Added documentation for [Top N fields](https://docs.omni.co/analyze-explore/custom-fields/top-n) and [Top N controls](https://docs.omni.co/visualize-present/dashboards/controls#top-n-limit).
</Update>

<Update label="Week of July 6, 2026">
  **Slack for AI routines!**

  Slack is now supported as an [AI routine destination](https://docs.omni.co/ai/routines).

  **Omni Agent floating avatar access**

  The Omni Agent is now accessible by clicking the floating avatar in workbooks and dashboards. In embedded instances, the agent is still accessed using the ✨ (sparkle) icon in the sidebar.

  **Administration**

  * Added per-method sign-in settings to the **Settings > Authentication** page. This allows you to enable and disable specific authentication methods for your instance.
  * Added documentation for the SAS token access option for [Azure audit logs](https://docs.omni.co/administration/audit-logs/azure-blob-storage).

  **AI**

  * Added the **Chat in navigation** setting to **AI Hub > General > Features**, which allows you to control whether the standalone AI chat is accessible from the main navigation in Omni.
  * [Apps](/visualize-present/apps) can now dynamically filter their own queries, enabling interactive drill-downs — for example, clicking an element to filter the underlying data — with loading indicators while results refresh.
  * Added support for user default credit limits on the AI credit controls endpoints. **This feature is currently in development.**
  * Draft Apps will now display [Access Warnings](https://docs.omni.co/visualize-present/apps/index#access-warnings).
  * Added support for Google Vertex AI as a bring-your-own LLM (BYO-LLM) provider.
  * Updated the design of the AI dashboard search tile for improved usability and visual consistency.
  * Added AI credit limit control to the **User Details** page, allowing you to set and manage AI credit allocations for individual users. **This feature is currently in development.**
  * Added settings for [MCP tools](https://docs.omni.co/ai/mcp/tools) to [**AI Hub > MCP**](https://docs.omni.co/ai/settings/mcp).
  * MCP server access is now governed by the **MCP server** setting in **AI Hub > General > Features**, rather than being tied to the **Personal tokens** setting. See [MCP Authentication](https://docs.omni.co/ai/mcp/authentication) for more information.
  * Added [documentation for styling apps](https://docs.omni.co/visualize-present/apps/styling) using Omni's design system CSS variables and custom theme styles.

  **API**

  * Removed an invalid `GET /connection-environments endpoint` from the API documentation.
  * Added the [Rename document identifier endpoint](https://docs.omni.co/api/documents-v2/rename-document-identifier), which allows you to programmatically update document identifiers.
  * Updated the [Get document state (v2) endpoint](https://docs.omni.co/api/documents-v2/get-document-state) to correctly retrieve the specified document's published state. Previously, the API would return the document's draft state.
  * The [Get document state](https://docs.omni.co/api/documents-v2/get-document-state) and [Get draft state](https://docs.omni.co/api/documents-v2/get-draft-state) endpoints now include the document's `modelId` in responses.

  **Dashboards**

  * The Dashboard Agent can now create dashboard controls.
  * Added the ability to [unlink and detach metadata](https://docs.omni.co/visualize-present/dashboards/charts#detaching-and-hiding-query-text-items) from query tiles in dashboards.

  **General UI**

  Added a **Word wrap** toggle to the **View** menu in the IDE.

  **Integrations**

  * Added support for [default warehouse routing](https://docs.omni.co/connect-data/oauth/snowflake/index#warehouse-configuration) to the Snowflake OAuth integration.
  * Added additional scenarios and troubleshooting instructions to the [Git integration troubleshooting guide](https://docs.omni.co/integrations/git/troubleshooting).

  **Modeling**

  * Added support for agent-specific AI context via the `omni_agent` Mustache namespace, allowing you to customize AI behavior on a per-agent basis. See [Optimize models for Omni AI](https://docs.omni.co/modeling/develop/ai-optimization#model-specific-context) for more information.
  * Added support for `@{constant_name}` references in `ai_context` fields for models, topics, views, and sample queries, allowing you to dynamically reference constants in your semantic model's AI context configuration. See [Optimize models for Omni AI](https://docs.omni.co/modeling/develop/ai-optimization#use-constants-for-reusable-ai-context) for more information.
  * [Composite topics](https://docs.omni.co/modeling/composite-topics/index) are now available in all Omni instances. **Note**: Composite topics are still in beta and [we want your feedback](https://docs.omni.co/modeling/composite-topics/index#roadmap)!
  * Added Finnish (`fi_FI`) as a [`default_numeric_locale`](https://docs.omni.co/modeling/models/default-numeric-locale) option.
  * [Sample queries](https://docs.omni.co/modeling/composite-topics/parameters/sample-queries) can now be saved to composite topics.
  * Added a new [`always_join_all_topics`](https://docs.omni.co/modeling/composite-topics/parameters/always-join-all-topics) parameter to composite topics. This allows you to control whether all topics are included in the `FULL OUTER JOIN` or only those with selected fields.
  * Fixed an issue where composite topics were not respecting the `fields` parameter, allowing access to fields that should have been restricted.
  * Added Portuguese (`pt_PT`) as a [`default_numeric_locale`](https://docs.omni.co/modeling/models/default-numeric-locale) option.
  * Added documentation for the [`fields`](https://docs.omni.co/modeling/composite-topics/parameters/fields) composite topic parameter.
</Update>

<Update label="Week of June 29, 2026">
  **All about Apps!**

  * AccessBoost now applies to queries in [Apps](/visualize-present/apps).
  * System and custom application theme settings are now available as CSS variables for use in [Apps](/visualize-present/apps).
  * Diff blocks will now display code changes made when [editing an App](https://docs.omni.co/visualize-present/apps#edit-an-app).

  **AI**

  Added support for implementing AI model tier-specific context with the `omni_llm` Mustache reference. See the [AI context management guide](https://docs.omni.co/modeling/develop/ai-optimization#model-specific-context) for more information and examples.

  **API**

  * Updated the [Stream AI job results API](https://docs.omni.co/api/ai/stream-ai-job-results) to include all query results in responses.
  * Dashboards can now be upgraded to the new layout experience using the [API](https://docs.omni.co/api/documents/upgrade-dashboard-layout).
  * API keys can now be [rotated](https://docs.omni.co/api/authentication#rotate).

  **Dashboards**

  Suggestions for filters will now display in the **Filter properties** panel when adding filters to dashboards.

  **dbt**

  HTTPS deploy-token authentication is now supported for connecting to dbt repositories.

  **Deliveries & Alerts**

  Email deliveries can now be restricted to a [list of allowed email domains](https://docs.omni.co/share/deliveries/email/domain-allowlist).

  **Embedding**

  * Added a warning to the [`mode` embed URL parameter documentation](https://docs.omni.co/embed/setup/url-parameters/mode#param-mode) cautioning against generating `SINGLE_CONTENT` and `APPLICATION` mode embed sessions for the same user simultaneously, as this can result in inconsistent behavior.
  * Added documentation for the automatic merge behavior that occurs when an [email-only user is converted to an embed user](https://docs.omni.co/administration/users/email-only#merging-email-only-users-with-embed-users).

  **Integrations**

  [Amazon Athena connections](https://docs.omni.co/connect-data/setup/athena) now support table/CSV uploads.

  **Modeling**

  * [Composite topics](https://docs.omni.co/modeling/composite-topics) now support selective field inclusion and exclusion, allowing you to control which fields from referenced topics appear in the composite topic.
  * Added a guide for [creating dynamic pivot query views](https://docs.omni.co/guides/patterns/dynamic-pivot-query-view).

  **Workbook**

  * Added documentation that clarifies how Omni handles URLs when [working with unsaved analyses](https://docs.omni.co/analyze-explore/workbook-basics#unsaved-analyses-and-url-behavior).
  * You can now add dashboard-level filters to [workbook queries with a single click](https://docs.omni.co/analyze-explore/queries/filters#adding-dashboard-filters-to-workbook-queries).
</Update>

<Update label="Week of June 22, 2026">
  **AI annotation support**

  AI-powered visualization annotations are now generally available.

  **Notion integration for AI context**

  The [external AI context integration for Notion](https://docs.omni.co/integrations/ai/notion) is now available.

  **Domain allowlist for email deliveries**

  Added support for [restricting email deliveries](https://docs.omni.co/share/deliveries/email/domain-allowlist) to specific domains.

  **AI**

  [Apps](https://docs.omni.co/visualize-present/apps) are now enabled by default for Omni organizations created after June 25, 2026.

  **API**

  * Added support for workbook-only documents to the [Create documents (v2) API](https://docs.omni.co/api/documents-v2/create-document).
  * Added a [new API endpoint](https://docs.omni.co/api/who-am-i/get-current-identity-and-permissions) that returns information about the currently authenticated user.
  * Added a [new API](https://docs.omni.co/api/ai-model-suggestions/dismiss-a-suggestion) that allows you to dismiss AI model suggestions.
  * Added the ability to manually trigger an AI routine in Omni and using the [API](https://docs.omni.co/api/ai-routines/run-ai-routine-now).
  * Added a [new API](https://docs.omni.co/api/ai-model-suggestions/list-ai-generated-suggestions) that allows you to retrieve a list of AI suggestions for a model.
  * Added two new APIs that allow you to [retrieve](https://docs.omni.co/api/ai-credit-controls/get-ai-credit-controls) and [update](https://docs.omni.co/api/ai-credit-controls/update-ai-credit-controls) your organization's AI credit control settings.
  * Added a [new API](https://docs.omni.co/api/ai-model-suggestions/enable-model-ai-suggestions-schedule) that allows you to enable a daily schedule for AI model suggestions.
  * Added a [new API](https://docs.omni.co/api/ai-model-suggestions/restore-a-dismissed-suggestion) that allows you to restore a previously dismissed AI model suggestion.
  * Added a [new API](https://docs.omni.co/api/ai-model-suggestions/disable-model-ai-suggestions-schedule) that allows you to disable the schedule for AI model suggestions.
  * Added a [new API](https://docs.omni.co/api/ai-model-suggestions/delete-a-suggestion) that allows you to permanently delete an AI model suggestion.
  * Added new endpoints that allow you to [create](https://docs.omni.co/api/ai-routines/create-an-ai-routine) and [update](https://docs.omni.co/api/ai-routines/update-an-ai-routine) AI Routines.
  * Added support for overriding a connection environment to the [Run query API](https://docs.omni.co/api/queries/run-query#body-connection-environment-id).

  **Dashboards**

  * Added a [placeholder layout item](https://docs.omni.co/visualize-present/dashboards/placeholders) to help you wire-frame dashboard layouts before adding actual content.
  * Added the ability to [lock dashboard containers](https://docs.omni.co/visualize-present/dashboards/containers-items#lock-container).

  **Embedding**

  Added support for [per-user OAuth authentication for embed users](https://docs.omni.co/embed/customization/vanity-domains#per-user-oauth-support) through vanity domain redirects.

  **Integrations**

  Added a new guide for setting up [OAuth authentication with Databricks](https://docs.omni.co/connect-data/oauth/databricks).

  **Modeling**

  * Added support for `timeframes` and `timeframe_metadata` in [shared dimensions](https://docs.omni.co/modeling/composite-topics/parameters/shared-dimensions) within composite topics.
  * Dynamic shared extensions can now be scoped to the active connection environment.

  **Visualization**

  Added the ability to set [column widths in tables](https://docs.omni.co/visualize-present/visualizations/types/table#field-options) by specifying a pixel value.

  **Other**

  Refactored the AI credits page to provide better account-level visibility and management of your AI usage.
</Update>

<Update label="Week of June 15, 2026">
  **Administration**

  Added an **Apps** setting to **Settings > General**, allowing Organization Admins to control whether users can use apps.

  **AI**

  * You can now upload `.lkml`, `.xml`, and `.html` files to AI chats.
  * Added support for connecting to Notion databases through the Model Context Protocol (MCP) client integration. Reach out to support for more information.
  * Added bulk actions for ignoring, restoring, and deleting suggestions from the AI suggestions page.

  **API**

  * Added a new optional **pretty** query parameter to the v2 document `GET` endpoints to request formatted JSON responses with 2-space indentation.
  * Corrected the deprecation date for the v1 Update document endpoints to July 31, 2026 and updated the deprecation headers in 200 responses.
  * Updated the OpenAPI spec to correctly indicate that the `summary` property in v2 document endpoints is optional and automatically filled when not provided.

  **Dashboards**

  Added **Spacer** and **Divider** inline layout elements to the dashboard builder.

  **Embedding**

  * Added a [`documentBreadcrumb` property](https://docs.omni.co/embed/setup/url-parameters/uiSettings#param-document-breadcrumb) to the `uiSettings` embed parameter, which allows you to control the display of folder paths in embedded content.
  * Added a [`dashboardChartContextMenu` property](https://docs.omni.co/embed/setup/url-parameters/uiSettings#param-document-chart-context-menu) to the `uiSettings` embed parameter, which allows you to control the display of context menus on embedded dashboard tiles.

  **Workbook**

  Added a search field to the **Switch topic** picker.

  **Other**

  Added a [timezone override picker](https://docs.omni.co/visualize-present/dashboards/timezone-override) for downloads and schedules.
</Update>

<Update label="Week of June 8, 2026">
  **AI**

  AI-powered suggestions are now generally available.

  **API**

  * Added a new [Publish draft document](https://docs.omni.co/api/documents-v2/publish-draft) endpoint.
  * Added a new optional `deleteViewsAndTopicsMissingFromSource` parameter to the [Migrate model API](https://docs.omni.co/api/models/migrate-a-model) that controls how views and topics are handled during migration.
  * Added `createdAt` and `updatedAt` fields to responses from Connection APIs.
  * Added support for passing `userId` as a query parameter when using the Run query API.

  **Dashboards**

  * The **Subtitle** and **Description** fields now remain visible in the properties panel for query-linked dashboard containers.
  * AI buttons on dashboards now open the chat interface in a split-view panel.

  **Integrations**

  Added validation in dbt settings to reject reserved git branch names.

  **Modeling**

  Added support for sketch-based approximate aggregates in aggregate awareness routing.

  **Visualization**

  * Added support for storing an initial map viewport in the map visualization configuration.
  * Added support for setting a fixed minimum and maximum range for display bars in tables.
</Update>

<Update label="Week of June 1, 2026">
  **Administration**

  Added documentation for [Azure Blob Storage](https://docs.omni.co/administration/audit-logs/azure-blob-storage) as an audit log destination.

  **AI**

  Custom dashboard identifiers can now be used when using the AI chat interface to search for dashboards.

  **Calculations**

  Added the [**Calculation pushdown** feature](https://docs.omni.co/analyze-explore/calculations/index#evaluating-calculations-before-or-after-row-limits), which allows calculations with range references to evaluate against your full dataset before row limits are applied. Previously, calculations only evaluated on the rows returned after the limit.

  **Dashboards**

  * Added documentation for using [query metadata items](https://docs.omni.co/visualize-present/dashboards/charts#inserting-query-metadata-items), which allow you to display query info such as name and subtitle, in dashboards.
  * Added info about the [**Add inside selection** option](https://docs.omni.co/visualize-present/dashboards/containers-items#from-the-catalog) in dashboard catalogs to the docs.

  **Embedding**

  * Added support for specifying a [timezone override](https://docs.omni.co/embed/setup/url-parameters/timezone) in embed login URLs.
  * Updated the [embed best practices](https://docs.omni.co/embed/best-practices#scheduled-deliveries-and-embed-user-entities) to include guidance for multi-entity users, dynamic shared extensions, and setting up deliveries.

  **Integrations**

  * The [Slack integration](https://docs.omni.co/integrations/ai/slack) no longer requires organization-level configuration before users can utilize it.
  * Improved visibility of schema, table, and view permission requirements for [Snowflake semantic views](https://docs.omni.co/connect-data/snowflake-semantic-views) in the documentation.

  **Modeling**

  * Added a new [`n` parameter](https://docs.omni.co/modeling/dimensions/parameters/dynamic-top-n#query-time-parameterization) to the `dynamic_top_n` modeling parameter, which allows you to dynamically control the number of results returned in queries.
  * Added a [`disabled_tools` property](https://docs.omni.co/modeling/models/parameters/ai-settings/disabled-tools) to the model AI settings that allows you to specify which AI tools should be unavailable to users in your semantic model.

  **Visualization**

  Added five new [Markdown column examples](https://docs.omni.co/showcase) to the visualization showcase: **User profile**, **Pills**, **Star rating**, **Location with national flag**, and **Status indicator**.

  **Workbook**

  * Added support for using fields included in access filters as mapping keys in [input columns](https://docs.omni.co/analyze-explore/input-columns).
  * Added the ability to [promote Markdown](https://docs.omni.co/visualize-present/visualizations/types/table-field-display#customizing-markdown-templates-in-the-workbook) to your workbook directly from the table configuration settings.

  **Other**

  Added support for personal content as a membership-level system attribute.
</Update>

<Update label="Week of May 25, 2026">
  **AI Hub is now available!**

  Check out the [AI Hub](https://docs.omni.co/administration/ai-hub) documentation to learn more.

  **Markdown columns are now available!**

  See the [dimension](https://docs.omni.co/modeling/dimensions/parameters/markdown) and [measure](https://docs.omni.co/modeling/measures/parameters/markdown) documentation for more information.

  **AI**

  * Added [optional scope configuration display](https://docs.omni.co/integrations/omni-slack-agent#optional-scopes-2) to the Slack integration settings in the **Integrations** view sidebar.
  * Added a guide for setting up Omni MCP Server with [Microsoft Copilot (Copilot Studio)](https://docs.omni.co/ai/mcp/microsoft-copilot).

  **API**

  * Added a new [Delete connection](https://docs.omni.co/api/connections/delete-connection) API.
  * Fixed an issue where [trigger requests](https://docs.omni.co/api/schedules/trigger-schedule) were incorrectly accepted for paused schedules. The API now properly rejects these requests.
  * Added a new [List document favoriters](https://docs.omni.co/api/document-favorites/list-document-favoriters) endpoint.
  * Added the `isDeferralEnabled` property to the [dbt environment APIs](https://docs.omni.co/api/dbt/create-dbt-environment).
  * Added a [guide](https://docs.omni.co/guides/api/bulk-update-model-yaml) about using the API to perform bulk updates to model files.
  * Updated the [Create model endpoint reference](https://docs.omni.co/api/models/create-model) to include all parameters from the public OpenAPI spec.

  **Dashboards**

  * Added support for dynamic filter dashboard controls, allowing dashboard viewers to add their own filters to published dashboards without the filter being predefined by the dashboard creator.
  * Added a [preview mode](https://docs.omni.co/visualize-present/dashboards/preview-mode) for dashboards. **Note**: This feature is not available for classic dashboards.

  **Embedding**

  Updated the [embedding documentation](https://docs.omni.co/embed/best-practices#send-connection-roles-on-every-embed-request) to clarify that you should send `connectionRoles` on every embed request.

  **Integrations**

  Fixed an issue where Snowflake external OAuth scope was incorrectly converted to lowercase.

  **Modeling**

  * Added support for [viewing the history for individual model files](https://docs.omni.co/modeling/develop/history#viewing-file-history) to the IDE.
  * Added support for gating [AI skills](https://docs.omni.co/ai/skills) with required access grants.
  * Added documentation for the [`dynamic_shared_extensions`](https://docs.omni.co/modeling/models/dynamic-shared-extensions) modeling parameter.

  **Visualization**

  Added text formatting controls to the [**Single Record** visualization](https://docs.omni.co/visualize-present/visualizations/types/single-record#text-formatting).

  **Workbook**

  Added support for `is like` filters in the workbook UI. Use the [`sql_like`](https://docs.omni.co/modeling/filters/operators/sql-like) filter operator to achieve the same result with YAML.
</Update>

<Update label="Week of May 17, 2026">
  **Specify compute resources for jobs**

  Added a new [`compute_routing`](https://docs.omni.co/modeling/models/compute-routing) model property that allows you to specify different compute resources for different types of jobs.

  **Drilling in calculated fields**

  Added support for drilling through from calculated fields that contain plain references to dimensions or measures.

  **OAuth for the Omni CLI**

  Added OAuth authentication support for the CLI. You can now use `omni config login <profile>` to authenticate with your Omni workspace. See the [CLI authentication documentation](https://docs.omni.co/developers/cli/authentication#oauth-authentication) for details.

  **Administration**

  * Updated documentation to clarify the differences between the dashboard-level [**View As**](https://docs.omni.co/visualize-present/dashboards/view-as) and Omni-level **Impersonate user** features, including when to use each.
  * Updated [documentation](https://docs.omni.co/administration/chart-palettes/omni) to remove "Omni" branding from built-in chart palette names for white-labeling purposes. Palette IDs remain unchanged for backward compatibility.

  **AI**

  * Updated documentation for the Omni Slack Agent to include a new [Slack permissions section](https://docs.omni.co/integrations/omni-slack-agent#optional-scopes) that lists required and optional scopes with their impacts on deliveries and the agent.
  * Fixed the [Features and shared data table in the AI security documentation](https://docs.omni.co/ai/security#features-and-shared-data) to correctly indicate that **Chat** and **Blank workbook topic picking** share current query metadata. Previously, these features were incorrectly marked as not sharing this data.

  **API**

  * Added a new [`GET /api/v1/documents/{identifier}/drafts`](https://docs.omni.co/api/documents/list-document-drafts) endpoint to retrieve draft versions of a document.
  * Renamed the [AI agent actions API endpoint](https://docs.omni.co/api/models/get-model-ai-agent-actions) from `ai_agent_actions` to `ai-agent-actions`. The full endpoint is now `/api/v1/models/{modelId}/ai-agent-actions`.
  * Updated the API documentation to include the `alwaysScopeViewNames` and `inferRelationshipsFromColumnNames` connection parameters in the [Create connection](https://docs.omni.co/api-reference/connections/create-connection) request body.
  * Added documentation for the [Update users](https://docs.omni.co/api/users/update-user) and [Update user groups](https://docs.omni.co/api/user-groups/update-user-group) endpoints. Also added the `jobId` field to the [Refresh schema endpoint's 200 response](https://docs.omni.co/api/models/refresh-schema#response-job-id).

  **Dashboards**

  * Container elements with attached queries no longer display the **Flow** and **Style** tabs in the builder, as these settings are not applicable to query-attached containers.
  * Added a selection-scope banner to the **Add** menu and **Catalog** popover that appears when a non-page-root container is selected, letting you know that new items will be added inside the selected container. The banner includes a **Clear selection** button to deselect the container and place new items at the page root instead.
  * Added a duplicate action for containers and content items in advanced dashboard layouts.
  * Added a **Dynamic size** option for KPI numbers in advanced layouts, allowing you to automatically scale text based on available space.
  * Added documentation for the [timezone picker](https://docs.omni.co/visualize-present/dashboards/timezone-override) that lets viewers override the query timezone for a single dashboard or workbook page.

  **General UI**

  Added a [searchable model picker](https://docs.omni.co/analyze-explore/workbook-basics#creating-a-new-workbook) when creating a new workbook from the **+ New** button.

  **Integrations**

  * [BigQuery connections](https://docs.omni.co/connect-data/setup/bigquery) will now perform dataset-level scans when a connection's **Included datasets** setting includes wildcards. This fixes an issue where the connector would scan project metadata to discover schemas, which would cause permission errors when users didn't have the BigQuery Project Metadata permissions.
  * Added [inline error detection in the dbt IDE](https://docs.omni.co/integrations/dbt/semantic-layer#troubleshooting) that displays semantic-layer validation problems directly in the code editor.
  * Added a setup guide for connecting to [Starburst Galaxy](https://docs.omni.co/connect-data/setup/starburst-galaxy), a managed Trino database service.
  * Updated the S3 resource ARN for [Amazon Athena](https://docs.omni.co/connect-data/setup/athena) query results to reference only the specific bucket instead of all buckets on the account.
  * Added documentation about using `sql_preamble` to work around Starburst Galaxy's `query_max_stage_count` limit to the [database troubleshooting guide](https://docs.omni.co/connect-data/troubleshooting).
  * Added support for [Snowflake external OAuth with Microsoft Entra ID](https://docs.omni.co/connect-data/oauth/snowflake/external-entra).

  **Modeling**

  * Added a [`target` option](https://docs.omni.co/modeling/dimensions/parameters/links#param-target) to dimension and measure `links` in your semantic model, allowing you to specify how linked content should open.
  * Added support for **Fully-resolved** as a first-class IDE mode.
  * Added support for [aggregate awareness across joins](https://docs.omni.co/analyze-explore/performance/aggregate-awareness), allowing you to leverage pre-aggregated data more effectively when querying across related tables.
</Update>

<Update label="Week of May 10, 2026">
  **Support hard/soft refresh in scheduled refreshes & through the API**

  Added support for hard and soft refresh options in [scheduled refreshes](https://docs.omni.co/modeling/develop/schema-refreshes#on-a-schedule) and through the [API](https://docs.omni.co/api/schema-refresh-schedules/create-schema-refresh-schedule).

  **Configurable session length for non-embed sessions**

  Added a new organization-level [Session length](https://docs.omni.co/administration/settings#general) setting. This allows you to define how long user sessions remain active before requiring re-authentication.

  **Administration**

  Added a [**Default connection** setting](https://docs.omni.co/ai/settings/features#default-connection) to **AI Hub > General > Features**, which allows you to set a default connection for the Omni Agent.

  **AI**

  * Updated the [Omni Agent guide](https://docs.omni.co/ai/chat#creating-dashboards) to include information about agentic dashboard creation.
  * Added information about AI summary caching to the [AI credit tracking FAQ](https://docs.omni.co/ai/settings/usage).

  **API**

  * Added a new [`GET /api/v1/ai/branding` endpoint](https://docs.omni.co/api/ai/get-ai-agent-branding) that allows you to retrieve branding configuration for AI features.
  * Added a new [`GET /api/v1/ai/conversations/{conversationId}`](https://docs.omni.co/api/ai/get-conversation) endpoint that allows you to retrieve details about a specific AI conversation.
  * Added a new `GET /api/v1/models/{modelId}/ai_agent_actions` that allows you to retrieve AI agent actions configured for a specific model.
  * Added a new [`GET /api/v1/ai/conversations` endpoint](https://docs.omni.co/api/ai/list-ai-conversations) that allows you to retrieve a user's AI conversations.
  * Added a new [`GET /api/v1/connections/{id}` endpoint](https://docs.omni.co/api/connections/get-connection) that allows you to retrieve details about a specific database connection.
  * Updated the [Update user endpoint](https://docs.omni.co/api/users/update-user) documentation to reflect support for updating an existing user's email address. Previously, the email field was read-only and had to match the user's existing email address.

  **Dashboards**

  * Added a per-page user timezone override widget that allows you to change the timezone for a specific dashboard or workbook page without affecting your global timezone setting.
  * Added support for tile-align presets when configuring content items in the dashboard builder.
  * Improved zoom behavior in the advanced dashboard layout to provide smoother panning and zooming interactions when working with larger dashboards.
  * Added a [context menu to the page switcher](https://docs.omni.co/visualize-present/dashboards/page-navigation#navigating-in-edit-mode) while editing dashboards.

  **General UI**

  * Fixed an issue where folder-specific role descriptions were not displaying correctly in the **Roles** management interface when sharing folders.
  * Removed "Omni" branding from built-in color palette names.

  **Integrations**

  * Fixed an issue where a Snowflake external OAuth scope for Microsoft Entra ID was not properly qualified, which could cause authentication failures when using Entra OAuth with Snowflake connections.
  * Added [documentation](https://docs.omni.co/integrations/dbt/virtual-schemas#common-questions) explaining how `omni_dbt` virtual schema names are derived from dbt model custom schema configurations.
  * Updated the [Snowflake Privatelink documentation](https://docs.omni.co/connect-data/snowflake-privatelink) to clarify differences between AWS and Azure implementations.

  **Modeling**

  Added support for patch-based merging of [AI context](https://docs.omni.co/modeling/models/ai-context) configurations in non-base model layers.

  **Workbook**

  Added an **Edit view** drawer that allows you to modify [database](https://docs.omni.co/modeling/views/edit) and [query views](https://docs.omni.co/modeling/query-views/edit) in a workbook.
</Update>

<Update label="Week of May 3, 2026">
  **AI**

  * Added support for enabling the AI to query outside topics when using the [MCP Server](https://docs.omni.co/ai/mcp). This is enabled by adding `X-MCP-Query-All-Views: true` to the Omni MCP server's configuration.
  * Added the ability to [provide feedback on Slack Agent responses](https://docs.omni.co/integrations/omni-slack-agent#providing-response-feedback) directly from Slack, allowing you to rate whether the agent's answer was helpful.
  * Added a new Modeling Agent skill that allows you to generate semantic models based on your [Snowflake or Postgres query history](https://docs.omni.co/ai/model-assistant#suggest-model-from-query-history).

  **API**

  Added support for enabling and disabling individual Personal Access Tokens (PATs) and MCP PATs in [Omni](https://docs.omni.co/api/authentication#enabling-and-disabling-pats) and through the [API](https://docs.omni.co/api/api-tokens/enable-or-disable-api-token). Organization Admin permissions are required.

  **Content**

  Added [branch content links](https://docs.omni.co/content/develop/branch-mode#publishing-and-merging-branches) to GitHub and GitLab pull request descriptions for branches that contain draft content, making it easier to preview changes before merging.

  **Dashboards**

  <Note>
    The following updates are applicable only to advanced layout dashboards.
  </Note>

  * Added support for [multiple selections](https://docs.omni.co/visualize-present/dashboards/advanced-filters#working-with-string-filters) to string filter button groups for advanced dashboard layouts.
  * Added a new dashboard setting that allows you to [fix the filter and control bar](https://docs.omni.co/visualize-present/dashboards/settings#fixed-control-bar) to the top of advanced layout dashboards.
  * Added an **Edit** context menu item to dashboard elements when the properties panel is closed, allowing you to quickly access editing options without opening the panel.
  * Added the ability to select which pages to include when [downloading](https://docs.omni.co/visualize-present/dashboards/download) or [scheduling](https://docs.omni.co/share/deliveries) dashboards. Applicable only to advanced layout dashboards.
  * Added the ability to insert query metadata (name, subtitle, description) into query items on advanced layout dashboards.
  * Added documentation for using [dynamic page name references](https://docs.omni.co/visualize-present/dashboards/page-navigation#dynamic-labels) (`{{page.<KEY>.name}}`) in advanced layout page navigation.

    Also split the documentation for advanced layouts into smaller, more focused pages covering [containers and items](https://docs.omni.co/visualize-present/dashboards/containers-items), [pages](https://docs.omni.co/visualize-present/dashboards/pages), [page navigation](https://docs.omni.co/visualize-present/dashboards/page-navigation), and [filter display options](https://docs.omni.co/visualize-present/dashboards/advanced-filters).

  **Deliveries & Alerts**

  Added an [**Alert condition types** section](https://docs.omni.co/share/deliveries#alert-condition-types) to the deliveries and alerts documentation.

  **Integrations**

  * Added an **Enable deferral** option to the dbt environment settings. When enabled, unbuilt models in the dbt dev environment will fall back to the production build.
  * Added visual highlighting to distinguish between development and production virtualized views when using dbt deferral environments. These views will have an orange icon in the IDE.
  * Added a step-by-step guide for [previewing dbt changes in Omni](https://docs.omni.co/guides/modeling/preview-dbt-changes).

  **Modeling**

  * Fixed an issue where topics with an ignored [`base_view`](https://docs.omni.co/modeling/topics/parameters/base-view) were being included in model validation and shown in the topic picker. Now, topics with an ignored `base_view` will be correctly excluded from validation and the topic picker.
  * Added examples to the [`always_where_sql`](https://docs.omni.co/modeling/topics/parameters/always-where-sql) topic modeling parameter.

  **Workbook**

  Added documentation for the beta [input columns](https://docs.omni.co/analyze-explore/input-columns) feature.
</Update>

<Update label="April 26, 2026">
  **Administration**

  * Added a confirmation dialog when you disable the **Custom email sender** setting in **Settings > Deliveries > Email**. Previously, toggling off immediately disabled the custom sender configuration, which could happen accidentally.
  * Fixed an issue where the `source` field in `QUERY_CONTEXT` audit log events was being corrupted by FireLens metadata injection. The `source` field is retained for backwards compatibility, but you should migrate your audit log filters to use the new [`query_source` field](https://docs.omni.co/administration/audit-logs/event-types).
  * Added Portuguese (Portugal) as a [supported localization option](https://docs.omni.co/administration/localization).
  * Added Norwegian Bokmål and Swedish as [supported localization options](https://docs.omni.co/administration/localization).

  **AI**

  * Updated the [**Start a new chat** indicator](https://docs.omni.co/ai/chat#managing-long-conversations) to trigger at 75% of the session's [token limit](https://docs.omni.co/modeling/models/parameters/ai-settings/conversation-prune-length) instead of 50%.
  * Added an indicator to the [**New chat** button](https://docs.omni.co/ai/chat#managing-long-conversations) that appears when your conversation is consuming a significant portion of the model's context window.
  * Updated the [Workbook inspector guide](https://docs.omni.co/analyze-explore/workbook-inspector#ai-messages) to include information about the **AI messages** section, which displays information about active AI workbook sessions.

  **API**

  * Added a new [`POST /api/v1/models/{modelId}/git/commit` API endpoint](https://docs.omni.co/api/model-git-configuration/create-or-update-a-pull-request-for-a-model-branch) that allows you to push a branch's model contents to git and create or update a pull request programmatically.
  * Added a new [`PUT /api/v1/api-keys/{id}` endpoint](https://docs.omni.co/api/api-tokens/enable-or-disable-organization-api-token) to enable or disable organization-level API tokens.
  * Added a [`DELETE /api/v1/api-keys/{id}` endpoint](https://docs.omni.co/api/api-tokens/delete-api-token) that allows you to revoke API tokens.
  * Added a new [`GET /api/v1/api-keys/{id}` endpoint](https://docs.omni.co/api/api-tokens/list-api-tokens) that allows you to retrieve details about a single API token.
  * Fixed the OpenAPI schema for the [`POST /api/v1/connections` endpoint](https://docs.omni.co/api/connections/create-connection) to include 13 missing fields that were accepted by the API but not documented, including `inferRelationshipsFromForeignKeys`, `authenticationType`, `awsRoleArn`, and others.
  * Fixed the [`GET /api/v1/models/{modelId}/dbt-exposures` endpoint](https://docs.omni.co/api/dbt/get-dbt-exposures) to accept the `cursor` query parameter for pagination.
  * Added a `fullyResolved` parameter to the [Get model YAML](https://docs.omni.co/api/models/get-model-yaml) and [Update model YAML](https://docs.omni.co/api/models/create-or-update-yaml-files) endpoints.

  **Content**

  Added support for restoring archived documents when following a [direct link](https://docs.omni.co/content/archive-restore#restore-from-direct-link).

  **Dashboards**

  * Added drag-to-resize functionality for items within column stack layouts on [advanced layout dashboards.](https://docs.omni.co/visualize-present/dashboards/advanced-layout)
  * Added support for using `{{page.KEY.name}}` tokens in inline page switcher option labels in advanced layouts for dashboards. These tokens expand to the page's current name at render time and automatically update when the page is renamed, allowing you to combine custom text with dynamic page references.
  * Added a [guide on dashboard best practices](https://docs.omni.co/guides/dashboards/dashboarding-best-practices) to help you design and organize dashboards effectively.

  **Embedding**

  * Fixed an issue where Markdown links in dashboards weren't respecting the [`NO-EMBED-LINK-REWRITE` parameter](https://docs.omni.co/embed/customization/link-content#opt-out-of-link-rewriting). Links tagged with this parameter will now pass through verbatim instead of being rewritten through `/embed/link`.
  * Fixed an issue where [voice mode wasn't available for the Omni Agent](https://docs.omni.co/embed/limitations#omni-agent-voice-mode) in embedded Omni instances. You can now include `allow=microphone` in iframe permissions to enable voice mode in embed scenarios.

  **Integrations**

  * Added an [**Always Scope View Names** setting](https://docs.omni.co/connect-data/view-name-generation) to connections that forces generated view names to include schema and catalog prefixes even for tables in the default schema or catalog.
  * Added documentation about how Omni uses [dbt deferrals and constraints](https://docs.omni.co/integrations/dbt/deferrals-constraints) for model metadata and testing.
  * Added documentation for [dbt Virtual Schemas](https://docs.omni.co/integrations/dbt/virtual-schemas), which allow you to decouple your modeling logic from physical database locations and use the `omni_dbt` prefix for dynamic environment switching.
  * Added information about required database user permissions to the [Databricks connection setup guide](https://docs.omni.co/connect-data/setup/databricks).
  * Added a dedicated [schema refresh guide](https://docs.omni.co/integrations/dbt/schema-refresh) for the dbt integration.
  * Added documentation about the [dbt health check](https://docs.omni.co/integrations/dbt/health-check), which is useful for debugging dbt model issues in Omni.
  * Added a dedicated guide about [pulling dbt metadata](https://docs.omni.co/integrations/dbt/metadata) into Omni.

  **Modeling**

  * You can now selectively ignore specific global filters in a `level_of_detail` by using the `cancel_query_filter: true` flag within the `filters` map. This works on both [dimension](https://docs.omni.co/modeling/dimensions/parameters/level-of-detail) and measure `level_of_detail` definitions.
  * Added explicit by-name mapping for [`materialized_query`](https://docs.omni.co/modeling/views/parameters/materialized-query) fields.
  * Users with Modeler permissions can now refresh schemas on single-model connections.
  * Omni-generated [query view names](https://docs.omni.co/analyze-explore/saved-views) now have "smarter" default names, along with adding a `_1`, `_2`, etc. suffix when a collision is detected. This fixes an issue where importing tabs across workbooks could silently cause data corruption when query view names collided.
  * Added instructions for [deleting topics](https://docs.omni.co/modeling/topics/index#deleting-topics) in Omni's model IDE.
  * Added a guide that explains how to [preview dbt changes in Omni](https://docs.omni.co/guides/modeling/preview-dbt-changes) before merging to production.

  **Workbook**

  * Added a [format quick-pick menu](https://docs.omni.co/analyze-explore/point-click-queries#formatting-number-and-date-columns) to the results table format bar that replaces the previous **Number** button.
  * Added a [keyboard shortcut](https://docs.omni.co/getting-started/keyboard-shortcuts) (`⇧ + ⌥ + ⌘ + F` on Mac, `⇧ + ⌥ + ⌃ + F` on Windows/Linux) to collapse or expand all items in the workbook's field browser.
  * Added a context menu to the topic header in the workbook field browser. You can now right-click the topic switch button or the vertical-dots icon to access options for editing the topic or jumping to the topic definition in the IDE.
</Update>

<Update label="April 19, 2026">
  **Administration**

  * Added a new [**Duplicate** content permission](https://docs.omni.co/administration/content-permissions#default-document-abilities) that controls duplication document and workbook tab duplication across your organization. Reach out to Omni support to have this feature enabled.
  * Added Vietnamese (vi-VN) as a [supported locale](https://docs.omni.co/administration/localization) in Omni.
  * Added Italian (it-IT) as a [supported locale](https://docs.omni.co/administration/localization) in Omni.
  * Updated the [Best practices](https://docs.omni.co/getting-started/best-practices) guide to reflect current guidance on modeling in Omni, managing content, and more.

  **AI**

  * Updated the default AI model tier for the model building agent from Sonnet to Opus, so the modeling subagent and related tools use a more capable model by default. Organization-level overrides in **AI settings** take precedence over this default.
  * [External AI context integrations](https://docs.omni.co/integrations/ai/index) are now available.
  * Added a [`conversation_prune_length` parameter](https://docs.omni.co/modeling/models/parameters/ai-settings/conversation-prune-length) to model-level `ai_settings` that lets you tune how aggressively Claude prunes conversation context. See the [Tuning Omni AI for cost and quality guide](https://docs.omni.co/guides/ai/tuning-cost-quality) for additional information about this new parameter.
  * AI chat on the homepage is now available to all organizations.
  * Added a guide for [tuning AI cost and quality settings](https://docs.omni.co/guides/ai/tuning-cost-quality), which provides three starting profiles—cost-optimized, balanced, and max-quality—along with guidance on customizing them for your use case.

  **API**

  * Added a new [`PATCH /api/v1/models/{modelId}` endpoint](https://docs.omni.co/api/models/rename-model) that allows you to programmatically rename models.
  * Added `includeSchemas` parameter to the [`GET /api/v1/models/:modelId/yaml` endpoint](https://docs.omni.co/api/models/get-model-yaml) to retrieve only a specified schema's views, reducing payload size.
  * Added a new [`GET /api/v1/models/:modelId/schemas`](https://docs.omni.co/api/models/list-model-schemas) endpoint that returns a list of all available schema names in your model.
  * Added a new [`GET /api/v1/api-keys` endpoint](https://docs.omni.co/api/api-tokens/list-api-tokens) that lists API tokens in your organization, filterable by type.
  * Added support for specifying a custom document identifier to the [`POST /api/v1/documents`](https://docs.omni.co/api/documents/create-document) and [`PATCH /api/v1/documents/:identifier`](https://docs.omni.co/api/documents/update-document) endpoints.
  * Restricted Queriers can now create [Personal Access Tokens](https://docs.omni.co/api/authentication#token-types).

  **Dashboards**

  * Added support for reordering, relabeling, and customizing page tabs in advanced dashboard layouts.
  * Updated the [advanced layout documentation](https://docs.omni.co/visualize-present/dashboards/advanced-layout) to reflect the new behavior for adding queries to dashboards. Now, when a new query is added to a dashboard, it will automatically be placed on the first page in a named stack container.

  **Embedding**

  Updated the embed [`entity` parameter](https://docs.omni.co/embed/setup/url-parameters/entity) documentation to reflect that entities are limited to 64 characters.

  **Integrations**

  * Added a per-connection **Auto-generate relationships** setting that lets you control whether Omni infers relationships from foreign keys, column names, both, or neither during schema refresh.
  * Added [slash command](https://docs.omni.co/integrations/omni-slack-agent#using-slash-commands) support to the Omni Slack Agent. This update also removes the **Home** tab. The settings previously in this tab can now be set using slash commands.
  * Added support for specifying multiple catalogs (databases) in Redshift connections.
  * Added documentation for the [Google Calendar](https://docs.omni.co/integrations/ai/google-calendar) and [Google Drive](https://docs.omni.co/integrations/ai/google-drive) AI integrations. See the [Google setup guide](https://docs.omni.co/integrations/ai/google-setup) for help setting up these integrations.
  * Added documentation for [External AI integrations](https://docs.omni.co/integrations/ai/index), including setup guides for [Slack](https://docs.omni.co/integrations/ai/slack) and [GitHub](https://docs.omni.co/integrations/ai/github) integrations.
  * Updated the [Omni Slack Agent documentation](https://docs.omni.co/integrations/omni-slack-agent#scoping-responses) to clarify that the agent enforces the same permissions and access controls as the rest of Omni, including access grants, user attributes, and connection-level permissions.
  * Added a [guide about dbt and Git workflows](https://docs.omni.co/integrations/dbt/git-workflows) in Omni, including guidance on managing changes with Omni's SDLC controls.

  **Modeling**

  * Added support for view-scoped tag filtering in topic fields using the [`view_name:tag:tag_name` directive syntax](https://docs.omni.co/modeling/topics/parameters/fields).
  * Updated the [`ai_chat_topics`](https://docs.omni.co/modeling/models/ai-chat-topics) documentation to specify that the parameter only affects topic visibility in AI search results. Topics not included can still be accessed through direct queries, since the AI runs with the same permissions as the user.
  * Added documentation for the [`parent_field` dimension](https://docs.omni.co/modeling/dimensions/parameters/parent-field) property, which allows you to specify the parent field for nested dimensions and control how labels are displayed in hierarchies.
  * Updated the [Data input documentation](https://docs.omni.co/analyze-explore/data-input-csvs) to clarify that topics created from uploads automatically receive empty `required_access_grants` at creation time, making them exempt from model-level `default_topic_required_access_grants`.
  * Added a [guide explaining how to use templated filters for advanced date flexibility patterns](https://docs.omni.co/guides/modeling/date-flexibility-templated-filters), giving your end users more control over date filtering options.

  **Workbook**

  Added a [**Remove unused** button](https://docs.omni.co/modeling/develop/promotion#removing-unused-objects-from-the-workbook) in the workbook model changes panel that identifies and removes extension objects (fields, views, topics, relationships) that aren't referenced by any query in the workbook.
</Update>

<Update label="April 12, 2026">
  **Rotate git webhook secrets**

  Added a [**Rotate secret** button to the model git settings](https://docs.omni.co/integrations/git/settings#webhook-secret) that allows you to generate a new webhook secret without unlinking and re-linking your git repository.

  **HTTPS-token based authentication for git integrations**

  Added HTTPS token-based authentication for [git connections](https://docs.omni.co/integrations/git/setup/index), allowing you to use GitHub fine-grained personal access tokens and GitLab project access tokens.

  **Get started with AI-guided topic creation!**

  Added documentation for the [AI-guided quickstart workflow](https://docs.omni.co/modeling/topics/quickstart), which can help you create your first topic from business questions.

  **Administration**

  * Added [Portuguese (Brazil) locale support](https://docs.omni.co/administration/localization).
  * Renamed **Token Tracking** to **Credit Tracking** throughout the application and documentation to better reflect the billing model.

  **AI**

  * Added a [**Home** tab to the Omni Slack Agent](https://docs.omni.co/integrations/omni-slack-agent#managing-your-settings) that provides a persistent surface for account management and settings directly in Slack.
  * Improved agentic follow-up performance by carrying the topic from conversation history, so the AI no longer needs to rediscover it on each turn. Also added validation to the [Create AI job endpoint](https://docs.omni.co/api/ai/create-ai-job) to return a `404` error if you provide an invalid or restricted `topicName`, instead of silently failing at runtime.
  * Added setup instructions for [Claude Code Cloud](https://docs.omni.co/ai/mcp/claude-code) to the MCP documentation.
  * Added clarification about user chat access to the [Omni Agent guide](https://docs.omni.co/ai/chat#sharing-chat-sessions).

  **API**

  * Added optional `find` and `find_type` query parameters to the content validator API endpoint. See the [API documentation](https://docs.omni.co/api/content-validator/validate-content) for details on the new parameters and their usage.
  * Added documentation for the [**Create draft** endpoint](https://docs.omni.co/api/documents/create-draft), which allows you to create a draft for a document.
  * Added clarification to the [**Find and replace content** endpoint reference](https://docs.omni.co/api/content-validator/find-and-replace-content#body-only-in-workbook-id) that the endpoint's `only_in_workbook_id` parameter expects a workbook UUID, not a URL slug.

  **Content**

  Added an **Allow users to copy values to the clipboard** toggle in the [embed share modal](https://docs.omni.co/share#customize-embed-content). When enabled, this includes the `clipboard-write` permission in the generated iframe snippet, allowing users to copy values directly within embedded dashboards without requiring manual iframe HTML edits.

  **Dashboards**

  * New queries are now automatically added to the first page of a dashboard when using advanced layouts.
  * Chart settings can now be [edited inline in the properties panel](https://docs.omni.co/visualize-present/dashboards/advanced-layout#editing-charts) when working with advanced layout dashboards.
  * Added a [**Wrap** toggle](https://docs.omni.co/visualize-present/dashboards/advanced-layout#layout-types) to the stack container properties panel in advanced layouts, allowing you to control whether flex items wrap to new lines when they exceed the container width.

  **Embedding**

  Added information about keyboard shortcuts being unsupported for embedded Omni instances to the [Embed limitations](https://docs.omni.co/embed/limitations#keyboard-shortcuts).

  **Modeling**

  * Fixed an issue where embed users couldn't query uploaded CSVs when the model had `default_topic_required_access_grants` set. CSV upload topics now explicitly set empty required access grants at creation time, overriding the model default.
  * Added documentation for the [`default_timeframes`](https://docs.omni.co/modeling/models/default-timeframes) model parameter, which allows you to specify default timeframes for dimensions in your semantic model.
  * Added documentation for the [**Allow exploration** setting](https://docs.omni.co/modeling/develop/shared-extensions/settings) in shared extension models, which controls whether users can create analyses using that extension.
  * Corrected the values of the [`duration` parameter](https://docs.omni.co/modeling/dimensions/parameters/duration) to be singular.
  * Added documentation for the field-level [`extends` parameter](https://docs.omni.co/modeling/dimensions/parameters/extends), which allows you to inherit properties from dimensions in other views.
  * Updated the documentation for the [`sample_queries`](https://docs.omni.co/model/sample-queries) parameter to include the `desc` field in `sort` entries.
  * Clarified the behavior of `many-to-many` relationships in the [`reversible` parameter reference](https://docs.omni.co/modeling/relationships/parameters/reversible).
</Update>

<Update label="April 5, 2026">
  **Omni Slack Agent now in beta**

  Get AI-powered answers from your semantic model without ever leaving Slack. See [the docs](https://docs.omni.co/integrations/omni-slack-agent) for more information, or reach out to Omni support if you're interested in participating in the beta.

  **Override model defaults in the Omni Agent**

  The new [model tier selector](https://docs.omni.co/ai/chat#selecting-an-ai-model-tier) lets you choose between **Smarter**, **Standard**, and **Faster** AI model options, overriding the default setting from your AI settings.

  **Visualize your topics**

  The new [**Diagram tab** in the workbook topic editor](https://docs.omni.co/modeling/topics/setup#visual-review-diagram) displays a visual representation of a topic's structure — including its views, joins, dimensions, and measures — allowing you to build and maintain topics with ease.

  **Define reusable custom formats**

  The new model-level [`custom_formats`](https://docs.omni.co/modeling/models/custom-formats) parameter allows you to define custom formats once and reference them in fields throughout the model. See the [Formatting values guide](https://docs.omni.co/modeling/models/format-values) for more information, including use cases and examples.

  **Administration**

  Added an organization-level toggle in **Settings > Organization > Preferences** that allows org admins to [opt out of easter eggs](https://docs.omni.co/administration/settings#preferences).

  **AI**

  * Renamed **AI Assistant** to **Omni Agent** throughout the application.

  **API**

  * Added a new API endpoint [`GET /api/v1/models/{modelId}/dbt-exposures`](https://docs.omni.co/api/dbt/get-dbt-exposures) that returns dbt exposures for a model by analyzing which dbt models are referenced by dashboards.
  * Added an optional `queryAllViews` parameter to the [`POST /api/v1/ai/generate-query` endpoint](https://docs.omni.co/api/ai/generate-a-query) that respects your model's [`query_all_views_and_fields` AI setting](https://docs.omni.co/modeling/models/parameters/ai-settings/query-all-views-and-fields).
  * Added an optional `branchId` field to the [`POST /api/v1/query/run` endpoint](https://docs.omni.co/api/queries/run-query) so you can target a specific model branch when running queries via the API.

  **Dashboards**

  * Moved the Advanced layout page **Key** field from the **Properties** panel into an **Advanced settings** dialog, accessible via the 3-dot menu.
  * Added a new [**Timeframe** filter control](https://docs.omni.co/visualize-present/dashboards/advanced-layout#timeframe-filter-control) for date fields on advanced layout dashboards.

  **Embed**

  Added a new [`appearance:mode` inbound embed event](https://docs.omni.co/embed/events/appearance-mode) that allows parent applications to switch the embedded Omni session's color scheme between dark, light, or system mode using `postMessage`.

  **Modeling**

  Added a `markdown` parameter to [dimensions](https://docs.omni.co/modeling/dimensions/parameters/markdown) and [measures](https://docs.omni.co/modeling/measures/parameters/markdown) that lets you define mustache templates to render field values as markdown in table columns.

  **Workbooks**

  Added [keyboard shortcut](https://docs.omni.co/getting-started/keyboard-shortcuts#workbook-shortcuts) support to toggle between chart and results views in the workbook query options panel. You can now use **Option+Click** on Mac or **Alt+Click** on Windows on the chart/results toggle button, or use **Shift+Alt+1** to toggle results and chart with options open.

  **Documentation**

  * Added documentation for the [Omni CLI](https://docs.omni.co/developers/cli) and [Agent Skills](https://docs.omni.co/developers/agent-skills) to the **Developers** section of the docs.
  * Added documentation about creating [statistical forecasts and projections](https://docs.omni.co/ai/forecasting) with AI.
  * Updated the [Omni Agent documentation](https://docs.omni.co/ai/chat#sharing-chat-sessions) to include information about sharing chat sessions.
  * Added a [troubleshooting section](https://docs.omni.co/ai/mcp/claude-code#troubleshooting) to the Claude Code MCP guide.
  * Added an [Authentication settings reference](https://docs.omni.co/administration/settings/authentication) to the Admin section of the docs.
  * Added documentation about managing [user-specific account settings](https://docs.omni.co/administration/users/your-account) to the Admin section of the docs.
  * Added a [new best practices guide](https://docs.omni.co/ai/eval-design-guide) about building effective eval sets to measure and improve Omni AI query generation accuracy.
  * Added **Common questions** sections to the dbt [category page](https://docs.omni.co/integrations/dbt/index#common-questions) and [setup guide](https://docs.omni.co/integrations/dbt/setup#common-questions).
</Update>

<Update label="March 29, 2026">
  **Administration**

  * [Custom emoji rendering](https://docs.omni.co/administration/settings/emoji) is now fully available across the app.
  * Added organization-level control over [emoji mode](https://docs.omni.co/administration/settings/emoji) for query tab names.
  * Added [custom branding asset support](https://docs.omni.co/administration/themes/application#branding-assets) to application themes.
  * Improved the [label editing experience](https://docs.omni.co/content/organize#label-options) by consolidating the **Verified** and **Home page** options into the **Edit label** dialog as checkboxes.
  * Added two new customizable colors to the [Application theme settings](https://docs.omni.co/administration/themes/application#styles) — **Action border** and **Action text** — that control the appearance of outline and transparent buttons.

  **AI**

  * Added support for navigating prompt history in the Blobby chat input using the **Up** and **Down** arrow keys.
  * Added an **Optimize topic for AI** skill to the Model IDE's AI assistant that automatically appears as a clickable option.
  * Added support for pie, donut, and heatmap visualizations to the AI Assistant.

  **API**

  * Added a new [`GET /api/v1/connections/{connectionId}/dbt/environments` endpoint](https://docs.omni.co/api/dbt/list-dbt-environments) that allows you to list all dbt environments for a connection.
  * Added a [`DELETE /api/v1/connections/{connectionId}/dbt/environments/{environmentId}` endpoint](https://docs.omni.co/api/dbt/delete-dbt-environment), allowing you to programmatically delete dbt environments.

  **Content**

  * When you hover over a label, you can now see who applied it and when. This [metadata](https://docs.omni.co/content/organize#viewing-label-information) appears in label tooltips across detail pages, content listings, search results, and the curation popover.
  * When you save an analysis without a name, Omni now automatically suggests a meaningful title and description.

  **Dashboards**

  * Added support for multi-page PDF pagination on advanced layout dashboards.
  * Updated advanced layouts so that [page navigation](https://docs.omni.co/visualize-present/dashboards/advanced-layout#page-navigation-for-viewers) is now automatically added to the first and second pages when a new page is added.

  **Embed**

  * Added two new embed events: [`sidebar:open`](https://docs.omni.co/embed/events/sidebar-open) fires when users click the mobile menu button, and [`navigation:home`](https://docs.omni.co/embed/events/navigation-home) fires when users click the logo or home header link in embedded Omni instances.
  * Added support for opting out of embed link rewriting by including [`NO-EMBED-LINK-REWRITE`](https://docs.omni.co/embed/customization/link-content#opt-out-of-link-rewriting) in dashboard URLs.

  **Integrations**

  * Added support for [Redshift Serverless as a PrivateLink option](https://docs.omni.co/connect-data/redshift-privatelink).

  **UI**

  * Moved the **My activity** navigation link into the **Personal** section, positioned after **My documents**. Previously, this link was located in the bottom navigation group alongside **All** and **Trash**.
  * Added [chat sessions](https://docs.omni.co/content/activity#chat-sessions) to the **My Activity** page. You can now see your chat session history interleaved with your exploration history, making it easy to navigate back to sessions as needed.
  * Added a new "Omni 1984" theme that recreates the classic 1-bit Macintosh aesthetic from the early 1980s.

  **Workbooks**

  * Renamed **Query Fields** to **Tab-only fields** in the model browser, and updated context menus for tab-only views and fields.
</Update>

<Update label="March 22, 2026">
  **Administration**

  Added Workload Identity support for GCS audit log delivery, allowing you to send audit logs to your GCS bucket without sharing service account keys.

  **AI**

  Improved the `searchOmniDocs` tool in Model Context Protocol by switching to Omni's AI-powered documentation search. The tool now accepts a question instead of a URL, and uses the same intelligent page selection, token limiting, and answer synthesis as the in-app documentation search feature.

  **API**

  Added a new API endpoint to [update dbt environments](https://docs.omni.co/api/dbt/update-dbt-environment).

  **Content**

  * Added support for document descriptions across the API and UI. You can now add an optional description (up to 1024 characters) when creating documents, update descriptions via the **Rename** dialog or API endpoints.
  * Added color and description fields to labels. These changes are fully supported in the API for creating, updating, and retrieving labels.

  **Dashboards**

  Added a multi-select dropdown control for string filters in the advanced layout.

  **Embedding**

  Added a new [`ai:chat-start` embed event](https://docs.omni.co/embed/events/ai-chat-start) that fires when an AI chat session begins, either when the chat route loads or when the workbook AI drawer opens.

  **Integrations**

  Added per-user OAuth for Databricks query execution with optional personal access token (PAT) or OAuth admin support for schema refresh. You now only need to register a single OAuth application in Databricks instead of two — per-user authentication handles queries, while schema refresh uses either a PAT or an OAuth admin's token for credentials.

  **Modeling**

  * Added an optional **Group remaining values** toggle to dynamic Top N grouping in workbooks. When disabled, only the top N values are displayed instead of aggregating remaining values into an **Other** row. Use the [`dynamic_top_n.else`](https://docs.omni.co/modeling/dimensions/parameters/dynamic-top-n#param-else) parameter to achieve this result in model YAML.
  * Added pattern matching support to [`ai_chat_topics`](https://docs.omni.co/modeling/models/ai-chat-topics) so you can now use the same inclusion and exclusion syntax as the topic-level `fields` parameter.
  * Added a [`faceting` property to dimensions](https://docs.omni.co/modeling/dimensions/parameters/faceting) that lets you control how suggestion queries are filtered.

  **Workbooks**

  Fixed the **Import Tab** dialog to accept full widget URLs in addition to query IDs. Previously, you could only paste raw query IDs; now you can paste complete URLs and the dialog will extract the query ID automatically.
</Update>

<Update label="March 15, 2026">
  **API**

  * Added an API for [creating dbt environments on connections](https://docs.omni.co/api/dbt/create-dbt-environment), allowing you to programmatically manage dbt environments.
  * Added an API that allows you to programmatically [set the active dbt environment on a branch](https://docs.omni.co/api/dbt/set-dbt-environment-on-model-branch), allowing you to automate dbt environment configuration in CI/CD pipelines before triggering schema refreshes.

  **Dashboards**

  * Added [undo and redo controls](https://docs.omni.co/visualize-present/dashboards/advanced-layout#undoing-and-redoing-layout-changes) for advanced layout dashboards.
  * Removed the redundant AI chat toggle from the **Edit dashboard** toolbar. You can now manage AI chat settings exclusively through the **Document Settings** dialog in published dashboards.

  **Modeling**

  * Added support for dynamic user attribute references in three model properties:

    * [`fiscal_month_offset`](https://docs.omni.co/modeling/models/fiscal-month-offset)
    * [`week_start_day`](https://docs.omni.co/modeling/models/week-start-day)
    * [`default_numeric_locale`](https://docs.omni.co/modeling/models/default-numeric-locale)

    Using Mustache references (`{{'{{omni_attributes.attribute_reference}}'}}`), you can reference user attributes and the values will be resolved at query time using the user's metadata.
  * Added a [`tags`](https://docs.omni.co/modeling/topics/parameters/tags) topic parameter, allowing you to categorize and organize topics similar to how you can tag fields and views.
  * Added a **Go to connection** option to the **Model** menu in the model IDE.

  **Workbooks**

  * Added support for applying data formatting to Excel downloads.
</Update>

<Update label="March 8, 2026">
  **AI**

  * Added support for [custom model identifiers](https://docs.omni.co/ai/settings/model-providers/openai) in OpenAI-compatible endpoints, allowing you to bring your own models (BYOM) for providers like Ollama and Azure OpenAI.
  * You can now ask the [AI chat assistant to generate map visualizations](https://docs.omni.co/ai/visualizations#supported-visualization-types) for geographic questions. When you ask questions like *"show me orders by state on a map,"* the AI will create region maps (choropleths) or point maps as appropriate for your data.
  * Renamed [AI workflows](https://docs.omni.co/ai/skills) to "skills" throughout Omni. Existing model files using `workflows:` will continue to work without changes.

  **Administration**

  * Added a confirmation dialog when disabling [personal access tokens](https://docs.omni.co/api/authentication#token-types).

  **API**

  * Added `onlySharedWithMe` as a new filter option to the [List folders API](https://docs.omni.co/api/folders/list-folders) to retrieve only folders that have been explicitly shared with you via folder permits, excluding folders you own.
  * Added `onlySharedWithMe` as a new filter option to the [List documents API](https://docs.omni.co/api/documents/list-documents) to retrieve only documents that have been explicitly shared with you via documents permits, excluding documents you own.

  **Dashboards**

  * [Cross-filtering](https://docs.omni.co/visualize-present/dashboards/filters#cross-filtering) is now generally available. You can use cross-filtering to filter data across multiple dashboard tiles by clicking on values in your visualizations.
  * Added a [button toggle control type](https://docs.omni.co/visualize-present/dashboards/advanced-layout#displaying-single-select-options-as-buttons) for single selection string filters, allowing you to display filter options as clickable buttons instead of a dropdown. **Available for **[**Advanced Dashboard layouts**](https://docs.omni.co/visualize-present/dashboards/advanced-layout)** only.**

  **Embedding**

  * Added support for generic embed integrations like FullStory and LogRocket. You can now configure integration credentials in **Settings > Embed > Integrations**.
  * Added support for creating multiple [embed secrets](https://docs.omni.co/embed/admin/secrets) in an Omni instance.
</Update>

<Update label="March 1, 2026">
  **AI**

  * Added a new `opus` model tier so you can set `model: opus` in your model's [`ai_settings`](https://docs.omni.co/modeling/models/parameters/ai-settings) to use Claude Opus 4.6.
  * Updated the [`ai_settings.query_all_views_and_fields`](https://docs.omni.co/modeling/models/parameters/ai-settings/query-all-views-and-fields) parameter to accept `enabled | disabled | default` values instead of `true | false`. This allows you to control whether the AI queries all views and fields when generating SQL.
  * Updated the [`ai_settings` parameter](https://docs.omni.co/modeling/models/parameters/ai-settings) to accept a per-category YAML configuration system. You can now define AI model and thinking preferences for different task categories directly in your semantic model YAML.

  **Administration**

  * Added a **Last login** column to [Settings > Users](https://docs.omni.co/administration/users), so you can see when each user last logged in.
  * Added a new **combined view** to the [**My activity**](https://docs.omni.co/content/activity) page that deduplicates activity by workbook or model and groups entries into time-period sections.

  **Integrations**

  * Added support for creating PrivateLink connections to [Redshift provisioned clusters](https://docs.omni.co/connect-data/redshift-privatelink).
  * Added support for [Snowflake External OAuth](https://docs.omni.co/connect-data/oauth/snowflake#external-oauth), allowing you to authenticate via external identity providers like Okta, Azure AD, or Ping Identity.
  * Added the ability to assign a dbt environment to a specific user when creating or editing environments in Omni.
</Update>

<Update label="February 22, 2026">
  **AI**

  * Added support for uploading Markdown (`.md`) files to AI chat. Previously, Markdown files had to be renamed as `.txt` files to be valid uploads.

  **API**

  * Fixed the merge branch API endpoint to restrict the [`force_override_git_settings` parameter](https://docs.omni.co/api/model-branches/merge-a-branch#body-force-override-git-settings) to Connection Admin and above roles; other users will receive a `403 Forbidden` response. Previously, Modelers could use this parameter via API or PAT to bypass PR-required and git-follower protections, even though they cannot modify git settings in the UI.
  * Added a `force` query parameter to the [Delete folder](https://docs.omni.co/api/folders/delete-folder) endpoint that enables you to recursively delete folders containing documents and sub-folders.
  * Added a `POST /api/v1/uploads` endpoint that allows you to upload a CSV file to create a new data source.

  **Dashboards**

  * Markdown tiles and visualizations now include a `prefers-dark` class name when you're viewing in dark mode, allowing you to write custom CSS that targets light and dark mode separately.

  **Integrations**

  * Added support for Databricks Lakebase as a new database connection type.

  **Modeling**

  * Added search and filter functionality for branches. You can now search branches by name in the **Branches** table, and when you have 10 or more branches in the IDE, a **Search branches...** option appears in the branch selector dropdown to help you quickly find the branch you need.

  **Visualizations**

  * Added support for Markdown columns in table visualizations, which allow you to format and style cell content using Markdown syntax. **Note**: This feature is still in development and is not yet available in-app.
  * Added percentage tooltips to [Sankey charts](https://docs.omni.co/visualize-present/visualizations/types/sankey). You can now enable the **Show percentages** toggle in the Sankey editor's tooltip settings to display percentage breakdowns in your chart tooltips. Additionally, the node tooltip label has been renamed from **Total** to **Value** for clarity.

  **Workbooks**

  * Added a new **Multi-Field Filter** control type that allows you to create `OR` filters across multiple fields in workbooks. You can now build queries like `Country is USA OR Gender is Female` by clicking the **+ Field** button in filter popovers. **Note**: This feature is still in development.
</Update>

<Update label="February 15, 2026">
  **AI**

  * Added an organization-wide [**MCP server** setting](https://docs.omni.co/ai/settings/features) to **AI Hub > General > Features** that controls whether users can authorize external AI tools to connect via OAuth. When disabled, new OAuth approval requests are rejected and existing MCP grants are blocked from making tool calls. This setting defaults to enabled.
  * Added the ability for Blobby to search the official Omni docs. This new tool is available in the Query Helper, [AI Assistant](https://docs.omni.co/ai/chat), and Dashboard Assistant.

  **API**

  * Added a new [`GET /api/v1/uploads` endpoint](https://docs.omni.co/api/uploads/list-uploads) that allows you to list uploaded CSVs (data input tables).
  * Added `url` fields to document, query, and folder API responses, giving you direct links to any piece of content in the Omni UI.

  **Dashboards**

  * Added the ability to select built-in color palettes (such as "Omni Blues", "Omni Threes", and "Omni") as default palettes in the [dashboard theme editor](https://docs.omni.co/visualize-present/dashboards/theming), in addition to custom palettes.

  **Integrations**

  * Added [Databricks PrivateLink](https://docs.omni.co/connect-data/databricks-privatelink) support for both Azure and AWS infrastructure. You can now create private connections to Databricks workspaces using native Private Endpoints on Azure and VPC Interface Endpoints on AWS.

  **Modeling**

  * Added Australian Dollar (AUD) currency formatting options to the dimension and measure [`format`](https://docs.omni.co/modeling/dimensions/parameters/format) parameter.

  **Visualizations**

  * Added a [**Funnel** visualization type](https://docs.omni.co/visualize-present/visualizations/types/funnel), which you can now use to visualize data flowing through sequential steps.

  **Workbooks**

  * Added YAML views and copy buttons to the [workbook inspector](https://docs.omni.co/analyze-explore/workbook-inspector), making it easy to view and copy query and visualization configuration in the sample query YAML format.
</Update>

<Update label="February 8, 2026">
  **AI**

  * Added Claude Opus 4.5 and 4.6 to the [list of available models](https://docs.omni.co/ai/settings/model-providers) when configuring a bring-your-own LLM with Anthropic as your provider.
  * Added the ability to paste images directly into the AI chat input from clipboard across all surfaces (chat page, dashboard, and workbook). Note that this feature currently works in Chrome and Safari, but not in Firefox.

  **Administration**

  * Fixed an issue on the **Users** page where a crash would occur for organizations with large numbers of users.

  **Dashboards**

  * Added a **Cross-filtering** setting in dashboard settings that allows you to enable or disable [cross-filtering](https://docs.omni.co/visualize-present/dashboards/filters#cross-filtering) on a per-dashboard basis.
  * Added new [dashboard metadata variables](https://docs.omni.co/visualize-present/mustache-reference#dashboard-metadata) to Markdown tiles:

    * `{{'{{metadata.createdAt}}'}}`
    * `{{'{{metadata.createdBy}}'}}`
    * `{{'{{metadata.lastUpdatedAt}}'}}`

    You can now reference these variables in your text tile templates to display when the dashboard was created, who created it, and when it was last updated.

  **Integrations**

  * Added support for enabling and disabling the [dbt Semantic Layer integration](https://docs.omni.co/integrations/dbt/semantic-layer) with the **Enable semantic layer** setting in the dbt settings.
  * Added a [quick connect feature](https://docs.omni.co/connect-data/setup/quick-connect) that lets you paste a connection string URI (for example, `postgresql://user:pass@host:5432/db`) to automatically create a database connection.
</Update>

<Update label="January 25, 2026">
  **AI**

  * Added Snowflake Cortex as an [AI model provider](https://docs.omni.co/ai/settings/model-providers/snowflake-cortex). You can now use Claude models hosted on Snowflake Cortex for AI features in Omni.
  * Added [OAuth 2.1 support for MCP clients](https://docs.omni.co/ai/mcp/authentication) like Claude and ChatGPT. Users can now authenticate AI assistants with Omni through a standard OAuth flow instead of manually copying API keys.
  * Added [Sankey chart generation to AI visualization capabilities](https://docs.omni.co/ai/visualizations).
  * Auto Learn is now in beta. When enabled, administrators can review and approve AI-generated modeling suggestions directly from chat conversations with the [AI Assistant](https://docs.omni.co/ai/chat) and [Dashboard Assistant](https://docs.omni.co/ai/dashboard-assistant).

  **API**

  * Added credential update support to the [`PATCH /api/v1/connections/{id}` endpoint](https://docs.omni.co/api/connections/update-connection). You can now programmatically rotate passwords, BigQuery service account keys, and Snowflake RSA private keys.
  * Promoted YAML model API routes from `/api/unstable/` to `/api/v1/`. The following endpoints are now stable:
    * `GET /api/v1/models/{modelId}/yaml`
    * `POST /api/v1/models/{modelId}/yaml`
    * `DELETE /api/v1/models/{modelId}/yaml`
  * Added new parameters to the Schedules API. Organization API keys can now create schedules on behalf of another user using the `userId` query parameter on `POST /api/v1/schedules`. The `GET /api/v1/schedules` endpoint now returns an `ownerId` field (membership ID) for each schedule.
  * Updated the List Folders API to return only folders that users have permission to access when using Personal Access Tokens (PAT). PAT users now see the same folder visibility through the API as they do in the UI. Organization-scoped API keys retain full access to all folders.
  * Added a `408 Timeout` response to the [Run Query API](https://docs.omni.co/api/queries/run-query).

  **Modeling**

  * Added [isolated branches support for model extensions](https://docs.omni.co/modeling/develop/shared-extensions/extension-branches). Extension models can now have their own independent branches that are separate from the parent shared model.

  **Visualizations**

  * Improved Sankey chart error handling. The technical error message for [cyclic data](https://docs.omni.co/visualize-present/visualizations/types/sankey#troubleshooting) is now translated to a user-friendly message: `"Sankey does not support cycles or paths that loop back to previous nodes."`

  **Workbooks**

  * Renamed some workbook menu items to improve clarity and avoid confusion with the model promotion workflow:
    * [**Promote to workbook**](https://docs.omni.co/analyze-explore/calculations#promote-table-calculations) for table calculations is now **Add to workbook**
    * **Promote as workbook defaults** for colors is now **Save to workbook**
</Update>

<Update label="January 18, 2026">
  **API**

  * The [Query APIs](https://docs.omni.co/api/queries/run-query) are now enabled by default. This includes endpoints for running semantic queries (`POST /api/unstable/query/run`) and waiting for query results (`GET /api/unstable/query/wait`).
  * Added an `identifier` query parameter to the [GET /api/v1/schedules](https://docs.omni.co/api/schedules/list-schedules) endpoint for filtering schedules by dashboard identifier.
  * Added missing POST endpoints for connections, models, and schedules to the public OpenAPI spec. Also added SCIM embed user endpoints for programmatic management of embed users. Access the spec at `https://<your-omni-instance>/api-explorer`

  **Dashboards**

  * Added an **Inspect** option to the dashboard chart menu that opens the workbook with the inspector panel pre-opened, providing quick access to SQL debugging info including query SQL, cache status, and execution details.

  **Embedding**

  * Added support for [Safari 26.2's CHIPS (Cookies Having Independent Partitioned State) partitioned cookies](https://docs.omni.co/embed/limitations#safari) in embedded dashboards. Safari 26.2+ users now skip the Storage Access API handshake flow, providing a smoother embed experience. Vanity domain embeds continue to use the existing Storage Access API flow.
  * Added `dashboardId` to the [`status` embed event](https://docs.omni.co/embed/events/status) payload, allowing embedded dashboard consumers to identify which dashboard emitted the event.

  **Integrations**

  * Added the ability to choose a [starting point for new Omni branches](https://docs.omni.co/content/develop/branch-mode#creating-branches): from the shared model, another branch, or a specific model version.
  * Multiple models can now share a single [git repository](https://docs.omni.co/integrations/git) with one webhook handling all associated models. When a pull request event occurs, all linked models are processed sequentially.

  **Visualizations**

  * Released the [Sankey diagram visualization](https://docs.omni.co/visualize-present/visualizations/types/sankey) for showing flow and distribution between categories.
</Update>

<Update label="January 4, 2026">
  **AI**

  * Added an AI-powered cron expression generator to help create custom schedules for dashboard refreshes and schema refreshes.

  **Administration**

  * Users with **Editor** permissions can now delete empty folders they created. Previously, only users with Manager permissions could delete folders.

  **API**

  * Added a `lastLogin` timestamp to the SCIM user API endpoints (`GET /api/scim/v2/Users` and `GET /api/scim/v2/Users/:id`). This enables programmatic identification of inactive users for cleanup.
  * Added API endpoints for managing dashboard filters and controls:
    * [`GET /api/v1/dashboards/:identifier/filters`](https://docs.omni.co/api/dashboard-filters/get-dashboard-filters-and-controls) - Retrieve filter and control configuration
    * [`PATCH /api/v1/dashboards/:identifier/filters`](https://docs.omni.co/api/dashboard-filters/update-dashboard-filterscontrols) - Update filter values, control settings, and display order
  * Added a `GET /api/v1/documents/:identifier` endpoint that returns document configuration in a format compatible with `PUT` for round-trip editing.
  * Added `PUT /api/v1/documents/:identifier` endpoint to programmatically update dashboard documents.
  * Extended `PUT /api/v1/documents/:identifier` endpoint with `filterConfig` and `filterOrder` support for setting dashboard filter configuration via API.
  * Extended the `PUT /api/v1/documents/:identifier` endpoint with query presentations support.
  * Extended the [Run query API](https://docs.omni.co/api/queries/run-query) to allow unlimited pivoted query results when the result format is set to CSV or XLSX.
  * Added `POST /api/v1/documents/:identifier/duplicate` endpoint to programmatically duplicate published documents.
  * Added a `PATCH /api/v1/documents/{identifier}/labels` endpoint for bulk adding and removing labels from a document in a single atomic operation.
  * Added support for the `**` (recursive wildcard) pattern in the List folders API endpoint. Use `GET /api/unstable/folders?path=folder/**` to retrieve all nested child folders under a given path.

  **Integrations**

  * Added a **Problems** page for dbt integrations that displays validation issues and errors in your dbt models.

  **Modeling**

  * Added a new "merged" model editing mode for branch models. This allows users to edit branch models merged with the shared model, enabling the ability to unignore items from the shared model while working in a branch.

  **Visualizations**

  * Added a **Sum** sorting option for stacked charts that sorts segments by their total value across all stacks.

  **Workbooks**

  * Added **Count True** and **Count False** quick aggregation options for boolean fields. These options count rows where the boolean field is true or false, respectively.
  * Added the ability to use links defined in the model file when using the **Display as link** option in tables. Note: Changing a link label in the model will break existing references.
</Update>


# Archiving (deleting) connections
Source: https://docs.omni.co/connect-data/archive-connection

Archive a database connection to permanently remove it from your Omni organization, including its associated models and content.

Archiving a connection allows you to delete it from your organization.

**When a connection is deleted:**

* The connection and its associated models and content will be moved to the [Trash](/content/archive-restore)
* Sensitive information, such as passwords and keys, will be fully deleted

## Deleting a connection

1. In Omni, navigate to **Settings > Connections**.
2. Click the connection you want to delete.
3. Click the connection's **Archive** tab.
4. Click **Move to trash**.
5. You'll be prompted to confirm the deletion. Confirm by entering the name of the connection in the dialog that displays.
6. Click **Move to trash** again to complete the deletion.

## Deleting a connection via the API

You can programmatically delete connections using the `DELETE /api/v1/connections/{id}` endpoint. This is useful for infrastructure-as-code workflows where connections are managed programmatically. See the [Connections API reference](/api/connections) for authentication requirements, request format, and error codes.

## Deleting a connection

<Tip>
  You can also delete connections using the [Delete connection](/api/connections/delete-connection) API.
</Tip>

1. In Omni, navigate to **Settings > Connections**.
2. Click the connection you want to delete.
3. Click the connection's **Archive** tab.
4. Click **Move to trash**.
5. You'll be prompted to confirm the deletion. Confirm by entering the name of the connection in the dialog that displays.
6. Click **Move to trash** again to complete the deletion.

## Restoring deleted connections

To restore a deleted connection:

1. Click the **Trash** option in the main [sidebar](/administration/settings/sidebar).
2. Click the **Connections** tab.
3. Locate the connection and click **Restore**.
   <Note>
     **Don't see a connection?** Archived connections only display in the trash if they were archived within your organization's [Trash visibility window](/administration/settings#trash-visibility-window).
   </Note>
4. You'll be redirected to the connection's settings page, where you'll need to re-enter any sensitive information like passwords or keys.
5. When finished, click **Update and test connection**.


# Connect to private databases with AWS PrivateLink
Source: https://docs.omni.co/connect-data/aws-privatelink

Set up AWS PrivateLink to connect Omni to databases in private VPCs using encrypted VPC endpoint connections.

<Note>
  This guide does not apply to **Snowflake** databases, **Redshift-managed VPCs**, or **ClickHouse Cloud** services in AWS. Follow the dedicated PrivateLink guides for these databases:

  * [Snowflake PrivateLink](/connect-data/snowflake-privatelink)
  * [Redshift-managed VPCs PrivateLink](/connect-data/redshift-privatelink)
  * [ClickHouse Cloud PrivateLink](/connect-data/clickhouse-privatelink)
</Note>

If your database is in a private network within Amazon Web Services (AWS), Omni can connect to your database via PrivateLink. In this configuration, Omni establishes an encrypted connection from our network to your network via a VPC endpoint.

## Requirements

To follow the steps in this guide, you'll need permissions in AWS that allow you to create VPC endpoint services.

## Setup

<Steps>
  <Step title="Set up a VPC endpoint in your AWS account">
    In your AWS account, set up a VPC endpoint service that connects to your database:

    * **Allow access to our account principal:** `arn:aws:iam::767117061426:root`

    * **Enable cross-region access and allow access to the regions of your Omni environment:**

      | Region    | Primary          | Disaster recovery |
      | --------- | ---------------- | ----------------- |
      | EastUsa   | `us-east-1`      | `us-west-2`       |
      | Ireland   | `eu-west-1`      | `eu-central-1`    |
      | Australia | `ap-southeast-2` | `ap-southeast-4`  |
      | Canada    | `ca-central-1`   | `ca-west-1`       |
      | India     | `ap-south-1`     | `ap-south-2`      |

    * Per [AWS's PrivateLink prerequisites](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html#prerequisites-endpoint-services), either enable cross-zone load balancing or register healthy targets in every Availability Zone the NLB spans.

    Additionally, **verify that traffic from the VPC endpoint to your database is allowed**. As PrivateLink traffic is internal to the network, Omni's public IP addresses don't apply.

    If using a security group on the load balancer, you'll need to manually disable a setting in AWS to accomplish this:

    1. In the AWS load balancer console, navigate to the **Security tab**.
    2. Click the **Edit** button.
    3. Turn off **Enforce inbound rules on PrivateLink traffic**.
  </Step>

  <Step title="Contact Omni support">
    Contact Omni support with the following information:

    * The name of your VPC endpoint service, for example `com.amazonaws.vpce.REGION.vpce-svc-XXXXXXXXXX`
    * The port your database will be listening on
    * Technical contact details, in case of connection difficulties
  </Step>
</Steps>

## What's next?

After you contact Omni support with the information in step 2, we'll create a VPC endpoint that connects to your service to support the connection to the database.

If your service requires manual approval of new endpoint connections, we will contact you to request approval.

Once this is complete, Omni support will add the new database connection to your Omni instance. The connection can then be used like any other database connection.


# Connect to private databases with Azure PrivateLink
Source: https://docs.omni.co/connect-data/azure-privatelink

Set up Azure Private Link to connect Omni to databases in private Azure networks using encrypted private endpoint connections.

<Note>
  This guide does not apply to **Snowflake** or **Azure SQL** databases in Azure. Follow the dedicated PrivateLink guides for these databases:

  * [Snowflake PrivateLink](/connect-data/snowflake-privatelink)
  * [Azure SQL Private Link](/connect-data/azure-sql-privatelink)
</Note>

If your database is in a private network within Microsoft Azure, Omni can connect to your database via Azure Private Link. In this configuration, Omni establishes an encrypted connection from our network to your network via a private endpoint connection.

## Requirements

To follow the steps in this guide, you'll need permissions in Azure that allow you to create PrivateLink services.

## Setup

<Steps>
  <Step title="Set up a PrivateLink service in your Azure account">
    In your Azure account, set up a PrivateLink service that connects to your database.

    If you choose to restrict access by subscription, Omni's subscription ID is:

    ```
    081a7a2c-5971-4342-ac5e-bf9e4d8235b0
    ```

    Additionally, **verify that traffic from the PrivateLink service to your database is allowed**. As PrivateLink traffic is internal to the network, Omni's public IP addresses don't apply.
  </Step>

  <Step title="Contact Omni support">
    After you finish setting up the PrivateLink service, contact Omni support with the following information:

    * The alias of your PrivateLink service, for example `pls-name.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.region.azure.privatelinkservice`
    * The port your database will be listening on
    * Technical contact details, in case of connection difficulties
  </Step>
</Steps>

## What's next?

After you contact Omni support with the information in step 2, we'll create a private endpoint connection that connects to your service to support the connection to the database.

If your service requires manual approval of new endpoint connections, we will contact you to request approval.

Once this is complete, Omni support will add the new database connection to your Omni instance. The connection can then be used like any other database connection.


# Connect to Azure SQL Database with Azure Private Link
Source: https://docs.omni.co/connect-data/azure-sql-privatelink

Connect Omni to an Azure SQL Database over a private network using an Azure Private Link service.

<Note>
  This guide is for **Azure SQL Database**. For other databases in a private Azure network, follow the [Azure Private Link guide](/connect-data/azure-privatelink).
</Note>

Omni can connect to your Azure SQL Database via Azure Private Link. In this configuration, Omni establishes an encrypted connection from our network to your network via a private endpoint connection.

## Limitations

Azure SQL Managed Instance isn't currently supported. Contact Omni support if you need to connect a managed instance.

## Requirements

To follow the steps in this guide, you'll need **Organization Admin** permissions in Omni, plus the following in Azure:

* An Azure SQL logical server
* Permissions that allow you to create Private Link services
* Permissions that allow you to view and change the server's connection policy

### Connection policy

Your logical server's connection policy must be **Proxy** or **Default**. It must not be **Redirect**.

Omni reaches your database through your Private Link service, which forwards only the ports defined by its load balancing rules. Under the **Redirect** policy the SQL gateway accepts the connection on port `1433` and then hands the client a node address on ports `11000-11999`, which your Private Link service doesn't publish. The connection fails at this second step.

Most servers don't require a change; a private endpoint left on **Default** already behaves as **Proxy** on port `1433`.

To check the current setting, open your server in the Azure portal under **Networking > Connectivity**, or run:

```bash theme={null}
az sql server conn-policy show \
  --resource-group <resource-group> \
  --server <server-name>
```

If it returns `Redirect`, change it to `Proxy`:

```bash theme={null}
az sql server conn-policy update \
  --resource-group <resource-group> \
  --server <server-name> \
  --connection-type Proxy
```

<Note>
  If the policy was set to **Redirect** before the private endpoint was created, you may need to toggle it after the endpoint exists for the change to take effect.
</Note>

## Setup

<Steps>
  <Step title="Set up a Private Link service in your Azure account">
    In your Azure account, expose your Azure SQL server through a Private Link service in your virtual network.

    Omni's subscription ID is:

    ```text theme={null}
    081a7a2c-5971-4342-ac5e-bf9e4d8235b0
    ```

    Add this subscription ID to your Private Link service's:

    * **Visibility list**- Controls who can find the service
    * **Auto-approval list** - **Optional.** Controls whether Omni's endpoint connects without requiring your approval. Omni always creates its endpoint as a manual connection request, so without the auto-approval entry you'll need to manually approve it.

    Additionally, verify that traffic from the Private Link service to your database is allowed. As Private Link traffic is internal to the network, Omni's public IP addresses don't apply.
  </Step>

  <Step title="Contact Omni support">
    After you finish setting up the Private Link service, contact Omni support with the following information:

    * **Your Azure SQL Server hostname**, which ends with `.database.windows.net`. For example, `omni-blobsrus-admin.database.windows.net`.

      <Note>
        Omni connects to your server's regular fully qualified domain name, `<server>.database.windows.net` and resolves it privately from our network. Connections addressed to the private IP or to `<server>.privatelink.database.windows.net` fail by design - the private endpoint routes traffic to the SQL gateway, which needs the real FQDN to route the login.
      </Note>
    * **The resource ID or alias of your Private Link service**:
      * The resource ID contains `/providers/Microsoft.Network/privateLinkServices/`. For example, `/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/privateLinkServices/<service-name>`
      * The alias ends with `.azure.privatelinkservice`. For example, `pls-name.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.region.azure.privatelinkservice`
    * The port your database will be listening on, typically `1433`
    * Technical contact details, in case of connection difficulties
  </Step>
</Steps>

## What's next?

After you contact Omni support with the information in step 2, Omni will create a private endpoint connection that connects to your service to support the connection to the database.

Unless you've added Omni's subscription to your Private Link service's auto-approval list, you'll need to approve the connection request. Omni will contact you to approve it.

Once this is complete, Omni support will add the new database connection to your Omni instance. The connection can then be used like any other database connection. You'll need to provide your [Microsoft SQL Server authentication credentials](/connect-data/setup/microsoftsql#setup) when setting up the connection in Omni.


# Connect to ClickHouse Cloud with AWS PrivateLink
Source: https://docs.omni.co/connect-data/clickhouse-privatelink

Connect Omni to a ClickHouse Cloud service on AWS over a private network using a VPC endpoint.

<Note>
  This guide applies only to **ClickHouse Cloud** services on AWS. For self-hosted ClickHouse in your own AWS network, follow the [AWS PrivateLink guide](/connect-data/aws-privatelink).
</Note>

Omni can connect to your ClickHouse Cloud service on Amazon Web Services (AWS) via PrivateLink. In this configuration, Omni establishes an encrypted connection from our network to ClickHouse Cloud over a private network using a VPC endpoint.

## Requirements

To follow the steps in this guide, you'll need **Organization Admin** permissions in Omni, plus the following in ClickHouse Cloud:

* A service deployed on AWS
* Permissions that allow you to view the service's PrivateLink settings and manage private endpoints for your organization

### Regions

Your ClickHouse Cloud service doesn't have to be in the same region as your Omni instance.

However, PrivateLink isn't available in `ap-east-2` and `mx-central-1` regions. These regions don't support cross-region PrivateLink, and Omni has no AWS environment in either region.

## Setup

<Steps>
  <Step title="Retrieve your ClickHouse PrivateLink details">
    Omni needs two values from your ClickHouse Cloud service:

    * **VPC Endpoint Service** (`endpointServiceId`), which starts with `com.amazonaws.vpce`
    * **Private DNS hostname** (`privateDnsHostname`), which looks like `abc123.eu-west-1.vpce.aws.clickhouse.cloud`

    You can find both in the ClickHouse Cloud console under the service's **Settings**, or by calling the ClickHouse Cloud API.
  </Step>

  <Step title="Contact Omni support">
    Contact Omni support with the following information:

    * The VPC endpoint service name, for example `com.amazonaws.vpce.eu-west-1.vpce-svc-XXXXXXXXXX`
    * The private DNS hostname, for example `abc123.eu-west-1.vpce.aws.clickhouse.cloud`
    * The AWS region where your ClickHouse Cloud service is deployed
    * The port your service will be listening on, typically `8443`
    * Technical contact details, in case of connection difficulties
  </Step>
</Steps>

## What's next?

We will need you to authorize Omni's endpoint **after** we create it. The endpoint ID doesn't exist until then, so there's nothing to add to ClickHouse before you contact us.

1. Omni creates the VPC endpoint and sends you the endpoint ID, which starts with `vpce-`.

2. Register the endpoint ID for your ClickHouse Cloud organization.

3. Add the registered endpoint to the private endpoint allowlist of each ClickHouse service Omni should reach. In the ClickHouse Cloud console, this is under the service's **Settings > Set up private endpoint**.

4. Omni finishes wiring up the connection and adds it to your Omni instance.

<Warning>
  The endpoint must be added at both the organization level and the service level. Organization-level registration alone doesn't grant access to any service, and adding it only at the service level isn't sufficient. The connection fails until you complete both steps.
</Warning>

Once this is complete, the connection can be used like any other database connection. You'll need to provide your [ClickHouse authentication credentials](/connect-data/setup/clickhouse#setup) when setting up the connection in Omni.

## References

* [ClickHouse Cloud - AWS PrivateLink](https://clickhouse.com/docs/manage/security/aws-privatelink)


# Connecting to Databricks using AWS or Azure PrivateLink
Source: https://docs.omni.co/connect-data/databricks-privatelink

Connect Omni to a Databricks workspace over a private network using AWS PrivateLink or Azure Private Link endpoints.

Omni can connect to your Databricks workspace in Amazon Web Services (AWS) or Azure via PrivateLink. In this configuration, Omni establishes an encrypted connection from our network to your Databricks workspace over a private network.

## Requirements

To follow the steps in this guide, you'll need:

* A Databricks workspace configured for PrivateLink access
  * **For Azure**: A VNet-injected Databricks workspace
  * **For AWS**: A Databricks workspace with AWS PrivateLink enabled
* Permissions in your cloud environment to retrieve PrivateLink configuration details
* **Organization Admin permissions in Omni**

## Setup

<Steps>
  <Step title="Gather connection information">
    Before contacting Omni support, retrieve your Databricks workspace connection details:

    * Your Databricks workspace URL. For example, `adb-1234567890123456.7.azuredatabricks.net` or `dbc-abcd1234-5678.cloud.databricks.com`
    * The cloud provider (AWS or Azure) and region where your Databricks workspace is deployed
    * Based on your cloud provider, we'll also need:
      * **For AWS** - The VPC endpoint service name, which will start with `com.amazonaws.vpce`
      * **For Azure** - The Databricks workspace resource ID, which should contain `/providers/Microsoft.Databricks/workspaces/`
    * Confirmation that your workspace is configured for PrivateLink access:
      * **For AWS** - Verify AWS PrivateLink is enabled for your workspace
      * **For Azure** - Verify your workspace is VNet-injected
  </Step>

  <Step title="Contact Omni support">
    Contact Omni support with the following information:

    * Your Databricks workspace URL
    * The connection details for the database, including:
      * The cloud provider (AWS or Azure)
      * The region of your Databricks workspace
      * The VPC endpoint service name (AWS) or Databricks workspace resource ID (Azure)
    * Technical contact details, in case of connection difficulties
  </Step>
</Steps>

## What's next?

After you contact Omni support with the above information, we'll create a private endpoint that connects to your Databricks workspace to support the connection.

Once this is complete, Omni support will add the new database connection to your Omni instance. The connection can then be used like any other database connection. You'll need to provide your [Databricks authentication credentials](/connect-data/setup/databricks#setup) (Personal Access Token or OAuth M2M) when setting up the connection in Omni.


# Pulling Databricks metrics and metrics views into Omni
Source: https://docs.omni.co/connect-data/databricks-unity-catalog-integration

Sync Databricks Unity Catalog metric views into Omni to query, visualize, and explore governed metrics.

If your team defines metrics in Databricks Unity Catalog, you can sync those definitions into Omni so that your metric views are available for querying, visualization, and AI-powered exploration — without duplicating any business logic.

## How it works

When you enable the integration and run a [schema refresh](/modeling/develop/schema-refreshes), Omni pulls the structure of your Databricks metric views into the semantic model. Here's what that looks like in practice:

* **Metric views become [topics](/modeling/topics).** Each metric view's dimensions and measures are imported as fields in Omni. Users can query them with the visual query builder or SQL and add results to dashboards without recreating any logic.

* **Comments become descriptions.** Any comments defined on fields in your Databricks metric views are mapped to field `descriptions` in the Omni semantic layer.

* **Lineage is preserved.** Fields managed by the Databricks semantic layer are tagged with a comment indicating that the definition is **managed by the Databricks semantic view**, so users can see where a field's logic comes from. In Omni, it will look similar to the following:

  ```yaml title="Example Databricks managed comment" theme={null}
  average_sale_price:
    # Measure is defined in the semantic view order_items_uc_metrics in the data warehouse
    sql: AVG(`sale_price`)
    description: this is the average of order sale price
  ```

* **Table and column tags become view and dimension tags.** An Omni [schema refresh](/modeling/develop/schema-refreshes) pulls table- and column-level Unity Catalog tags into the model as the [`tags`](/modeling/views/parameters/tags) parameter on views and [`tags`](/modeling/dimensions/parameters/tags) on dimensions.

  This doesn't apply to legacy `hive_metastore` catalogs. If the service principal lacks permission to read tags, the refresh still completes; the affected tables and columns simply have no tags.

* **Changes sync automatically.** When your team updates a metric view in Databricks — for example, adding an `average_sale_price` measure — the change appears in Omni after the next schema refresh.

* **AI features understand the context.** Because the synced metadata includes field definitions and descriptions, Omni's [AI features](/ai) can answer natural language questions about your Databricks metrics without users needing to write SQL.

### Limitations

* Measure-level filters are not currently supported as filtered measures
* Window measures in Databricks are not generated during sync
* Snowflake schema joins (nested dimensions) are not supported

## Requirements

To follow the steps in this guide, you'll need:

* An existing [Databricks connection](/connect-data/setup/databricks) configured in Omni
* **Connection Admin** or **Organization Admin** permissions in Omni
* Existing metric views defined in your Databricks Unity Catalog

## Setup

<Steps>
  <Step title="Enable the integration">
    1. In Omni, navigate to **Settings > Connections**.
    2. Click the Databricks connection you want to work with.
    3. In the **Settings** tab, check the **Enable DW metric view integration** box.
    4. Click **Update and Test connection**.
  </Step>

  <Step title="Refresh the model's schema">
    After you enable the integration, you'll need to trigger a [schema refresh](/modeling/develop/schema-refreshes) to pull the Databricks definitions into your Omni model.

    1. Click **Develop** in the [sidebar](/administration/settings/sidebar).
    2. If your organization has more than one model, click the Databricks-based model you want to work with to open the model IDE. If you have only one model, Omni opens it automatically.
    3. Click **Model > Refresh schema**.

    After the refresh completes, your Databricks metric views will appear as [topics](/modeling/topics) in the model. You can open the topic in the model IDE to view its structure or add additional Omni [topic parameters](/modeling/topics/parameters).
  </Step>
</Steps>

## Pushing Omni topics into Databricks

You can also go in the other direction — if you've built a [topic](/modeling/topics) in Omni that you want to formalize as a governed metric view in your Unity Catalog, you can use the [Omni Python SDK](https://github.com/exploreomni/omni-python-sdk) to generate the required Databricks DDL. You can then run the generated SQL in the Databricks console to create the metric view.

For a full walkthrough, refer to the [Push Omni topics to Databricks as metric views](/guides/modeling/push-to-databricks-metric-views) guide.


# Dynamic connection environments
Source: https://docs.omni.co/connect-data/dynamic-environments

Allow users to switch database environments while modeling or building analyses.

Using database environments, you can allow users to easily switch environments in an Omni branch or assign defaults by using [user attributes](/administration/users/attributes).

This can be useful for:

* **Development workflows** that test and validate changes against a non-production database
* **Embedded instances with multi-tenant data** where each customer must be restricted to only their own data

<Tip>
  For model-level tenant isolation — where each customer sees a tailored version of the same base model — see [shared extension models](/modeling/develop/shared-extensions).
</Tip>

<Note>
  To let users choose an environment themselves — rather than switching in a branch or being routed by a user attribute — see [user-selected environments](/connect-data/user-selected-environments).
</Note>

## Limitations

**The schemas in each database connection should be as close to identical as possible.**

When a connection is switched, the [schema model](/modeling/develop/model-generation) - meaning the available tables, views, and so on - is swapped, but the overarching model remains the same.

For example, if a model utilizes an object that exists in one connection but not in another, modeling errors will arise.

## Requirements

To follow the steps in this guide, you'll need **Omni Organization Admin** permissions.

## Setup

<Steps>
  <Step title="Create the primary connection">
    The first step is to create the primary connection which will be used to build the shared model. Refer to the [Database setup guides](/connect-data/setup) for instructions specific to different database types.<br /><br />When setting the connection's **Base role**, select the role you want all users who will interact with the connection and its environments to have. For example, if you select **Querier**, users will have **Querier** permissions on the primary connection and any associated environment.

    In this guide, the primary connection is a Snowflake database named **Snowflake (production)** that has an associated data model with the same name.
  </Step>

  <Step title="Create & configure the environments">
    1. Create another connection and set the base access role to **No Access.**
    2. Navigate back to the details page for the primary connection.
    3. Click the **Environments** tab.
    4. Click the **New Environment** button, which will open a dialog like the following:
       <img alt="Add database environment" />
    5. Select the secondary connection. In this example, the connection is named **Snowflake (dev)**.
    6. Click **Save**.

    At this point, you can use the connections in workbooks. Creating a new branch will display an option to change the connection environment from the primary connection (**Snowflake (production)**) to other environments (**Snowflake (dev)**):

    <img alt="Switch environment in branch mode" />

    While in a branch, the branch's environment selection is always in effect - user attribute-based assignment is never applied. If no environment is chosen, queries in the branch run against the primary connection. When multiple environment sources apply, refer to [How environment selection is resolved](/connect-data/user-selected-environments#how-environment-selection-is-resolved).

    <Warning>
      The branch environment switcher displays **every** configured environment, plus the primary connection, to any user who can access the primary connection and create a branch. Unlike [user-selected environments](/connect-data/user-selected-environments), visibility isn't restricted by user attributes, connection role, or environment access grants. Don't rely on dynamic environments to isolate sensitive data, such as PII, from users who are able to create branches.
    </Warning>

    If you want to dynamically assign an environment based on user attributes, continue to step 3.
  </Step>

  <Step title="Create a user attribute">
    <Note>
      This step is required only if you want to dynamically assign database environments.
    </Note>

    In this step, you'll create a user attribute that will be used to determine the connection a given user should be assigned to.

    1. Navigate to **Settings > Attributes**.
    2. Click **New Attribute**.
    3. Fill in the fields to create the attribute, including the **Default Value** field. This will set a default value for users that don't have a value directly assigned:
       <img alt="New user attribute" />
       In this example, users will be assigned to `prod` unless their `snowflake_env` attribute is specifically set to `dev`.
    4. When finished, click **Save**.
  </Step>

  <Step title="Configure the connection for dynamic environments">
    <Note>
      This step is required only if you want to dynamically assign database environments.
    </Note>

    The last step is to configure the primary connection to dynamically assign environments using the user attribute you created in step 3.

    1. Navigate to the **primary connection** you created in step 1 of this guide.
    2. Click the **Environments** tab.
    3. Toggle **Allow environments to be assigned dynamically** to **on**. Fill in the fields that display as follows:
       * **User attribute** - Enter the **reference name** of the user attribute you created in step 3. In this example, that would be `snowflake_env`.
       * **Values for the default connection** - Enter the value to be used for the default connection. In this example, that would be `prod`:
         <img alt="Enable dynamic environment" />
    4. Click **Update**.
    5. After clicking **Update**, a new field will display next to the connection in the **Environments** section. Use this field to assign a value to the connection, which will route users with this user attribute value to the connection.
       In this example, users with a `dev` value for the `snowflake_env` user attribute will be routed to the **Snowflake (dev)** connection:
       <img alt="Define connection variable" />
    6. Click **Update**.

    <Note>
      A user's attribute value must exactly match a value assigned to an environment to be routed to it. **If the user attribute allows multiple values, only the first value in the comma-separated list is used for environment routing.** For example, a user with the values `dev,staging,prod` will be routed to the environment assigned the `dev` value.
    </Note>
  </Step>
</Steps>

## What's next?

That's it! Users will now be able to use the same data model but change connections based on how their user attributes are defined.

If specific users need access to a connection other than the default, the next step is to assign them the appropriate user attribute value. Refer to the [User attributes guide](/administration/users/attributes) for more information.


# Connect data
Source: https://docs.omni.co/connect-data/index

Connect your data warehouse or database to Omni and configure connection settings 

Omni connects directly to your data warehouse or database. Once connected, you can configure settings like timezone conversion, schema restrictions, and secure network access.

## Getting started

<Columns>
  <Card title="Quick connect" icon="bolt" href="/connect-data/setup/quick-connect">
    Create connections by pasting a connection URI
  </Card>

  <Card title="Connect a database" icon="database" href="/connect-data/setup">
    Set up a connection to your data warehouse or database
  </Card>

  <Card title="Configure timezones" icon="clock" href="/connect-data/timezones">
    Control how time-based data is converted across timezones
  </Card>

  <Card title="Restrict schemas" icon="filter" href="/connect-data/schema-restriction">
    Limit which schemas are included in your model
  </Card>
</Columns>

## Connection methods

<Columns>
  <Card title="SSH tunnels" icon="lock" href="/connect-data/ssh-tunnels">
    Connect to databases in private networks using SSH
  </Card>

  <Card title="AWS PrivateLink" icon="aws" href="/connect-data/aws-privatelink">
    Connect to databases in private AWS networks. Supports cross-region access.
  </Card>

  <Card title="Redshift-managed VPC PrivateLink" icon="aws" href="/connect-data/redshift-privatelink">
    Connect to databases in a Redshift provisioned cluster. Doesn't support cross-region access.
  </Card>

  <Card title="Azure PrivateLink" icon="microsoft" href="/connect-data/azure-privatelink">
    Connect to databases in private Azure networks
  </Card>

  <Card title="Azure SQL PrivateLink" icon="microsoft" href="/connect-data/azure-sql-privatelink">
    Connect to Azure SQL Database via an Azure Private Link service
  </Card>

  <Card title="ClickHouse PrivateLink" icon="aws" href="/connect-data/clickhouse-privatelink">
    Connect to a ClickHouse Cloud service on AWS via PrivateLink
  </Card>

  <Card title="Snowflake PrivateLink" icon="snowflake" href="/connect-data/snowflake-privatelink">
    Connect to Snowflake via AWS or Azure PrivateLink
  </Card>
</Columns>

## Advanced configuration

<Columns>
  <Card title="Dynamic environments" icon="arrows-rotate" href="/connect-data/dynamic-environments">
    Switch between database environments for development or multi-tenancy
  </Card>

  <Card title="Offloaded schemas" icon="bolt" href="/connect-data/offloading-schemas">
    Defer loading of large or infrequently used schemas
  </Card>

  <Card title="Snowflake semantic views" icon="snowflake" href="/connect-data/snowflake-semantic-views">
    Import Snowflake semantic views as topics
  </Card>

  <Card title="User-selected environments" icon="user-gear" href="/connect-data/user-selected-environments">
    Let users pick which connection environment their queries run against
  </Card>
</Columns>

## Manage connections

<Columns>
  <Card title="Scope view names" icon="tag" href="/connect-data/view-name-generation">
    Control how view names are generated with catalog and schema prefixes
  </Card>

  <Card title="Delete connections" icon="trash" href="/connect-data/archive-connection">
    Archive and restore database connections
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/connect-data/troubleshooting">
    Resolve common connection issues
  </Card>
</Columns>


# Configuring native OAuth for Databricks databases
Source: https://docs.omni.co/connect-data/oauth/databricks

Configure native Databricks OAuth, allowing each Omni user to authenticate with their Databricks credentials when running queries.

## Requirements

To follow the steps in this guide, you'll need:

* **In Omni**:
  * **Organization Admin** permissions
  * **An existing Databricks connection.** Refer to [Connecting a Databricks database](/connect-data/setup/databricks) before continuing.
* **A Databricks service account with access to all schemas and tables you want to use in Omni**. This is required even when OAuth is enabled, because Omni uses the service account to build the model.

<Warning>
  Before continuing, review the [OAuth limitations](/connect-data/oauth#limitations).
</Warning>

## Setup

<Steps>
  <Step title="Create a Databricks OAuth integration">
    Create an OAuth integration in Databricks using `https://callbacks.omniapp.co/callback/oauth` as the **Redirect URI**, then retrieve the **Client ID** and **Client Secret**.

    Refer to [Databricks's OAuth documentation](https://docs.databricks.com/aws/en/integrations/enable-disable-oauth#enable-custom-oauth-applications-using-the-databricks-ui) for instructions.

    <Note>
      **For vanity-domain embeds**: If you're using OAuth with [vanity-domain embeds](/embed/customization/vanity-domains), also add `https://<your-vanity-domain>/oauth/callback` as a **Redirect URI**. Replace `<your-vanity-domain>` with your vanity domain (e.g., `omni.myapp.com`).
    </Note>
  </Step>

  <Step title="Configure the connection in Omni">
    <Note>
      You must still configure a service account on this connection. Omni uses the service account to build the model, which provides the foundation for all user queries.
    </Note>

    This guide assumes you have an existing Databricks connection in Omni. If you don't, refer to [Connecting a Databricks database](/connect-data/setup/databricks) for more information.

    1. In Omni, navigate to **Settings > Connections** and click on the Databricks connection you want to use.
    2. In the **Authentication Type** dropdown, select **OAuth User Authentication**.
    3. Enter the **OAuth Client ID** and **OAuth Client Secret** from the previous step into the respective fields.
    4. Save the connection settings.
  </Step>

  <Step title="Verify the user experience">
    After saving, each Omni user will be prompted to authenticate with Databricks the first time they run a query in a workbook or dashboard. This prompt reappears when their OAuth token expires.

    Once authenticated, Omni uses the user's database permissions in place of the service account for all queries that user runs.
  </Step>
</Steps>

## Next steps

To ensure database permissions align with what users see in Omni, we recommend implementing:

* [**Access grants**](/modeling/models/access-grants) to control which fields and tables are visible to each user in the model and field browser
* [**Content permissions**](/administration/users/permissions) to control which dashboards and documents users can access


# OAuth for database connections
Source: https://docs.omni.co/connect-data/oauth/index

Authenticate individual users against your database with OAuth, enforcing database-level permissions in Omni.

By default, Omni queries your database using a shared service account. With OAuth, each user authenticates with their own credentials, and Omni enforces that user's database-level permissions when they run queries. This lets you manage data access in your database and have it filter down to Omni automatically.

## How it works

When OAuth is enabled on a connection, Omni prompts each user to authenticate with the database the first time they run a query. After authenticating, the user's own database permissions apply to every query they run — rather than the permissions of the shared service account.

A service account is still required on the connection. Omni uses it to build the model, which provides the foundation for all user queries.

## Getting started

Select your database to get started:

<Columns>
  <Card title="Databricks" icon="database" href="/connect-data/oauth/databricks">
    Configure OAuth for Databricks connections.
  </Card>

  <Card title="Snowflake" icon="snowflake" href="/connect-data/oauth/snowflake">
    Configure OAuth for Snowflake connections, including native and External OAuth options.
  </Card>
</Columns>

## Limitations

Before enabling OAuth, review the following limitations.

| Area                   | Details                                                                                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model and IDE**      | Omni models are built using the service account. All users will see the same tables and fields in the model unless you restrict visibility with [access grants](/modeling/models/access-grants).            |
| **Field picker**       | All fields and tables will be visible in the workbook's field browser unless explicitly restricted with access grants.                                                                                      |
| **Scheduling**         | Schedules run as the schedule creator and cannot be personalized with user attributes. Schedules may also fail when the creator's OAuth token expires — the creator must re-authenticate to resolve this.   |
| **Caching**            | Caches are not shared across users, which results in a lower cache hit rate and higher data warehouse costs. The same applies to cubes and extracts.                                                        |
| **Content visibility** | Users may be able to open dashboards that reference data they don't have database permissions to query, which can result in permission errors.                                                              |
| **Embedding**          | Per-user OAuth is only supported with [vanity domain embeds](/embed/customization/vanity-domains). Default embed domains (`embed-*`) cannot support per-user OAuth due to cookie partitioning restrictions. |

<Note>
  Some databases may have additional limitations. Check the setup guide for your database for details.
</Note>

## Related

* [**Access grants**](/modeling/models/access-grants) — Control which fields and tables are visible to each user in the model and field browser
* [**Content permissions**](/administration/users/permissions) — Control which dashboards and documents users can access


# Configuring Snowflake External OAuth with Microsoft Entra ID
Source: https://docs.omni.co/connect-data/oauth/snowflake/external-entra

Configure Snowflake External OAuth to authenticate users through Microsoft Entra ID (Azure AD).

<Note>
  For authenticating Snowflake users directly through Snowflake, see [Snowflake native OAuth](/connect-data/oauth/snowflake/native).
</Note>

[Snowflake External OAuth](https://docs.snowflake.com/en/user-guide/oauth-ext-overview) allows each Omni user to authenticate to Snowflake using their own identity through an external identity provider instead of Snowflake's built-in OAuth server. Each user's queries run under their own Snowflake role and session, so Snowflake's row-level security and role restrictions apply automatically.

## Requirements

To follow the steps in this guide, you'll need:

* **Permissions in Microsoft Entra ID** that allow you to register applications and configure OAuth settings
* **In Omni**:
  * **Organization Admin** permissions
  * **An existing Snowflake connection.** Refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) before continuing.
* **In Snowflake**:
  * **`ACCOUNTADMIN` or `SECURITYADMIN`** privileges to create a security integration
  * **A service account** with access to all schemas and tables you want to use in Omni. This is required even when OAuth is enabled, because Omni uses the service account to build the model.
  * **To assign regular user roles to your Snowflake users.** Snowflake blocks `ACCOUNTADMIN`, `ORGADMIN`, and `SECURITYADMIN` from external OAuth authentication by default.

<Warning>
  Before continuing, review the [OAuth limitations](/connect-data/oauth#limitations).
</Warning>

## Setup

<Steps>
  <Step title="Register an Entra OAuth resource app">
    <Steps>
      <Step title="Create the app">
        1. In the Azure portal, navigate to **Microsoft Entra ID > App registrations**.
        2. Click **New registration**.
        3. Enter a name (e.g., *Omni Snowflake OAuth Resource*).
        4. Set **Supported account types** to **Single tenant**.
        5. Click **Register**.
      </Step>

      <Step title="Set the Application ID URI">
        1. Navigate to **Expose an API**.
        2. Click the link next the **Application ID URI** to add the Application ID URI. This value must be unique within your directory (e.g., `https://<your-domain>/<app-guid>`).

        Save this value — you'll need it as the **Audience** in both Snowflake and Omni.
      </Step>

      <Step title="Configure app permissions">
        1. Click **Add a scope**.
        2. Select who can consent.
        3. In the **Value** field, enter `session:role-any`. This allows the token to work with any role the user holds in Snowflake.
        4. **Optional**. Add a description.
        5. Save the role.
      </Step>
    </Steps>
  </Step>

  <Step title="Register an Entra OAuth client app">
    <Steps>
      <Step title="Create the app">
        1. In the Azure portal, navigate to **Microsoft Entra ID > App registrations**.
        2. Click **New registration**.
        3. Enter a name (e.g., *Omni Snowflake OAuth Client*).
        4. Set **Supported account types** to **Single tenant**.
        5. Click **Register**.
      </Step>

      <Step title="Retrieve your OAuth information">
        1. On the page that displays after registering the app, copy the **Application (client) ID**. This is your **OAuth Client ID** for Omni.
        2. Navigate to **Certificates & secrets > New client secret**.
        3. Copy the secret value. This is your **OAuth Client Secret** for Omni.
      </Step>

      <Step title="Configure app permissions">
        1. Navigate to **Manage API permissions > Add a permission > My APIs**.
        2. Select the Omni resource app you created in the previous section.
        3. Select the **Delegated Permissions** box.
        4. Confirm that the scope permissions (`session:role-any`) for the resource app are present and correct.
        5. Click **Add permissions**.
        6. Click **Grant admin consent** to grant the permissions to the client.
        7. Click **Yes**.
      </Step>

      <Step title="Add the redirect URI">
        1. Navigate to **Manage > Authentication**.
        2. Add a **web** platform.
        3. Add the following **Redirect URI**, replacing `<your-omni-domain>` with the name of your Omni instance:

           ```text theme={null}
           https://callbacks.<your-omni-domain>/callback/oauth
           ```

           **If you're using OAuth with [vanity-domain embeds](/embed/customization/vanity-domains)**, also add `https://<your-vanity-domain>/callback/oauth` as a redirect URI. Replace `<your-vanity-domain>` with your vanity domain (e.g., `omni.myapp.com`).
      </Step>
    </Steps>
  </Step>

  <Step title="Collect Entra ID metadata">
    In your resource app registration, go to the **Endpoints** tab and collect the following values:

    | Value                      | Where to find it                                                                                                                          |
    | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | **Authorization endpoint** | **OAuth 2.0 authorization endpoint (v2)**                                                                                                 |
    | **Token endpoint**         | **OAuth 2.0 token endpoint (v2)**                                                                                                         |
    | **JWK Set URI**            | Open the **OpenID Connect metadata document** URL in a browser and find the `jwks_uri` value                                              |
    | **Issuer**                 | Open the **Federation metadata document** URL in a browser and find the `entityID` value (format: `https://sts.windows.net/<tenant-id>/`) |
  </Step>

  <Step title="Create a Snowflake security integration">
    Run this in Snowflake as `ACCOUNTADMIN` or `SECURITYADMIN`, substituting the values from the previous step.

    ```sql theme={null}
    CREATE SECURITY INTEGRATION omni_external_oauth_azure
      TYPE = EXTERNAL_OAUTH
      ENABLED = TRUE
      EXTERNAL_OAUTH_TYPE = AZURE
      EXTERNAL_OAUTH_ISSUER = '<issuer from Federation metadata>'
      EXTERNAL_OAUTH_JWS_KEYS_URL = '<jwks_uri from OpenID metadata>'
      EXTERNAL_OAUTH_AUDIENCE_LIST = ('<Application ID URI from resource app>')
      EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'upn'                    
      EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'login_name'
      EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';
    ```

    When filling in the placeholder values, keep in mind that:

    * The `EXTERNAL_OAUTH_ISSUER` value is case-sensitive and must match exactly. Include the trailing slash (`https://sts.windows.net/<tenant-id>/`).
    * The `EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM: upn` (User Principal Name) claim maps Entra ID users to Snowflake. Each user's UPN in Entra ID must exactly match the `LOGIN_NAME` on their Snowflake user record. Verify this before going live.
  </Step>

  <Step title="Configure the connection in Omni">
    <Note>
      You must still configure a service account on this connection. Omni uses the service account to build the model, which provides the foundation for all user queries.
    </Note>

    This guide assumes you have an existing Snowflake connection in Omni. If you don't, refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) for more information.

    1. In Omni, navigate to **Settings > Connections** and click on the Snowflake connection you want to use.
    2. Under **Authentication type**, select **External OAuth User Authentication**.
    3. Fill in the fields as follows:
       * **Authorization URL** - Enter the **Authorization endpoint** from [Entra ID](#collect-metadata)
       * **Token URL** - Enter the **Token endpoint** from [Entra ID](#collect-metadata)
       * **OAuth Client ID** - Enter the **Application (client) ID** from the [client app](#create-client-app)
       * **OAuth Client Secret** - Enter the **Client secret** from the [client app](#create-client-app)
       * **Audience** - Enter the **Application ID URI** from the [resource app](#create-resource-app)
       * **Warehouse** - **Optional**: Leave blank to use each user's `DEFAULT_WAREHOUSE` from Snowflake. This enables per-user warehouse routing for organizations using role-to-warehouse mappings in Snowflake for cost attribution.

         **Users must have an assigned default warehouse to use this feature.** Otherwise, users without a default warehouse will receive a `No active warehouse` error when they attempt to run queries in Omni.
    4. Save the connection.
  </Step>

  <Step title="Verify the user experience">
    After saving, each Omni user who wants to query this connection will need to authorize once through the OAuth flow. They'll be redirected to Microsoft to sign in, then redirected back to Omni. After that, Omni will automatically refresh their token in the background.

    <Tip>
      **Running into issues?** See the [Troubleshooting Snowflake OAuth](/connect-data/oauth/snowflake/troubleshooting) for help with diagnosing and resolving common Snowflake OAuth problems.
    </Tip>
  </Step>
</Steps>

## Next steps

To ensure database permissions align with what users see in Omni, we recommend implementing:

* [**Access grants**](/modeling/models/access-grants) to control which fields and tables are visible to each user in the model and field browser
* [**Content permissions**](/administration/users/permissions) to control which dashboards and documents users can access


# Configuring Snowflake External OAuth with Okta
Source: https://docs.omni.co/connect-data/oauth/snowflake/external-okta

Configure Snowflake External OAuth to authenticate users through Okta.

<Note>
  For authenticating Snowflake users directly through Snowflake, see [Snowflake native OAuth](/connect-data/oauth/snowflake/native).
</Note>

[Snowflake External OAuth](https://docs.snowflake.com/en/user-guide/oauth-ext-overview) allows each Omni user to authenticate to Snowflake using their own identity through an external identity provider instead of Snowflake's built-in OAuth server. Each user's queries run under their own Snowflake role and session, so Snowflake's row-level security and role restrictions apply automatically.

**Looking for another IdP?** Guides for Microsoft Entra ID (Azure AD) and Ping Identity are coming soon.

## Requirements

To follow the steps in this guide, you'll need:

* **Permissions in Okta** that allow you to create an app integration and authorization server
* **In Omni**:
  * **Organization Admin** permissions
  * **An existing Snowflake connection.** Refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) before continuing.
* **In Snowflake**:
  * **`ACCOUNTADMIN` or `SECURITYADMIN`** privileges to create a security integration
  * **A service account** with access to all schemas and tables you want to use in Omni. This is required even when OAuth is enabled, because Omni uses the service account to build the model.
  * **To assign regular user roles to your Snowflake users.** Snowflake blocks `ACCOUNTADMIN`, `ORGADMIN`, and `SECURITYADMIN` from external OAuth authentication by default.

<Warning>
  Before continuing, review the [OAuth limitations](/connect-data/oauth#limitations).
</Warning>

## Setup

<Steps>
  <Step title="Create an Okta application">
    1. In the Okta admin console, navigate to **Applications > Applications**.
    2. Click **Create App Integration**.
    3. Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type.
    4. Give it a descriptive name (e.g., *Omni Snowflake External OAuth*).
    5. Under **Grant type**, enable **Refresh Token** in addition to **Authorization Code**.
    6. In **Sign-in redirect URIs**, add the Omni callback: `https://callbacks.<your-omni-domain>/callback/oauth`
       <Note>
         **For vanity-domain embeds**: If you're using OAuth with [vanity-domain embeds](/embed/customization/vanity-domains), also add `https://<your-vanity-domain>/callback/oauth` to **Sign-in redirect URIs**. Replace `<your-vanity-domain>` with your vanity domain (e.g., `omni.myapp.com`).
       </Note>
    7. Save the app.
    8. Copy the **Client ID** and **Client Secret** — you'll need these in Omni.
  </Step>

  <Step title="Create an Okta authorization server">
    1. In Okta, navigate to **Security > API** and click **Add Authorization Server**.
    2. Set the **Audience** to your Snowflake account URL (e.g., `https://<account>.snowflakecomputing.com`).
    3. Open the server's **Metadata URI** and note the following values — you'll need them for both Snowflake and Omni:
       * **Issuer** (`issuer`)
       * **Authorization endpoint** (`authorization_endpoint`)
       * **Token endpoint** (`token_endpoint`)
       * **JWK Set URI** (`jwks_uri`)
    4. Add a **Scope** named `SESSION:ROLE-ANY`. This allows the token to work with any role the user holds in Snowflake.
    5. Under **Access Policies**, create a policy that assigns your app to this authorization server.
    6. Add a rule with appropriate token lifetimes — Okta's defaults (1-hour access token, 90-day refresh token) are reasonable starting points.
  </Step>

  <Step title="Create a Snowflake security integration">
    Run this in Snowflake as `ACCOUNTADMIN` or `SECURITYADMIN`, substituting values from your Okta metadata URI.

    <Note>
      **User mapping**: The `email_address` value is used to map Okta users to Snowflake. Each user's Okta email must exactly match the `LOGIN_NAME` or `EMAIL` on their Snowflake user record. Verify this before going live.
    </Note>

    ```sql theme={null}
    CREATE SECURITY INTEGRATION omni_external_oauth
      TYPE = EXTERNAL_OAUTH
      ENABLED = TRUE
      EXTERNAL_OAUTH_TYPE = OKTA
      EXTERNAL_OAUTH_ISSUER = '<issuer from Okta metadata>'
      EXTERNAL_OAUTH_JWS_KEYS_URL = '<jwks_uri from Okta metadata>'
      EXTERNAL_OAUTH_AUDIENCE_LIST = ('<your Snowflake account URL>')
      EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
      EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'email_address'
      EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';
    ```
  </Step>

  <Step title="Configure the connection in Omni">
    <Note>
      You must still configure a service account on this connection. Omni uses the service account to build the model, which provides the foundation for all user queries.
    </Note>

    This guide assumes you have an existing Snowflake connection in Omni. If you don't, refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) for more information.

    1. In Omni, navigate to **Settings > Connections** and click on the Snowflake connection you want to use.
    2. Under **Authentication type**, select **External OAuth User Authentication**.
    3. Fill in the fields as follows:

       * **Authorization URL** - Enter the `authorization_endpoint` from Okta metadata
       * **Token URL** - Enter the `token_endpoint` from Okta metadata
       * **OAuth Client ID** - Enter the **Client ID** from your Okta app
       * **OAuth Client Secret** - Enter the **Client Secret** from your Okta app
       * **Audience** - Leave blank
       * **Warehouse** - **Optional**: Leave blank to use each user's `DEFAULT_WAREHOUSE` from Snowflake. This enables per-user warehouse routing for organizations using role-to-warehouse mappings in Snowflake for cost attribution.

         **Users must have an assigned default warehouse to use this feature.** Otherwise, users without a default warehouse will receive a `No active warehouse` error when they attempt to run queries in Omni.
    4. Save the connection.
  </Step>

  <Step title="Verify the user experience">
    After saving, each Omni user who wants to query this connection will need to authorize once through the OAuth flow. They'll be redirected to Okta to sign in, then redirected back to Omni. After that, Omni will automatically refresh their token in the background.

    <Tip>
      **Running into issues?** See the [Troubleshooting Snowflake OAuth](/connect-data/oauth/snowflake/troubleshooting) for help with diagnosing and resolving common Snowflake OAuth problems.
    </Tip>
  </Step>
</Steps>

## Next steps

To ensure database permissions align with what users see in Omni, we recommend implementing:

* [**Access grants**](/modeling/models/access-grants) to control which fields and tables are visible to each user in the model and field browser
* [**Content permissions**](/administration/users/permissions) to control which dashboards and documents users can access


# OAuth for Snowflake connections
Source: https://docs.omni.co/connect-data/oauth/snowflake/index

Authenticate individual users against your Snowflake database with OAuth, enforcing database-level permissions in Omni.

By default, Omni queries your Snowflake database using a shared service account. With OAuth, each user authenticates with their own credentials, and Omni enforces that user's Snowflake database-level permissions when they run queries. This lets you manage data access in Snowflake and have it filter down to Omni automatically.

## OAuth types

Omni supports two OAuth modes for Snowflake. Both enforce per-user database permissions, but they differ in how users authenticate.

<Warning>
  Before configuring OAuth, review the [limitations](/connect-data/oauth#limitations) that apply to both types.
</Warning>

### Native OAuth

With native OAuth, users authenticate directly with Snowflake's built-in OAuth server. When a user runs a query for the first time, they're prompted to sign in with their Snowflake credentials.

This is the simpler option — it doesn't require an external identity provider and can be configured entirely between Omni and Snowflake.

<Card title="Snowflake native OAuth" icon="snowflake" href="/connect-data/oauth/snowflake/native">
  Set up native OAuth for Snowflake
</Card>

### External OAuth

With External OAuth, users authenticate through an external identity provider (IdP) such as Okta, Entra ID (Azure AD), or Ping Identity. The IdP issues a token that Snowflake trusts, so users sign in with their existing corporate identity rather than separate database credentials.

This option is more complex to configure — it involves setup in the IdP, Snowflake, and Omni — but it centralizes authentication through the identity provider your organization already uses.

<Card title="Snowflake + Okta External OAuth" icon="snowflake" href="/connect-data/oauth/snowflake/external-okta">
  Set up federated OAuth for Snowflake connections using Okta
</Card>

<Card title="Snowflake + Microsoft Entra ID External OAuth" icon="snowflake" href="/connect-data/oauth/snowflake/external-entra">
  Set up federated OAuth for Snowflake connections using Microsoft Entra ID (Azure AD)
</Card>

**Looking for another IdP?** A guide for Ping Identity is coming soon.

## Warehouse configuration

Omni's Snowflake OAuth integration supports per-user warehouse routing through a user's assign `DEFAULT_WAREHOUSE`. This is useful for organizations that manage role-to-warehouse mappings in Snowflake for per-user or per-team cost attribution. Instead of pinning all users to a single warehouse in Omni, each user's queries route to their assigned warehouse based on their Snowflake configuration.

Before implementing, note that:

* **Your users must have an assigned `DEFAULT_WAREHOUSE` in Snowflake to use this feature.** Otherwise they'll receive `No active warehouse` errors when they try to run queries in Omni.
* **Model-level [`compute_routing`](/modeling/models/compute-routing) and [`warehouse_override`](/modeling/models/warehouse-override) settings take precedence over user default warehouses.**

See the OAuth setup guides for more information.

## Limitations

Before enabling OAuth for Snowflake, review the [Limitations for OAuth](/connect-data/oauth#limitations). **These limitations apply to both Native and External OAuth**.

## Related

* [Troubleshooting Snowflake OAuth](/connect-data/oauth/snowflake/troubleshooting) - Diagnose and resolve common issues with Omni's Snowflake OAuth integration
* [Access grants](/modeling/models/access-grants) — Control which fields and tables are visible to each user in the model and field browser
* [Content permissions](/administration/users/permissions) — Control which dashboards and documents users can access


# Configuring native OAuth for Snowflake databases
Source: https://docs.omni.co/connect-data/oauth/snowflake/native

Configure native Snowflake OAuth, allowing each Omni user to authenticate with their Snowflake credentials when running queries.

<Note>
  For authenticating Snowflake users with Okta, see [Snowflake + Okta External OAuth](/connect-data/oauth/snowflake/external-okta).
</Note>

## Requirements

To follow the steps in this guide, you'll need:

* **In Omni**:
  * **Organization Admin** permissions
  * **An existing Snowflake connection.** Refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) before continuing.
* **A Snowflake service account with access to all schemas and tables you want to use in Omni**. This is required even when OAuth is enabled, because Omni uses the service account to build the model.

<Warning>
  Before continuing, review the [OAuth limitations](/connect-data/oauth#limitations).
</Warning>

## Setup

<Steps>
  <Step title="Create a Snowflake OAuth integration">
    Create an OAuth integration in Snowflake using `https://callbacks.omniapp.co/callback/oauth` as the `OAUTH_REDIRECT_URI`, then retrieve the **Client ID** and **Client Secret**. Refer to [Snowflake's OAuth documentation](https://docs.snowflake.com/en/user-guide/oauth-intro) for instructions.

    <Note>
      **Vanity-domain embed users**: If you're using OAuth with [vanity-domain embeds](/embed/customization/vanity-domains), you'll also need to register your vanity domain's OAuth callback URL. Run the following command in Snowflake to add the vanity callback URL to your existing OAuth integration:

      ```sql wrap theme={null}
      ALTER SECURITY INTEGRATION <your-integration-name>
        SET OAUTH_REDIRECT_URI = 'https://callbacks.omniapp.co/callback/oauth,https://<your-vanity-domain>/callback/oauth';
      ```

      Replace `<your-integration-name>` with your integration's name and `<your-vanity-domain>` with your vanity domain (e.g., `omni.myapp.com`).
    </Note>
  </Step>

  <Step title="Configure the connection in Omni">
    <Note>
      You must still configure a service account on this connection. Omni uses the service account to build the model, which provides the foundation for all user queries.
    </Note>

    This guide assumes you have an existing Snowflake connection in Omni. If you don't, refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) for more information.

    1. In Omni, navigate to **Settings > Connections** and click on the Snowflake connection you want to use.
    2. Fill in the fields as follows:
       * **Authentication Type** - Select **OAuth User Authentication**
       * **OAuth Client ID** - Enter the **Client ID** from the previous step
       * **OAuth Client Secret** - Enter the **Client secret** from the previous step
       * **Warehouse** - **Optional**: Leave blank to use each user's `DEFAULT_WAREHOUSE` from Snowflake. This enables per-user warehouse routing for organizations using role-to-warehouse mappings in Snowflake for cost attribution.

         **Users must have an assigned default warehouse to use this feature.** Otherwise, users without a default warehouse will receive a `No active warehouse` error when they attempt to run queries in Omni.
    3. Save the connection settings.
  </Step>

  <Step title="Verify the user experience">
    After saving, each Omni user will be prompted to authenticate with Snowflake the first time they run a query in a workbook or dashboard. This prompt reappears when their OAuth token expires.

    Once authenticated, Omni uses the user's database permissions in place of the service account for all queries that user runs.

    <Tip>
      **Running into issues?** See the [Troubleshooting Snowflake OAuth](/connect-data/oauth/snowflake/troubleshooting) for help with diagnosing and resolving common Snowflake OAuth problems.
    </Tip>
  </Step>
</Steps>

## Next steps

To ensure database permissions align with what users see in Omni, we recommend implementing:

* [**Access grants**](/modeling/models/access-grants) to control which fields and tables are visible to each user in the model and field browser
* [**Content permissions**](/administration/users/permissions) to control which dashboards and documents users can access


# Troubleshooting Snowflake OAuth
Source: https://docs.omni.co/connect-data/oauth/snowflake/troubleshooting

Diagnose and resolve common issues with Omni's Snowflake OAuth integration.

Use this guide to diagnose common issues with Omni's Snowflake OAuth integration. Each scenario describes what you're seeing, why it happens, and how to fix it.

## Users can't authenticate with Entra ID or Okta

<Note>
  This section is applicable if you're using [Snowflake External OAuth](https://docs.snowflake.com/en/user-guide/oauth-ext-overview).
</Note>

<Steps>
  <Step title="What you're seeing" icon="eye">
    Users are unable to use Entra ID or Okta to authenticate to Snowflake.
  </Step>

  <Step title="Why it happens" icon="question">
    Authentication failures are commonly caused by mismatches between the user identifiers in the Identity Provider (IdP) and Snowflake. As identifiers are case-sensitive, a mismatch could be caused by a difference in casing. For example, `blobby` versus `Blobby`.
  </Step>

  <Step title="How to fix it" icon="hammer">
    Verify that each user's IdP identifier exactly matches the required value in Snowflake, including casing.

    | Your IdP | User's IdP identifier     | Snowflake value         |
    | -------- | ------------------------- | ----------------------- |
    | Entra ID | UPN (User Principal Name) | `LOGIN_NAME`            |
    | Okta     | Email                     | `LOGIN_NAME` or `EMAIL` |
  </Step>
</Steps>

## Frequent re-authentication prompts

<Steps>
  <Step title="What you're seeing" icon="eye">
    Users authenticated to Snowflake using OAuth frequently receive prompts to re-authenticate.
  </Step>

  <Step title="Why it happens" icon="question">
    This issue is typically caused by insufficient refresh token lifetimes or an incorrectly configured Snowflake security integration.
  </Step>

  <Step title="How to fix it" icon="hammer">
    Verify that:

    * The refresh token lifetime in your IdP is sufficient. Omni recommends 90 days.
    * The Snowflake security integration is correctly configured with the IdP's token endpoint. See the OAuth setup guide for your IdP ([Entra ID](/connect-data/oauth/snowflake/external-entra#create-snowflake-integration), [Okta](/connect-data/oauth/snowflake/external-okta#create-a-snowflake-security-integration)) for more information.
  </Step>
</Steps>

## 'No default warehouse' errors when querying in Omni

<Steps>
  <Step title="What you're seeing" icon="eye">
    Users receive a `No active warehouse` error when they try to run queries against Snowflake in Omni.
  </Step>

  <Step title="Why it happens" icon="question">
    This occurs when both of the following are true:

    1. The **Warehouse** field on the Omni Snowflake connection is left blank
    2. An Omni user who authenticated to Snowflake through OAuth doesn't have an assigned `DEFAULT_WAREHOUSE`

    When the **Warehouse** field is left blank on a Snowflake connection, Omni uses each user's `DEFAULT_WAREHOUSE` from Snowflake. If the user doesn't have an assigned `DEFAULT_WAREHOUSE`, Snowflake can't route the query to the correct warehouse.
  </Step>

  <Step title="How to fix it" icon="hammer">
    In Snowflake, verify that all users who need to query the database from Omni have an assigned `DEFAULT_WAREHOUSE`. Users with the required Snowflake permissions can run [`SHOW USERS`](https://docs.snowflake.com/en/sql-reference/sql/show-users) to check if a user has a `DEFAULT_WAREHOUSE` configured:

    ```sql theme={null}
    show users;
    ```

    The output of `SHOW USERS` will include a `default_warehouse` column. If this column is blank, you'll need to use `ALTER USER` to assign a warehouse:

    ```sql theme={null}
    alter user <user_name> set default_warehouse = '<warehouse>';
    ```

    Alternatively, if you're unable or don't want to assign a `DEFAULT_WAREHOUSE` to users, specify a **Warehouse** on the Snowflake connection in Omni.
  </Step>
</Steps>


# Offloading schemas
Source: https://docs.omni.co/connect-data/offloading-schemas

Improve model performance by deferring the load of large or infrequently used schemas – like dbt virtual schemas – until they’re needed.

When your data model includes many schemas – or a few very large ones – it can slow down performance. Offloading, or *lazy loading*, helps by deferring the loading of schema metadata until you need it.

This approach is especially useful when working with dbt virtual schemas or other large, infrequently accessed schemas. Offloading keeps your model lean and responsive while still allowing full access to schema metadata on demand.

## Requirements

**Connection Admin** permissions are required to modify connection settings.

## Specifying offloaded schemas

<Steps>
  <Step title="Open the connection details">
    1. Navigate to **Settings > Connections**.
    2. Click a connection.
    3. Locate the **Offloaded schemas** setting in the connection settings.
  </Step>

  <Step title="Add the schemas">
    In the **Offloaded schemas** setting, use a **comma-separated list** to add the names of the schemas you want to offload. The values in this field:

    * **Can use wildcard syntax**, for example `dbt_*`.
    * **Are case-sensitive**, meaning the schema name you enter must exactly match the name of the schema in the database. For example, `blob_schema` must match a `blob_schema` in the database.
    * **Can use exclusion syntax** by prefixing an entry with `-` to exclude it from the offloaded list, for example `dbt_*, -dbt_core`. A list containing only exclusion entries offloads everything except those listed.

    <Tip>
      If the schema is in a database other than the connection default, you need to:

      1. **Include the database in the connection's Other databases setting**. This name varies by database type. For example, this setting is named **Include Other Data Catalogs** for an Amazon Athena connection.
      2. **Specify the database when adding the schema to Offloaded Schemas**. For example, `NON_DEFAULT_DATABASE.OFFLOADED_SCHEMA`.
    </Tip>
  </Step>

  <Step title="Save & apply the changes">
    1. When finished, click **Update and Test connection**.
    2. Trigger a [**schema refresh**](/modeling/develop/schema-refreshes) to apply the changes to your Omni model.
  </Step>

  <Step title="Confirm the changes">
    While the changes may not be visible in the connection's shared models, you can verify that the application was successful using the model IDE:

    1. Click **Develop** in the [sidebar](/administration/settings/sidebar).
    2. If your organization has more than one model, click one of the connection's models to open it in the model IDE. If you have only one model, Omni opens it automatically.
    3. In the **Shared** layer of the model, click the link next to **Parent** at the bottom of the page. This opens the schema model.

       <img alt="Highlighted Parent section in the model IDE" />
    4. In this view, change the **Browse mode** to **Model** by using the dropdown near the top left corner of the page:

       <img alt="Browse selector in the model IDE, set to Model" />
    5. The offloaded schemas should **not** be visible in the **Schemas** section.
  </Step>
</Steps>

## Accessing offloaded schemas in workbooks

Offloaded schemas will display in the UI, but the tables and views they contain will display only when requested. Click an offloaded schema in a workbook or the model IDE and Omni will load its contents:

<Frame>
  <img alt="Alt text" />
</Frame>


# Connect to Redshift with AWS PrivateLink
Source: https://docs.omni.co/connect-data/redshift-privatelink

Connect to Redshift Provisioned clusters or Redshift Serverless workgroups in AWS using PrivateLink

<Note>
  This feature is in beta and is subject to change.
</Note>

Omni can connect to your Redshift provisioned cluster or Redshift Serverless workgroup in Amazon Web Services (AWS) via PrivateLink. In this configuration, Omni establishes an encrypted connection from our network to your Redshift environment over a private network using a Redshift-managed VPC endpoint.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions in Omni
* **In AWS**:
  * A Redshift **provisioned** cluster or a Redshift **Serverless** workgroup
  * A Redshift cluster or workgroup **in the same AWS region** as your Omni instance
  * Permissions that allow you to authorize endpoint access from Omni for your Redshift cluster or workgroup

## Limitations

Redshift-managed VPC endpoints must be in the same region as the cluster or workgroup (your Omni instance):

| Region    | Primary          |
| --------- | ---------------- |
| EastUsa   | `us-east-1`      |
| Ireland   | `eu-west-1`      |
| Australia | `ap-southeast-2` |
| Canada    | `ca-central-1`   |
| India     | `ap-south-1`     |

For cross-region access, you'll need to use a traditional AWS PrivateLink setup with a network load balancer instead. See [AWS PrivateLink](/connect-data/aws-privatelink) for more information.

## Setup

Choose the tab that matches your Redshift deployment type.

<Tabs>
  <Tab title="Redshift Provisioned">
    <Steps>
      <Step title="Authorize Omni's AWS account">
        Before Omni can create a private connection to your Redshift cluster, you need to authorize Omni's AWS account to create a managed VPC endpoint to your cluster.

        Run the following command in your AWS environment, replacing `<your-cluster-identifier>` with the identifier of your cluster:

        ```bash highlight={2} theme={null}
        aws redshift authorize-endpoint-access \
          --cluster-identifier <your-cluster-identifier> \
          --account 767117061426
        ```
      </Step>

      <Step title="Contact Omni support">
        Contact Omni support with the following information:

        * Your AWS account ID (the 12-digit account ID that owns the Redshift cluster)
        * The Redshift cluster identifier
        * The AWS region where the cluster is deployed
        * Technical contact details, in case of connection difficulties
      </Step>
    </Steps>
  </Tab>

  <Tab title="Redshift Serverless">
    <Steps>
      <Step title="Add a resource policy to your workgroup">
        Before Omni can create a private connection to your Redshift Serverless workgroup, you need to add a resource policy that grants Omni's AWS account permission to create a managed VPC endpoint to your workgroup.

        Run the following command in your AWS environment, replacing `<your-workgroup-arn>` with the ARN of your Redshift Serverless workgroup:

        ```bash wrap highlight={2} theme={null}
        aws redshift-serverless put-resource-policy \
          --resource-arn <your-workgroup-arn> \
          --policy '{
            "Version": "2012-10-17",
            "Statement": [{
              "Sid": "CrossAccountAccess",
              "Effect": "Allow",
              "Principal": {
                "AWS": "767117061426"
              },
              "Action": [
                "redshift-serverless:CreateEndpointAccess",
                "redshift-serverless:UpdateEndpointAccess",
                "redshift-serverless:DeleteEndpointAccess",
                "redshift-serverless:GetEndpointAccess"
              ],
              "Condition": {
                "ArnLike": {
                  "redshift-serverless:AuthorizedVpc": "arn:aws:ec2:*:767117061426:vpc/*"
                }
              }
            }]
          }'
        ```

        <Tip>
          You can find your workgroup ARN in the AWS console under **Amazon Redshift Serverless > Workgroups**, or by running:

          ```bash theme={null}
          aws redshift-serverless get-workgroup --workgroup-name <your-workgroup-name> \
            --query 'workgroup.workgroupArn' --output text
          ```
        </Tip>
      </Step>

      <Step title="Contact Omni support">
        Contact Omni support with the following information:

        * Your AWS account ID (the 12-digit account ID that owns the Redshift Serverless workgroup)
        * The Redshift Serverless workgroup name
        * The AWS region where the workgroup is deployed
        * Technical contact details, in case of connection difficulties
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next steps

After you contact Omni support with the above information, we'll create a Redshift-managed VPC endpoint that connects to your cluster or workgroup to support the connection.

Once this is complete, Omni support will add the new database connection to your Omni instance. The connection can then be used like any other database connection. You'll need to provide your [Redshift authentication credentials](/connect-data/setup/redshift#setup) (username and password, or workgroup credentials for Serverless) when setting up the connection in Omni.


# Restricting connection schemas
Source: https://docs.omni.co/connect-data/schema-restriction

Limit which schemas are included in your Omni model to improve performance and control model scope.

<Warning>
  This guide applies to the **Included schemas** field in the connection settings page. For the modeling parameter, which restricts the schemas that are accessible in workbooks, refer to the [`included_schemas`](/modeling/models/included-schemas) reference.
</Warning>

When a database connection includes many schemas, your Omni model can become larger than necessary. Restricting which schemas are included helps improve performance, reduces clutter, and ensures only relevant data is modeled.

## Requirements

**Connection Admin** permissions are required to modify connection settings.

## Defining included schemas

You can control which schemas Omni pulls into your model using the **Include schemas** field in the connection settings. Only the listed schemas will be included when the model is built.

If this field is left blank, Omni will include all available schemas in the accessible databases for that connection.

When finished modifying the connection settings, trigger a [schema refresh](/modeling/develop/schema-refreshes) to apply the changes to the model.

## Example configuration

The **Include schemas** field accepts a comma-separated list of schema names, and also supports wildcard syntax for partial matches. You can prefix an entry with `-` to exclude it from the match. A list containing only exclusion entries matches everything not excluded.

<Note>
  The values in **Included schemas** are case-sensitive, meaning they must exactly match the name of the schema in the database.
</Note>

```yaml title="Include only the blob_sales schema" theme={null}
blob_sales
```

```yaml title="Include only the blob_sales & blob_marketing schemas" theme={null}
blob_sales, blob_marketing
```

```yaml title="Include only schemas starting with blob_" theme={null}
blob_*
```

```yaml title="Include all blob_ schemas except blob_test" theme={null}
blob_*, -blob_test
```

## Related

* [Offloading schemas](/connect-data/offloading-schemas)
* [Incorporating database changes with schema refreshes](/modeling/develop/schema-refreshes)


# Connecting Amazon Athena to Omni as a data source
Source: https://docs.omni.co/connect-data/setup/athena

Learn how to create an access key or IAM role and connect your Amazon Athena data source to Omni.

Omni's Athena integration supports two types of authentication:

* [**Access key**](#access-key) - Uses an IAM user to authenticate to Amazon Web Services (AWS) by providing Omni with the user's **Access key ID** and **Secret access key**
* [**Cross-account role**](#cross-account-role) - Enables Omni services to assume an IAM role in your account

## Requirements

To follow the steps in this guide, you'll need:

* **An existing Athena database**. Additionally, this database should have an S3 bucket configured to store query results. Refer to the [AWS documentation](https://docs.aws.amazon.com/athena/latest/ug/setting-up.html) to get started.
* **Omni Organization Admin permissions.** This is required to create the Athena connection in Omni.

Depending on the type of authentication you want to use, you'll also need permissions in AWS that:

* Allow you to create access keys
* Allow you to create IAM permission policies and roles

<Heading>
  Option 1: Access key authentication
</Heading>

To use this method of authentication, you'll need to create an [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in the AWS console and then add it to the Athena configuration in Omni.

<Steps>
  <Step title="Create the access key in AWS">
    <Note>
      To complete this step, you need permissions in AWS that allow you to create access keys.
    </Note>

    In the AWS console, [follow these instructions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html#admin-create-access-key) to create an access key. **Note**: The key will only display once after it's created - make sure to copy it immediately.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Athena** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <ParamField>
         The Amazon S3 bucket used to store query results for the Athena database
       </ParamField>

       <ParamField>
         The lowercase name of the data catalog to connect to
       </ParamField>

       <ParamField>
         A comma-delimited list of data catalogs you want to generate models for, ex: `catalog1`, `catalog2`
       </ParamField>

       <Offloaded />

       <Default />

       <TableUploads />

       <ParamField>
         Select **AWS Access Key**
       </ParamField>

       <ParamField>
         The ID of the AWS access key, which you created in the previous step
       </ParamField>

       <ParamField>
         The secret access key for AWS authentication, which you created in the previous step
       </ParamField>

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <AlwaysScopeViewNames />

       <ParamField>
         The AWS region the database is in. Defaults to `us-east-1`.
       </ParamField>

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

<Heading>
  Option 2: Cross-account role authentication
</Heading>

Cross-account role authentication allows you to specify an IAM role for Omni to assume when connecting to Athena.

<Steps>
  <Step title="Open the Athena setup page in Omni">
    <OmniConnection />

    Leave this page open for now - you'll need it in the next step.
  </Step>

  <Step title="Create an IAM policy">
    <Note>
      To complete this step, you need permissions in AWS that allow you to create IAM policies.
    </Note>

    In this step, you'll create an IAM policy that grants the required permissions to the IAM role Omni will assume. The policy includes permissions for querying data and, optionally, [uploading tables](/analyze-explore/data-input-csvs) to join with your warehouse data.

    1. Sign into your AWS console.

    2. Navigate to **IAM**, then click **Roles** in the sidebar.

    3. On the page that displays, click **Create policy**.

    4. In the **Policy editor** section, click the toggle to **JSON**:

       <img alt="AWS IAM policy editor" />

    5. In the policy editor, paste the following policy. Replace `<NAME-OF-ATHENA-QUERY-RESULTS-BUCKET>` with the name of the S3 bucket used to store Athena query results:

       ```json expandable highlight={28} theme={null}
       {
        "Version": "2012-10-17",
        "Statement": [
         {
          "Sid": "BasePermissionsForAllS3Buckets",
          "Effect": "Allow",
          "Action": [
           "s3:ListAllMyBuckets",
           "s3:ListBucket",
           "s3:GetBucketLocation"
          ],
          "Resource": "*"
         },
         {
          "Sid": "BaseAndQueryPermissionsForQueryResultBucket",
          "Effect": "Allow",
          "Action": [
           "s3:GetObject",
           "s3:ListBucket",
           "s3:GetBucketLocation",
           "s3:ListBucket",
           "s3:ListBucketMultipartUploads",
           "s3:ListMultipartUploadParts",
           "s3:AbortMultipartUpload",
           "s3:PutObject",
           "s3:DeleteObject"
          ],
          "Resource": [
           "arn:aws:s3:::<NAME-OF-ATHENA-QUERY-RESULTS-BUCKET>",
           "arn:aws:s3:::<NAME-OF-ATHENA-QUERY-RESULTS-BUCKET>/*"
          ]
         },
         {
          "Sid": "GluePermissions",
          "Effect": "Allow",
          "Action": [
           "glue:GetTables",
           "glue:GetDatabases",
           "glue:GetDatabase",
           "glue:GetTable"
          ],
          "Resource": "*"
         },
         {
          "Sid": "AthenaPermissions",
          "Effect": "Allow",
          "Action": [
           "athena:StartQueryExecution",
           "athena:GetQueryResults",
           "athena:GetQueryResultsStream",
           "athena:ListDatabases",
           "athena:GetQueryExecution",
           "athena:ListTableMetadata"
          ],
          "Resource": "*"
         }
        ]
       }
       ```

       <Note>
         If your data is stored in a separate bucket than the query results, you'll need to add an additional permissions block to the policy.

         Replace `<NAME-OF-BUCKET-CONTAINING-DATA>` with the name of the bucket that contains the data:

         ```json title="Additional permissions for different data & query buckets" highlight={9-10} theme={null}
         {
           "Sid": "S3AccessForDataBuckets",
           "Effect": "Allow",
           "Action": [
             "s3:GetObject",
             "s3:ListBucket"
           ],
           "Resource": [
             "arn:aws:s3:::<NAME-OF-BUCKET-CONTAINING-DATA>",
             "arn:aws:s3:::<NAME-OF-BUCKET-CONTAINING-DATA>/*"
           ]
         }
         ```
       </Note>

    6. Click **Next**.

    7. On the **Policy details** page, enter a name and description for the policy.

    8. When finished, click **Create policy**.
  </Step>

  <Step title="Create the IAM role">
    <Note>
      To complete this step, you need permissions in AWS that allow you to create IAM roles.
    </Note>

    In this step, you'll create the IAM role and attach the permissions policy you created in step 2 to it.

    1. You should still be in the **IAM** section of the AWS console. If not, navigate there.
    2. Click **Roles** in the sidebar.
    3. On the page that displays, click **Create role**.
    4. Define the trusted entity for the role as follows:

       * **Trusted entity type** - Select **AWS account**
       * In **An AWS account**, click **Another AWS account**
       * **Account ID** field - Paste the **AWS Account ID** value from the Omni setup page
       * In **Options**, check **Require external ID**
       * **External ID** - Enter a placeholder value - we used `we-will-add-this-later` in the below image. **You will update this after you save the connection in Omni!**

       At this point, the page should look like this:

       <img alt="Athena role entity" />

       When finished, click **Next**.
    5. On the **Add permissions** page, locate and select the policy you created in the previous section.
    6. Click **Next**.
    7. In the **Role details** section, enter a name for the role.
    8. Review the selections and click **Create role** when finished.

    After the role is created, open its details page in AWS and locate the **ARN** near the top of the page:

    <img alt="Athena role ARN" />

    Leave this page open - you'll need it to complete the setup.
  </Step>

  <Step title="Create the connection in Omni">
    Navigate back to the Athena setup page in Omni and fill in the connection details:

    <DisplayName />

    <ParamField>
      The Amazon S3 bucket used to store query results for the Athena database
    </ParamField>

    <ParamField>
      The lowercase name of the data catalog to connect to
    </ParamField>

    <ParamField>
      A comma-delimited list of data catalogs you want to generate models for, ex: `catalog1`, `catalog2`
    </ParamField>

    <Offloaded />

    <Default />

    <TableUploads />

    <ParamField>
      Select **AWS Cross Account Role**
    </ParamField>

    <ParamField>
      The ARN of the IAM role for Omni to assume, which you created in step 3
    </ParamField>

    <DatabaseTimezone />

    <QueryTimezone />

    <AllowUserSpecificTimezones />

    <AutoGenerateRelationships />

    <AlwaysScopeViewNames />

    <ParamField>
      The AWS region the database is in. Defaults to `us-east-1`.
    </ParamField>

    <BaseAccess />

    When finished, click **Create connection**.

    <Note>
      After you save the connection, you'll likely see an error similar to `System message: AWS Role must be configured to check for an External ID` - don't worry! You're going to address this in the next step.
    </Note>
  </Step>

  <Step title="Add the Omni external ID to the IAM role">
    1. In AWS, navigate back to the IAM role page.

    2. On the role's details page, click the **Trust relationships** tab in the middle of the page:

       <img alt="Athena role trust relationships" />

    3. Click **Edit trust policy**.

    4. Locate the `sts:ExternalId` property. Replace its value with the **AWS External ID** value from the Omni setup page:

       ```json title="Add AWS external ID from Omni" highlight={12} theme={null}
       {
         "Version": "2012-10-17",
         "Statement": [
           {
             "Effect": "Allow",
             "Principal": {
               "AWS": "arn:aws:iam::767117061426:root"
             },
             "Action": "sts:AssumeRole",
             "Condition": {
               "StringEquals": {
                 "sts:ExternalId": "<REPLACE-WITH-OMNI-EXTERNAL-ID>"
               }
             }
           }
         ]
       }
       ```

    5. Click **Update policy** when finished.

    Lastly, navigate back to the Omni setup page and click **Update and test connection**. At this point, the connection should return a **Success!** message.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection

## Troubleshooting

<Accordion title="Data & query results in different S3 buckets">
  **Applicable if using cross-account role authentication.** If the S3 bucket containing your data is different than the bucket Athena is configured to use for query results, you may encounter an error in Omni.

  Adding a block like the following to the IAM permissions policy attached to the IAM role you created can help resolve the issue.

  Replace `<NAME-OF-BUCKET-CONTAINING-DATA>` with the name of the bucket that contains the data:

  ```json title="Additional permissions for different data & query buckets" highlight={9-10} theme={null}
  {
    "Sid": "S3AccessForDataBuckets",
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
      "s3:ListBucket"
    ],
    "Resource": [
      "arn:aws:s3:::<NAME-OF-BUCKET-CONTAINING-DATA>",
      "arn:aws:s3:::<NAME-OF-BUCKET-CONTAINING-DATA>/*"
    ]
  }
  ```
</Accordion>


# Connecting Google BigQuery to Omni with a service account
Source: https://docs.omni.co/connect-data/setup/bigquery

Connect your Google BigQuery project to Omni using a service account and private key.

<Note>
  This guide uses a service account key. To connect without storing a key, see [Connecting BigQuery with workload identity federation](/connect-data/setup/bigquery-workload-identity).
</Note>

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Google Cloud admin permissions**, which are required to create a [service account](https://cloud.google.com/iam/docs/service-accounts) and [private key](https://cloud.google.com/storage/docs/authentication#generating-a-private-key).
* **The following details about the default dataset in your BigQuery project:**

  * The **name** of the default dataset
  * Its **data location**
  * Its **timezone** <br /><br />

  <Accordion title="Need help locating the dataset?">
    1. Navigate to your BigQuery console.
    2. Select the project your dataset resides in. Use the top middle drop-down menu to toggle between projects.
    3. Select a dataset and the info will appear in the **Dataset info** menu. In this example:

       * The dataset **name** is `products`
       * The **Data location** is `US`
       * The **timezone** is `UTC-7`, as indicated in the **Last modified** field

    <img alt="BigQuery dataset info" />
  </Accordion>

## Setup

<Steps>
  <Step title="Create a BigQuery service account and grant project access">
    1. Open the credentials page in the [Google Cloud Platform API Manager](https://console.cloud.google.com/apis/credentials) and, if necessary, select your project.
    2. Click **Create credentials**, located near the top center of the page, then **Service account**.
    3. In the **Service account details** section:
       1. Enter a name and description for the new service account, such as `Omni BigQuery`.
       2. Click **Create and continue**.
    4. In the **Grant this service account access to project** section, grant the service account access to the following [BigQuery roles](https://cloud.google.com/bigquery/access-control#curated_roles_comparison_matrix):

       * BigQuery Job User
       * BigQuery Data Viewer
       * BigQuery Metadata Viewer - This role is only required if you want to give Omni access to all views within a dataset (e.g., `project.*`) when setting up the connection in Omni. If you explicitly list specific datasets without wildcards in the [connection setup step](#create-connection), Omni will skip the project-level metadata scan and work with dataset-level permissions only.

       <img alt="Service account roles" />
    5. After adding the roles, click **Done**. You'll be redirected to the **Credentials** page.
  </Step>

  <Step title="Create a service account private key">
    1. In the **Service Accounts** section, click the service account you created in the [previous step](#create-service-account).
    2. On the service account details page, click the **Keys** tab near the top of the page.
    3. Click **Add Key > Create new key**.
    4. When prompted, select **JSON** as the key type and then click **Create**:
       <img alt="Key type prompt" />
    5. The JSON key will be saved to your computer. **After noting where the key was downloaded**, click **Close**.
       <img alt="Key confirmation" />
  </Step>

  <Step title="Set up a table upload dataset">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated dataset to use for [table uploads](/analyze-explore/data-input-csvs). Before you create the dataset, note that:

    * This dataset can't be used for other modeled tables
    * This dataset must be in the same region as other projects and schemas in the connection, or you may encounter cross-region errors

    To create a dataset for table uploads:

    1. Navigate to your BigQuery project.
    2. Create the dataset.
    3. After the dataset is created, open it so that its details display.
    4. Click **Share > Manage permissions**, located next to the **Copy** option near the top right corner of the page.
    5. In the dialog that displays, click **Add principal**.
    6. Fill in the fields as follows:

       * **New principals** - Add the service account you created in [step 1](#create-service-account)
       * **Role** - Add the **BigQuery Data Editor** role

       <img alt="BigQuery dataset sharing" />
    7. Click **Save**.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **BigQuery** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Default />

       <IncludeOther />

       <Include />

       <Tip>
         When you explicitly list datasets without wildcards (no `*` characters), Omni skips the project-level metadata scan and only requires dataset-level permissions (BigQuery Data Viewer role). Using wildcards or leaving this field empty requires project-level permissions (BigQuery Metadata Viewer role).
       </Tip>

       <Offloaded />

       <TableUploads label="Dataset for CSV Upload" />

       <ParamField>
         The type of authentication to use. Select **Service Account Authentication**.

         <Expandable title="Service Account Authentication">
           <ParamField>
             The JSON private key you created in [step 2](#create-service-account).
           </ParamField>
         </Expandable>
       </ParamField>

       <ParamField>
         The region the dataset resides in. Refer to the [Requirements](#requirements) section if you need help finding this information.
       </ParamField>

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <ParamField>
         The maximum bytes billed for queries run on this connection.
       </ParamField>

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting Google BigQuery to Omni with workload identity federation
Source: https://docs.omni.co/connect-data/setup/bigquery-workload-identity

Connect BigQuery to Omni using workload identity federation — no service account key to store, upload, or rotate.

With workload identity federation, Omni connects to BigQuery using its own cloud identity instead of a stored service account key. Omni exchanges its identity for short-lived Google Cloud credentials through a [workload identity pool](https://cloud.google.com/iam/docs/workload-identity-federation) you control — there's no key to create, upload, or rotate, and you can revoke Omni's access at any time from your Google Cloud project.

## How it works

1. In your Google Cloud project, you create a workload identity pool with an AWS provider that trusts the identity Omni presents.
2. When Omni queries BigQuery or refreshes the connection's schema, it exchanges that role's credentials for a short-lived Google Cloud access token.
3. The token acts either as the federated identity itself, or as a service account you allow Omni to impersonate.

## Requirements

<Note>
  Workload identity federation is currently available for **AWS-hosted Omni deployments only**. Support for Azure-hosted deployments is planned.
</Note>

To follow the steps in this guide, you'll need:

* **Organization Admin permissions** in Omni

* **Google Cloud admin permissions**, which are required to create workload identity pools and grant IAM roles

* **The `gcloud` CLI**

* **The following details about the default dataset in your BigQuery project:**

  * The **name** of the default dataset
  * Its **data location**
  * Its **timezone** <br /><br />

  <Accordion title="Need help locating the dataset?">
    1. Navigate to your BigQuery console.
    2. Select the project your dataset resides in. Use the top middle drop-down menu to toggle between projects.
    3. Select a dataset and the info will appear in the **Dataset info** menu. In this example:

       * The dataset **name** is `products`
       * The **Data location** is `US`
       * The **timezone** is `UTC-7`, as indicated in the **Last modified** field

    <img alt="BigQuery dataset info" />
  </Accordion>

## Setup

<Steps>
  <Step title="Retrieve Omni's AWS identity information">
    1. In Omni, click **Settings > Connections**.
    2. Click the **BigQuery** option.
    3. In the **Authentication Type** menu, select **Workload Identity Federation**.
    4. Copy the **Omni Workload Identity** value. It will contain a value like the following:

       ```text theme={null}
       arn:aws:iam::123456789012:role/Prod-ProdModelTaskRole
       ```

    This identifies Omni to Google Cloud. Note that:

    * **It contains Omni's AWS account ID**. This is the `123456789012` segment. You'll need this when creating the provider in the next step.
    * **It contains a prefix, not the full role name.** The actual role has a random suffix appended by Omni's infrastructure, so your attribute condition must use a **starts-with** comparison. An exact-match condition will never match.
  </Step>

  <Step title="Create a workload identity pool and AWS provider">
    <Tabs>
      <Tab title="Console" icon="window-maximize">
        1. In the Google Cloud Console, navigate to [**IAM & Admin > Workload Identity Federation**](https://console.cloud.google.com/iam-admin/workload-identity-pools).
        2. Click **Create pool**.
        3. Enter a name, such as `omni`, and continue.
        4. Add a provider to the pool:
           * **Provider type** - AWS
           * **Provider name** - Enter a name, such as `Omni`
           * **AWS account ID** - The account ID from the value you copied in&#x20;
        5. Configure the provider attribute mappings. AWS presents Omni's identity in a different format than the value shown in Omni, so the mappings reconstruct the role ARN before comparing it.

           1. Click **Edit mapping**.
           2. For `google.subject`, paste the following into the corresponding **AWS** field:

              ```text wrap theme={null}
              assertion.arn.extract('assumed-role/{role}/')
              ```
           3. For `attribute.aws_role_arn`, paste the following into the corresponding **AWS** field:

              ```text wrap theme={null}
              'arn:aws:iam::' + assertion.account + ':role/' + assertion.arn.extract('assumed-role/{role}/')
              ```

           The mappings should look like the following when finished:

           <Frame>
             <img alt="Configured provider attribute mappings in the Google Cloud Console" />
           </Frame>
        6. Configure the provider attribute conditions:
           1. Click **Add condition**.
           2. In the text field, add the attribute condition. Replace  with the  value you copied from Omni in :

              ```text wrap theme={null}
              attribute.aws_role_arn.startsWith('OMNI_WORKLOAD_IDENTITY')
              ```

              For example:

              ```text wrap theme={null}
              attribute.aws_role_arn.startsWith('arn:aws:iam::123456789012:role')
              ```

              The attribute conditions should look like the following when finished:

        <Frame>
          <img alt="Configured provider attribute condition in the Google Cloud Console" />
        </Frame>

        7. Click **Save**.
      </Tab>

      <Tab title="gcloud CLI" icon="terminal">
        Using the `gcloud CLI`, run the following to create a workload identity pool:

        ```bash highlight={2} theme={null}
        gcloud iam workload-identity-pools create omni \
          --project=GCP_PROJECT_ID \
          --location=global \
          --display-name="Omni"
        ```

        Replace **GCP\_PROJECT\_ID** with the ID of your GCP project.

        Then, create the provider:

        ```bash wrap highlight={2,5,7} theme={null}
        gcloud iam workload-identity-pools providers create-aws omni-aws \
          --project=GCP_PROJECT_ID \
          --location=global \
          --workload-identity-pool=omni \
          --account-id=OMNI_AWS_ACCOUNT_ID \
          --attribute-mapping="google.subject=assertion.arn.extract('assumed-role/{role}/'),attribute.aws_role_arn='arn:aws:iam::'+assertion.account+':role/'+assertion.arn.extract('assumed-role/{role}/')" \
          --attribute-condition="attribute.aws_role_arn.startsWith('OMNI_WORKLOAD_IDENTITY')"
        ```

        Replace the following values:

        | Placeholder                      | Replace with                                 |
        | -------------------------------- | -------------------------------------------- |
        | **GCP\_PROJECT\_ID**             | The ID of your GCP project                   |
        | **OMNI\_AWS\_ACCOUNT\_ID**       | The account ID from the value you copied in  |
        | The entire  value you copied in  |                                              |
      </Tab>
    </Tabs>
  </Step>

  <Step title="Grant BigQuery access">
    Choose how Omni's federated identity accesses BigQuery:

    <AccordionGroup>
      <Accordion title="Option 1 - Grant direct access" icon="arrow-right" description="Grant the pool the BigQuery roles directly on your project.">
        Grant the BigQuery roles directly to the pool's identities, replacing **GCP\_PROJECT\_ID** with the ID of your GCP project:

        ```bash theme={null}
        gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
          --role=roles/bigquery.jobUser \
          --member="principalSet://iam.googleapis.com/projects/GCP_PROJECT_ID/locations/global/workloadIdentityPools/omni/*"

        gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
          --role=roles/bigquery.dataViewer \
          --member="principalSet://iam.googleapis.com/projects/GCP_PROJECT_ID/locations/global/workloadIdentityPools/omni/*"
        ```

        **Optional**. Grant the `metadataViewer` role directly to the pool's identities:

        ```bash theme={null}
        gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
          --role=roles/bigquery.metadataViewer \
          --member="principalSet://iam.googleapis.com/projects/GCP_PROJECT_ID/locations/global/workloadIdentityPools/omni/*"
        ```

        The `metadataViewer` role is only required if you want to give Omni access to all views within a dataset (e.g., `project.*`) when setting up the connection in Omni. If you explicitly list specific datasets without wildcards in the [connection setup step](#create-connection), Omni will skip the project-level metadata scan and work with dataset-level permissions only.

        When you configure Omni, leave the **Service account impersonation URL** field blank.
      </Accordion>

      <Accordion title="Option 2 - Impersonation through a service account" icon="mask" description="Have the pool impersonate a named service account that holds the required BigQuery roles.">
        1. Create a service account (for example, `omni-bigquery`) and grant it the following [BigQuery roles](https://cloud.google.com/bigquery/access-control#curated_roles_comparison_matrix) on your project:
           * BigQuery Job User
           * BigQuery Data Viewer
        2. Allow the pool's identities to impersonate the service account by granting the **Workload Identity User** role on the service account to the pool:

           ```bash theme={null}
           gcloud iam service-accounts add-iam-policy-binding omni-bigquery@GCP_PROJECT_ID.iam.gserviceaccount.com \
             --project=GCP_PROJECT_ID \
             --role=roles/iam.workloadIdentityUser \
             --member="principalSet://iam.googleapis.com/projects/GCP_PROJECT_ID/locations/global/workloadIdentityPools/omni/*"
           ```

           Replace **GCP\_PROJECT\_ID** with the ID of your GCP project.

        Keep the service account email handy - you'll need it to complete the setup in Omni.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Set up a table upload dataset">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated dataset to use for [table uploads](/analyze-explore/data-input-csvs). Before you create the dataset, note that:

    * This dataset can't be used for other modeled tables
    * This dataset must be in the same region as other projects and schemas in the connection, or you may encounter cross-region errors

    To create a dataset for table uploads:

    1. In the Google Cloud Console, navigate to your BigQuery project.
    2. Create the dataset.
    3. After the dataset is created, open it so that its details display.
    4. Click **Share > Manage permissions**, located next to the **Copy** option near the top right corner of the page.
    5. In the dialog that displays, click **Add principal**.
    6. For the **New principals** field, the value you enter depends on the access method you selected in [step 3](#grant-access):
       * **Direct access** - Enter the pool identity, including the `principalSet://`. This is the `member` value from the command in [step 3](#direct-access) and will look like the following:

         ```text theme={null}
         principalSet://iam.googleapis.com/projects/GCP_PROJECT_ID/locations/global/workloadIdentityPools/omni/*
         ```
       * **Service account** - Enter the email address of the service account you created in [step 3](#service-account). This will look like the following:

         ```text theme={null}
         omni-bigquery@GCP_PROJECT_ID.iam.gserviceaccount.com
         ```
    7. Add the **BigQuery Data Editor** role.
    8. Click **Save**.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **BigQuery** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Default />

       <IncludeOther />

       <Include />

       <Tip>
         When you explicitly list datasets without wildcards (no `*` characters), Omni skips the project-level metadata scan and only requires dataset-level permissions (BigQuery Data Viewer role). Using wildcards or leaving this field empty requires project-level permissions (BigQuery Metadata Viewer role).
       </Tip>

       <Offloaded />

       <TableUploads label="Dataset for CSV Upload" />

       <ParamField>
         The type of authentication to use. Select **Workload Identity Federation**.

         <Expandable title="Workload Identity Federation settings">
           <ParamField>
             The full resource name of the provider you created in [step 2](#pool-provider), prefixed with `//iam.googleapis.com/`. For example:

             ```text theme={null}
             //iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/omni/providers/omni-aws
             ```

             The Google Cloud console doesn't display this value for AWS providers — build it from the pool and provider names, or run `gcloud iam workload-identity-pools providers describe` and prefix the returned `name` with `//iam.googleapis.com/`.
           </ParamField>

           <ParamField>
             **Required for [service account impersonation](#service-account)**. The service account email from [step 3](#grant-access). Otherwise, leave blank for direct access.
           </ParamField>

           <ParamField>
             The Google Cloud project queries run in and are billed to. The federated identity or impersonated service account must be able to run BigQuery jobs in it.
           </ParamField>
         </Expandable>
       </ParamField>

       <ParamField>
         The region the dataset resides in. Refer to the [Requirements](#requirements) section if you need help finding this information.
       </ParamField>

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <ParamField>
         The maximum bytes billed for queries run on this connection.
       </ParamField>

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## Troubleshooting

| Issue                                      | What to check                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Token exchange fails or is denied**      | Verify the attribute condition uses `startsWith` — the value Omni shows is a prefix, and the full role name includes a random suffix. Also confirm the attribute mapping reconstructs the role ARN as shown in step 2; the raw AWS assertion uses the `arn:aws:sts::...:assumed-role/...` format, which won't match the value from Omni without it. |
| **Queries fail with a permission error**   | Confirm the roles from step 3 were granted to the right principal: the service account (impersonation) or the pool's `principalSet` (direct access). IAM changes can take a couple of minutes to propagate.                                                                                                                                         |
| **Datasets appear, but contain no tables** | Check the connection's **Default Dataset** field — it must be a dataset name, not a project ID.                                                                                                                                                                                                                                                     |

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting ClickHouse to Omni
Source: https://docs.omni.co/connect-data/setup/clickhouse

Learn how to retrieve connection details and connect your ClickHouse database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in ClickHouse** that allow you to access connection credentials

## Setup

<Steps>
  <Step title="Retrieve ClickHouse connection details">
    1. In ClickHouse, navigate to the warehouse you want to connect to Omni.
    2. Click **Connect** in the sidebar.
    3. A dialog like the following will display:

       <img alt="Connection details" />

    The information you need is highlighted in the above image, specifically:

    * **Username** - In the above image, the username is ClickHouse's default (`default`), but this may differ for you.

      <Note>
        If you want to use a different (non-default) Clickhouse user, verify that the user has, at a minimum, `SELECT` permissions for:

        * All schemas you want to include in the Omni model
        * `INFORMATION_SCHEMA.SCHEMATA`
        * `INFORMATION_SCHEMA.TABLES`
      </Note>

    * **Password**

    * **Host** - This is a string similar to `https://<some-string>.eastus2.azure.clickhouse.cloud`

    * **Port** - In the above image, the port is `8443`

    Keep this information handy - you'll need it to complete the setup.
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to ClickHouse is [limited by IP address](https://clickhouse.com/docs/cloud/security/setting-ip-filters#create-or-modify-an-ip-access-list), you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **ClickHouse** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Default />

       <Include />

       <Offloaded />

       <TableUploads />

       <Username />

       <Password />

       <TrustServerCertificate />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting Databricks to Omni
Source: https://docs.omni.co/connect-data/setup/databricks

Learn how to generate credentials, retrieve connection details, and connect your Databricks workspace to Omni.

<Note>
  If your Databricks workspace is in a private network and requires PrivateLink access, refer to the [Databricks PrivateLink guide](/connect-data/databricks-privatelink) instead.
</Note>

## Requirements

To follow the steps in this guide, you'll need **Organization Admin permissions in Omni**.

## Setup

<Steps>
  <Step title="Generate credentials">
    Omni can use either personal access token (PAT) or OAuth machine-to-machine (M2M) credentials to authenticate to Databricks.

    * **To use a <Tooltip>PAT</Tooltip>** - Follow the Databricks [Access Token for a service principal guide](https://docs.databricks.com/en/dev-tools/auth/pat.html#databricks-personal-access-tokens-for-service-principals). When you create the connection in Omni, you'll select the **Personal Access Token** as the **Authentication type**.

    * **To use an <Tooltip>M2M</Tooltip>** - Follow the Databricks [Authenticate as a service principal guide](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m). When you create the connection in Omni, you'll select the **OAuth M2M Authentication** as the **Authentication type**.
  </Step>

  <Step title="Grant permissions to the service principal">
    The Databricks service principal or user must have the following privileges on each catalog and schema Omni will access:

    ```sql theme={null}
    GRANT USE CATALOG ON CATALOG <catalog> TO `omni_user`; 
    GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `omni_user`;
    GRANT SELECT ON SCHEMA <catalog>.<schema> TO `omni_user`;
    ```

    Repeat the schema-level grants for each schema you want Omni to query. The `SELECT ON SCHEMA` grant covers all current and future tables and views within that schema.
  </Step>

  <Step title="Retrieve database connection details">
    Next, you'll need to retrieve your database's connection details from Databricks. Follow the steps in [this Databricks guide](https://docs.databricks.com/en/integrations/compute-details.html), specifically the **getting connection details for a Databricks SQL warehouse** section.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Databricks** option.

    3. On the connection setup page, fill in the connection details:
       <DisplayName />
       <Host />
       <ParamField>
         The HTTP path for the Databricks SQL warehouse.
       </ParamField>
       <Default />
       <IncludeOther />
       <Include />
       <Offloaded />
       <TableUploads />
       <Default />
       <ParamField>
         Select the authentication type you chose in step 1 and enter the credentials into their corresponding fields.
       </ParamField>
       <DatabaseTimezone />
       <QueryTimezone />
       <AllowUserSpecificTimezones />
       <QueryTimeout />
       <ParamField>
         When enabled, Omni will sync metrics and metric views defined in your [Databricks Unity Catalog](/connect-data/databricks-unity-catalog-integration) into your Omni model.
       </ParamField>
       <AlwaysScopeViewNames />
       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting Exasol to Omni
Source: https://docs.omni.co/connect-data/setup/exasol

Learn how to create a database user, grant permissions, and connect your Exasol database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in Exasol** that allow you to create database users and grant permissions

## Setup

<Steps>
  <Step title="Create an Omni database user">
    1. In your Exasol database, run the following command to create a database user for Omni:

       ```sql title="Create Omni user" theme={null}
       CREATE USER OMNI IDENTIFIED BY "<password>";
       GRANT ALTER SESSION TO OMNI;
       ```

    2. Grant the Omni user access to the system views required for schema, table, and column discovery:

       ```sql title="Grant metadata introspection permissions" theme={null}
       GRANT SELECT ON EXA_ALL_SCHEMAS TO OMNI;
       GRANT SELECT ON EXA_ALL_TABLES TO OMNI;
       GRANT SELECT ON EXA_ALL_COLUMNS TO OMNI;
       ```

    3. Grant `SELECT` access to the schemas or tables you want to query in Omni:

       ```sql title="Grant data access to the Omni user" theme={null}
       GRANT SELECT ON <tables used by OMNI> TO OMNI;
       ```

       You could also grant all privileges:

       ```sql title="Grant all privileges to the Omni user" theme={null}
       GRANT ALL PRIVILEGES ON SCHEMA <YOUR_SCHEMA> TO OMNI;
       ```

       Or, run the following to avoid needing to grant access to tables created in the future:

       ```sql title="Grant data access to all existing and future tables" theme={null}
       GRANT SELECT ANY TABLE TO OMNI;
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the Exasol database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Exasol** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Include />

       <Offloaded />

       <Default />

       <Username />

       <Password />

       <TrustServerCertificate />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <QueryTimeout />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connect a database
Source: https://docs.omni.co/connect-data/setup/index

Connect your data warehouse or database to Omni

Omni connects directly to your data warehouse or database. Select your database below to get started with the setup process.

<Tip>
  If a supported database has a connection string (URI) for your database, you can [quick connect](/connect-data/setup/quick-connect) by pasting it instead of manually filling out the connection form.
</Tip>

## Supported databases

<Columns>
  <Card title="Amazon Athena" href="/connect-data/setup/athena" icon="aws">
    Connect to Amazon Athena.
  </Card>

  <Card title="Amazon Redshift" href="/connect-data/setup/redshift" icon="aws">
    Connect to Amazon Redshift. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="ClickHouse" href="/connect-data/setup/clickhouse" icon="database">
    Connect to ClickHouse. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="Databricks" href="/connect-data/setup/databricks" icon="layer-group">
    Connect to Databricks. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="Exasol" href="/connect-data/setup/exasol" icon="database">
    Connect to Exasol. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="Google BigQuery" icon="google">
    Connect to Google BigQuery using a [service account + key](/connect-data/setup/bigquery) or [Workload identity federation](/connect-data/setup/bigquery-workload-identity).
  </Card>

  <Card title="MariaDB" href="/connect-data/setup/mariadb" icon="database">
    Connect to MariaDB. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="Microsoft SQL Server" href="/connect-data/setup/microsoftsql" icon="microsoft">
    Connect to Microsoft SQL Server. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="MotherDuck" href="/connect-data/setup/motherduck" icon="duck">
    Connect to MotherDuck.
  </Card>

  <Card title="MySQL" href="/connect-data/setup/mysql" icon="database">
    Connect to MySQL. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="PostgreSQL" href="/connect-data/setup/postgres" icon="elephant">
    Connect to PostgreSQL. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="Snowflake" href="/connect-data/setup/snowflake" icon="snowflake">
    Connect to Snowflake. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>

  <Card title="Starburst Galaxy (Trino)" href="/connect-data/setup/starburst-galaxy" icon="star-of-life">
    Connect to Starburst Galaxy using the Trino connector.
  </Card>

  <Card title="StarRocks" href="/connect-data/setup/starrocks" icon="database">
    Connect to StarRocks. **Supports [quick connect](/connect-data/setup/quick-connect).**
  </Card>
</Columns>

## Next steps

After connecting your database, you may want to:

* [Restrict schemas](/connect-data/schema-restriction) to limit which schemas are visible in Omni
* [Configure timezones](/connect-data/timezones) for your connection
* Set up [SSH tunnels](/connect-data/ssh-tunnels) or [AWS PrivateLink](/connect-data/aws-privatelink) for secure connections


# Connecting MariaDB to Omni
Source: https://docs.omni.co/connect-data/setup/mariadb

Learn how to create a database user, grant permissions, and connect your MariaDB database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in MariaDB** that allow you to create database users

## Setup

<Steps>
  <Step title="Create a database user for Omni">
    In your MariaDB database, run the following command to create a database user for Omni:

    ```sql title="Create Omni user" theme={null}
    CREATE USER omni IDENTIFIED WITH mysql_native_password BY '<password>';
    ```

    Next, run the following command to grant the Omni user access to the database:

    ```sql title="Grant SELECT permissions to Omni user" theme={null}
    GRANT SELECT ON database_name.* TO 'omni'@'%';
    ```
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). **Note**: This schema can't be used for other modeled tables.

    1. Create the schema in MariaDB.
    2. Run the following commands to grant the Omni user the required privileges:

       ```sql title="Grant the Omni user permissions to upload schema" theme={null}
       GRANT SELECT, CREATE, INSERT, UPDATE, DELETE ON upload_schema_name.* TO 'omni'@'%';
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the MariaDB database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **MariaDB** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Default />

       <Include />

       <Offloaded />

       <TableUploads />

       <Username />

       <Password />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <QueryTimeout />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting Microsoft SQL Server to Omni
Source: https://docs.omni.co/connect-data/setup/microsoftsql

Learn how to retrieve connection details and connect your Microsoft SQL Server database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Microsoft Azure Portal Admin permissions**, which are required to allowlist Omni's IP addresses

## Setup

<Steps>
  <Step title="Retrieve connection details">
    1. Navigate to your [Microsoft Azure Portal](https://portal.azure.com/#home).

    2. In the portal, navigate to the database you want to connect to Omni.

    3. On the database's details page, locate the **Connection strings** field:

       <img alt="Connection strings link" />

    4. Click the **Show database connection strings** link.

    5. On the page that displays, click the **JDBC** tab:

       <img alt="Connection string" />

    6. You should see something like the following, which will contain all the information you need:

       ```yaml theme={null}
       jdbc:sqlserver://omni-test-admin.database.windows.net:1433;
       database=e-commerce;
       user=omni-test-admin@omni-test-admin;
       password={your_password_here};
       encrypt=true;
       trustServerCertificate=false;
       hostNameInCertificate=*.database.windows.net;
       loginTimeout=30;
       ```
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). This schema can't be used for other modeled tables.

    1. Create the schema in Microsoft SQL Server. This can be in its own database or the same database as other schemas to be used in modeling.
    2. Run the following commands to grant the Omni user the required privileges:

       ```sql title="Grant Omni user permissions to upload schema" theme={null}
       GRANT CREATE TABLE TO omni;
       GRANT ALTER, INSERT, SELECT, UPDATE ON SCHEMA::upload_schema_name TO omni;
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the SQL Server database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.

    1. Navigate to your [Microsoft Azure Portal](https://portal.azure.com/#home).

    2. In the sidebar, click the **Networking** option under **Security**.

    3. In the **Firewall rules** section, click **Add a firewall rule**:

       <img alt="Add firewall rule" />

    4. Create a rule for each of Omni's IP addresses:

       <img alt="Firewall rule input" />
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Microsoft SQL Server** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Database />

       <Include />

       <Offloaded />

       <TableUploads />

       <Default />

       <Username />

       <Password />

       <TrustServerCertificate />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <QueryTimeout />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting MotherDuck to Omni
Source: https://docs.omni.co/connect-data/setup/motherduck

Learn how to create an access token and connect your MotherDuck database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* Organization Admin permissions in Omni
* A MotherDuck database using MotherDuck v0.10.2 or higher

## Setup

<Steps>
  <Step title="Create a MotherDuck access token">
    1. Sign in to your MotherDuck account.
    2. In top left corner of the page, click the organization name and then **Settings**.
    3. Click **Integrations > Access Tokens**.
    4. Click **+ Create token**.
    5. Enter a **Name** for the token to make it easy to recognize. For example: `Omni connection`
    6. For **Token type**, select **Read/Write token**.
    7. **Optional**. Define expiration settings for the token.
    8. Click **Create token**.
    9. Copy the token. **Note**: The token will only display once, so make sure you copy it before closing the dialog.
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). This can be in its own database or the same database as other schemas to be used in modeling. **Note**: The upload schema can't be used for other modeled tables.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Motherduck** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Database />

       <IncludeOther />

       <Include />

       <Offloaded />

       <TableUploads />

       <ParamField>
         The MotherDuck authentication token you created in step 1.
       </ParamField>

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting MySQL to Omni
Source: https://docs.omni.co/connect-data/setup/mysql

Learn how to create a database user, grant permissions, and connect your MySQL database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in MySQL** that allow you to create database users

## Setup

<Steps>
  <Step title="Create a database user for Omni">
    In your MySQL database, run the following command to create a database user for Omni:

    ```sql title="Create Omni user" theme={null}
    CREATE USER omni IDENTIFIED WITH mysql_native_password BY '<password>';
    ```

    Next, run the following command to grant the Omni user access to the database:

    ```sql title="Grant SELECT permissions to Omni user" theme={null}
    GRANT SELECT ON database_name.* TO 'omni'@'%';
    ```
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). This schema can't be used for other modeled tables.

    1. Create the schema in MySQL.
    2. Run the following commands to grant the Omni user the required privileges:

       ```sql title="Grant Omni user permissions to upload schema" theme={null}
       GRANT SELECT, CREATE, INSERT, UPDATE, DELETE ON upload_schema_name.* TO 'omni'@'%';
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the MySQL database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **MySQL** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Database />

       <Default />

       <Include />

       <Offloaded />

       <TableUploads />

       <Username />

       <Password />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <QueryTimeout />

       <AutoGenerateRelationships />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting Postgres to Omni
Source: https://docs.omni.co/connect-data/setup/postgres

Learn how to create a database user, grant permissions, and connect your Postgres database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in Postgres** that allow you to create database users

## Setup

<Steps>
  <Step title="Create an Omni database user">
    1. In your Postgres database, run the following command to create a database user for Omni:

       ```sql title="Create Omni user" theme={null}
       CREATE USER omni WITH ENCRYPTED PASSWORD '<password>';
       GRANT CONNECT ON DATABASE database_name to omni;
       \c database_name
       GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO omni;
       GRANT SELECT ON ALL TABLES IN SCHEMA public TO omni;
       ```

    2. Grant permissions to the Omni user. If you're using a schema other than `public`, run the following to grant usage to Omni:

       ```sql title="Grant usage to the Omni user" theme={null}
       GRANT USAGE ON SCHEMA schema_name TO omni
       ```

    3. Lastly, ensure any tables created in the future will be accessible:

       ```sql title="Grant permissions to future tables to the Omni user" theme={null}
       ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON tables TO omni;
       ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON sequences TO omni;
       ```

    4. **Optional**. Enable the `pg_stat_statements` extension to use the Modeling Agent's [Suggest model from query history skill](/ai/model-assistant#suggest-model-from-query-history):

       ```sql title="Enable pg_stat_statements extension" theme={null}
       CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
       ```
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). This schema can't be used for other modeled tables.

    1. Create the schema in Postgres.
    2. Run the following commands to grant the Omni user the required privileges:

       ```sql title="Grant Omni user permissions to upload schema" theme={null}
       GRANT USAGE, CREATE ON SCHEMA upload_schema_name TO omni;
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the Postgres database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Postgres** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Database />

       <Include />

       <IncludeOther />

       <Offloaded />

       <TableUploads />

       <Username />

       <Password />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <QueryTimeout />

       <AutoGenerateRelationshipsAllModes />

       <AlwaysScopeViewNames />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Creating quick database connections with connection strings
Source: https://docs.omni.co/connect-data/setup/quick-connect

Create database connections quickly by pasting a connection URI

You can quickly create a database connection in Omni by pasting a standard connection URI instead of filling out the connection form manually. This method supports most common database types and automatically parses your connection details.

## Requirements

To use quick connect with a connection string, you'll need:

* **Organization Admin permissions in Omni**
* A connection string (URI) for your database in the standard format

## Supported databases

Quick connect supports the following databases:

* [ClickHouse](/connect-data/setup/clickhouse)
* [Databricks](/connect-data/setup/databricks)
* Exasol
* [MariaDB](/connect-data/setup/mariadb)
* [Microsoft SQL Server](/connect-data/setup/microsoftsql)
* [MySQL](/connect-data/setup/mysql)
* [PostgreSQL](/connect-data/setup/postgres)
* [Redshift](/connect-data/setup/redshift)
* [Snowflake](/connect-data/setup/snowflake)
* [StarRocks](/connect-data/setup/starrocks)
* Trino

<Note>
  Oracle connections require manual setup through the connection form to accept the license agreement.
</Note>

## Connection string format

Connection strings follow the standard URI format:

```text theme={null}
dialect://username:password@host:port/database
```

For databases that support additional parameters, add them as [query parameters](#database-specific-parameters):

```text theme={null}
dialect://username:password@host:port/database?parameter=value
```

<Tip>
  If your username or password contains special characters, they must be [URL-encoded in the connection string](#special-characters-in-credentials).
</Tip>

### Examples

<CodeGroup>
  ```text Databricks theme={null}
  databricks://token:dapi123abc@workspace.cloud.databricks.com:443/default?http_path=/sql/1.0/warehouses/abc123
  ```

  ```text Microsoft SQL Server theme={null}
  mssql://omni_user:password@db.example.com:1433/analytics?schema=dbo
  ```

  ```text MySQL theme={null}
  mysql://omni_user:password@db.example.com:3306/analytics
  ```

  ```text PostgreSQL theme={null}
  postgresql://omni_user:password@db.example.com:5432/analytics
  ```

  ```text Snowflake theme={null}
  snowflake://omni_user:password@account.snowflakecomputing.com/database?warehouse=COMPUTE_WH
  ```
</CodeGroup>

## Using quick connect

<Steps>
  <Step title="Prep the database">
    Before you start, prep your database for the connection. This can include:

    * Creating an Omni database user and granting permissions
    * Setting up a table upload schema (for CSV uploads)
    * Adding Omni's IP addresses to an allowlist

    Refer to the [setup guide](#supported-databases) for your database for more information.
  </Step>

  <Step title="Navigate to the new connection page">
    In Omni, go to **Settings > Connections** and click **New connection**.
  </Step>

  <Step title="Paste your connection string">
    <Tip>
      If your credentials contain any special characters, be sure to [URL-encode them](#special-characters-in-credentials) when adding the connection string in Omni.
    </Tip>

    At the bottom of the page, you'll see a quick connect input field. Paste your connection string and press **Connect**:

    <img alt="Quick connect input field on the new connection page" />

    Omni will automatically parse the connection details and create the connection.

    If the connection string format is invalid or missing required fields, an error message will display below the input. Error messages never include passwords for security.

    If you encounter a server error during connection creation, you'll be redirected to the connection form where you can review and adjust the settings.
  </Step>
</Steps>

## Database-specific parameters

Some databases support additional parameters in the connection string:

| Database             | Parameter   | Description                    | Example                                 |
| -------------------- | ----------- | ------------------------------ | --------------------------------------- |
| Snowflake            | `warehouse` | Snowflake warehouse name       | `?warehouse=COMPUTE_WH`                 |
| Snowflake            | `account`   | Snowflake account identifier   | Added automatically from host           |
| Microsoft SQL Server | `schema`    | Default schema                 | `?schema=dbo`                           |
| Databricks           | `http_path` | HTTP path to the SQL warehouse | `?http_path=/sql/1.0/warehouses/abc123` |

## Special characters in credentials

If your username or password contains special characters, they must be URL-encoded in the connection string:

| Character | Encoded value |
| --------- | ------------- |
| `@`       | `%40`         |
| `:`       | `%3A`         |
| `/`       | `%2F`         |
| `?`       | `%3F`         |
| `#`       | `%23`         |
| `&`       | `%26`         |

For example, if your password is `p@ss:word`, use `p%40ss%3Aword` in the connection string.

## What's next?

After creating your connection, you may want to:

* [Restrict schemas](/connect-data/schema-restriction) to limit which schemas are visible in Omni
* [Configure timezones](/connect-data/timezones) for your connection
* Set up [SSH tunnels](/connect-data/ssh-tunnels) or [AWS PrivateLink](/connect-data/aws-privatelink) for secure connections


# Connecting Amazon Redshift to Omni
Source: https://docs.omni.co/connect-data/setup/redshift

Learn how to create a database user, grant permissions, and connect your Amazon Redshift data warehouse to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in Redshift** that allow you to create database users and grant permissions

## Setup

<Steps>
  <Step title="Create a database user for Omni">
    In your Redshift database, run the following command to create a database user for Omni:

    ```sql title="Create an Omni database user" theme={null}
    CREATE USER omni WITH PASSWORD '<password>';
    GRANT USAGE ON SCHEMA '<schema_name>' TO omni;
    GRANT SELECT ON TABLE information_schema.tables TO omni;
    GRANT SELECT ON TABLE information_schema.columns TO omni;
    ```

    Next, run the following command for each schema you want to use in Omni:

    ```sql title="Grant Omni access to schemas" theme={null}
    GRANT SELECT ON ALL TABLES IN SCHEMA '<schema_name>' TO omni;
    ```

    <Tip>
      If you're using Redshift views via dbt, Omni may not be granted permissions if there are dependencies with other schemas. To grant access to those views, you'll also need to grant `SELECT` access to the views. If objects are declared as tables, they will be available in Omni.
    </Tip>
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). This schema can't be used for other modeled tables.

    1. Create the schema in Redshift.
    2. Run the following to grant the Omni user the required privileges:

       ```sql title="Grant Omni access to table upload schema" theme={null}
       GRANT USAGE, CREATE ON SCHEMA 'upload_schema_name' TO omni;
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the Redshift database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection. For Redshift, this typically means creating a security group and adding an inbound traffic rule for each IP address.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Redshift** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Database />

       <IncludeOther />

       <Include />

       <Offloaded />

       <TableUploads />

       <Default />

       <Username />

       <Password />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <QueryTimeout />

       <AlwaysScopeViewNames />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## Connecting to Redshift datashares

[Redshift data sharing](https://docs.aws.amazon.com/redshift/latest/dg/datashare-overview.html) lets you share data across Redshift databases and clusters. To make datashare tables available in Omni, you need to create an external schema in the database Omni connects to and grant the Omni user access to it.

### Create an external schema

In the consumer database (the one Omni connects to), run:

```sql title="Create an external schema for the datashare" theme={null}
CREATE EXTERNAL SCHEMA <external_schema_name>
FROM REDSHIFT DATABASE '<datashare_database_name>'
SCHEMA '<source_schema_name>';
```

Replace the following placeholders:

* `<external_schema_name>` — the name the schema will have in your local database
* `<datashare_database_name>` — the name of the shared database
* `<source_schema_name>` — the schema within the shared database to expose

### Grant the Omni user access

Grant the Omni user usage on the external schema:

```sql title="Grant schema access to the Omni user" theme={null}
GRANT USAGE ON SCHEMA <external_schema_name> TO omni;
```

If the datashare was created with the `WITH_PERMISSIONS` flag, you also need to grant usage on the shared database:

```sql title="Grant database access (WITH_PERMISSIONS datashares only)" theme={null}
GRANT USAGE ON DATABASE '<datashare_database_name>' TO omni;
```

### Verify Omni can see the tables

To confirm the external schema and its tables are visible to the Omni user, run the following queries as the Omni user:

```sql title="Verify table visibility" theme={null}
SELECT * FROM SVV_TABLES WHERE table_schema = '<external_schema_name>';
```

```sql title="Verify column visibility" theme={null}
SELECT column_name FROM SVV_COLUMNS WHERE table_schema = '<external_schema_name>';
```

If both queries return rows, Omni will be able to discover and model the datashare tables.

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting Snowflake to Omni
Source: https://docs.omni.co/connect-data/setup/snowflake

Learn how to create a database user, grant permissions, and connect your Snowflake data warehouse to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions** in Omni
* **Permissions in Snowflake** that allow you to:
  * Create database users and grant permissions
  * Allowlist IP addresses
  * Set up key-pair authentication

## Setup

<Steps>
  <Step title="Create a database user for Omni">
    1. Sign in to your Snowflake account.
    2. Create a new worksheet.
    3. Run the following to create a role and user for Omni, and grant privileges:

       ```sql title="Create Omni role & user and grant privileges" wrap theme={null}
       use role ACCOUNTADMIN;
       create role if not exists omni_role;
       create user if not exists omni_user;
       grant role omni_role to user omni_user;
       alter user omni_user set default_role = omni_role;
       alter user omni_user set type = service;
       alter user omni_user set default_warehouse = '<warehouse>';

       -- grant read only database access
       -- repeat for all database/schemas:
       grant usage, monitor on database <database> to role omni_role;
       grant usage, monitor on schema <database>.<schema> to role omni_role;
       grant usage, monitor on warehouse <warehouse> to role omni_role;

       -- alternatively, grant read only database
       -- access across all schemas:
       grant usage, monitor on database <database> to role omni_role;
       grant usage, monitor on all schemas IN DATABASE <database> to role omni_role;
       grant usage, monitor on future schemas IN DATABASE <database> to role omni_role;
       grant usage, monitor on warehouse <warehouse> to role omni_role;

       -- grant access to all tables
       -- in the schema to omni_role:
       grant select on all tables in schema <database>.<schema> to role omni_role;
       grant select on future tables in schema <database>.<schema> to role omni_role;

       -- grant access to all views
       -- in the schema to omni_role:
       grant select on all views in schema <database>.<schema> to role omni_role;
       grant select on future views in schema <database>.<schema> to role omni_role;

       -- (optional) grant access to dynamic tables
       -- in the schema to omni_role:
       grant select on all dynamic tables in schema <database>.<schema> to role omni_role;
       grant select on future dynamic tables in schema <database>.<schema> to role omni_role;

       -- (optional) required to use the Model Assistant's 
       -- "Suggest model from query history" skill
       grant imported privileges on database SNOWFLAKE TO ROLE omni_role;

       -- grant ownership of omni_role to omni_user:
       grant role omni_role to user omni_user;
       ```

    <Note>
      Omni supports [Snowflake semantic views](/connect-data/snowflake-semantic-views), but they require additional connection settings to enable. If you use semantic views, refer to the setup guide after completing your connection.
    </Note>
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated schema to use for [table uploads](/analyze-explore/data-input-csvs). This schema can't be used for other modeled tables.

    1. Create the schema in Snowflake. This can be in its own database or the same database as other schemas to be used in modeling.
    2. Run the following commands to grant the Omni user the required privileges:
       ```sql title="Grant Omni user permissions to upload schema" theme={null}
       grant usage on database <upload_database> to role omni_role;
       grant usage, create table on schema <upload_database>.<csv_schema> to role omni_role;
       ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the Snowflake database is [limited by IP address](https://docs.snowflake.com/en/user-guide/network-policies), you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Retrieve your Snowflake account identifier">
    1. In Snowflake, click your user icon in the bottom left corner of the page and then hover over **Account**.
    2. In the account selector, click the **View account details** link under the account:
       <img alt="Account identifier" />
    3. In the **Account Details** dialog, locate and copy the **Account Identifier**.

    Refer to the [Snowflake documentation](https://docs.snowflake.com/user-guide/admin-account-identifier#finding-the-organization-and-account-name-for-an-account) for information about Snowflake account identifiers.
  </Step>

  <Step title="Create the connection in Omni">
    <Note>
      Snowflake connection parameters can be case sensitive and are often capitalized. If you see errors on connection, confirm your connection parameters match your Snowflake environment exactly.
    </Note>

    1. In Omni, click **Settings > Connections**.
    2. Click the **Snowflake** option.
    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <ParamField>
         Controls how you provide warehouse information to Omni. Supported options are an **Account Identifier** or a **Host and Port**.

         <Expandable title="Account Identifier">
           <ParamField>
             Your Snowflake account identifier. Required if **Host Type** is **Account Identifier**.
           </ParamField>
         </Expandable>

         <Expandable title="Host and Port">
           <ParamField>
             The full hostname for your Snowflake instance (e.g., `youraccount.snowflakecomputing.com`). Required if **Host Type** is **Host and Port**.
           </ParamField>

           <Port />
         </Expandable>
       </ParamField>

       <ParamField>
         The Snowflake warehouse to use for queries.

         <Note>
           **OAuth connections only**: You can leave this field blank to use each user's `DEFAULT_WAREHOUSE` setting from Snowflake. This enables per-user warehouse routing for organizations using Snowflake's role-to-warehouse mappings for cost attribution. Non-OAuth connections (password, keypair, or PAT) still require a warehouse value.
         </Note>
       </ParamField>

       <Database />

       <Include />

       <IncludeOther />

       <Offloaded />

       <TableUploads />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <QueryTimeout />

       <AutoGenerateRelationshipsAllModes />

       <AlwaysScopeViewNames />

       <ParamField>
         The type of authentication to use.

         <AccordionGroup>
           <Accordion title="Programmatic access token (PAT)" icon="ticket">
             Snowflake [programmatic access tokens](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) (PATs) provide a secure, non-interactive way to authenticate to Snowflake without a traditional password.
             To use a PAT, select **Password** as the authentication type and enter:

             * **Username** - The Omni database user you created in step 1.
             * **Password** - Paste the Snowflake PAT value.
               No additional configuration is needed — PATs work out of the box in the password field.
           </Accordion>

           <Accordion title="Key-pair authentication" icon="key">
             To use this authentication type, you'll need to specify a **Username** and set up a key-pair:

             * **Username** - This is the Omni database user you created in step 1.
             * **Key-pair configuration** - Click the link to set up keys for the connection. Refer to step 6 for more information.
           </Accordion>

           <Accordion title="Password authentication" icon="passport">
             Password authentication uses a **username** and **password** to authenticate to Snowflake.

             <Warning>
               Snowflake is [phasing out single-factor password authentication](https://docs.snowflake.com/en/user-guide/security-mfa-rollout), with full enforcement expected by October 2026. Use a programmatic access token or key-pair authentication instead to meet their enforcement deadlines.
             </Warning>
           </Accordion>
         </AccordionGroup>
       </ParamField>

       <BaseAccess />
    4. When finished, click **Create connection**.
  </Step>

  <Step title="Set up Snowflake key-pair authentication">
    If you selected **Keypair authentication** as the [**Authentication type**](#param-authentication-type), you'll need to configure keys before you can save the connection.

    Omni can generate the keypair for you, or you can provide an existing [private key](https://docs.snowflake.com/en/user-guide/key-pair-auth#generate-the-private-key).

    <Note>
      Running `alter user omni_user set RSA_PUBLIC_KEY='...'` replaces any key currently assigned to that slot on the Snowflake user. If `omni_user` already has an active key you need to preserve during a rotation, assign the new public key to the second slot instead by running `alter user omni_user set RSA_PUBLIC_KEY_2='...'`. Refer to Snowflake's [key-pair rotation guide](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation) for the full rotation flow.
    </Note>

    <AccordionGroup>
      <Accordion title="Omni-generated key-pair" description="Let Omni generate the key-pair on your behalf" icon="o">
        1. In the **Keypairs** tab, click **Generate key-pair**.

        2. Click **Copy** next to the public key.

        3. Navigate back to your Snowflake account and run:

           ```sql wrap theme={null}
           alter user omni_user set RSA_PUBLIC_KEY='COPIED_PUBLIC_KEY';
           ```

           If the `omni_user` has an existing key and you need to rotate keys, run the following instead:

           ```sql wrap theme={null}
           alter user omni_user set RSA_PUBLIC_KEY_2='COPIED_PUBLIC_KEY';
           ```

        4. In the **Keypair** tab in Omni, click the toggle in the **Active** column to enable the keypair.
      </Accordion>

      <Accordion title="Existing private key" description="Provide an existing private key" icon="key">
        <Tip>
          Omni only supports RSA private keys without passphrases.
        </Tip>

        1. In the **Keypairs** tab, click **Add existing key**.
        2. Paste the private key into the dialog. For example:
           ```shell theme={null}
           -----BEGIN PRIVATE KEY-----
           MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCXHK07oaqx8fnY
           r3UbfUS6HRXQFRvQ0J8qqzgq+UH4ZqtgxV44ciSOwzL65E2aZrixXxB+s7Kbbw1q
           ...
           ...
           fAPCZRg8vdG8Hp26PwXxybZ/M9u7NaKJ0BT4AwKKtZTUxZVxz/kPhdHT+MpoQqJf
           JuzuwXVAAcl1GME2OiqkZhww
           -----END PRIVATE KEY-----
           ```
           **Note**: Omni will automatically add `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` if the key doesn't have them.
        3. Click **Add keypair**. Omni will automatically generate the public key and redirect you back to the **Keypairs** tab.
        4. Click **Copy** next to the newly-generated public key.
        5. Navigate back to your Snowflake account and run the following:

           ```sql wrap theme={null}
           alter user omni_user set RSA_PUBLIC_KEY='COPIED_PUBLIC_KEY';
           ```

           If the `omni_user` has an existing key and you need to rotate keys, run the following instead:

           ```sql wrap theme={null}
           alter user omni_user set RSA_PUBLIC_KEY_2='COPIED_PUBLIC_KEY';
           ```
        6. In the **Keypair** tab in Omni, click the toggle in the **Active** column to enable the keypair.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection

- If you use Snowflake semantic views, refer to [Snowflake semantic views](/connect-data/snowflake-semantic-views#setup) for additional setup steps to import and query them in Omni.
- Use the Model Assistant's [Suggest model from query history skill](/ai/model-assistant#suggest-model-from-query-history) to generate semantic models based on actual SQL query patterns run against the database


# Connecting Starburst Galaxy to Omni
Source: https://docs.omni.co/connect-data/setup/starburst-galaxy

Learn how to create a dedicated Starburst Galaxy user, grant privileges, and connect your Galaxy cluster to Omni.

This guide covers connecting Omni to [Starburst Galaxy](https://www.starburst.io/starburst-galaxy/), Starburst's managed Trino service.

<Note>
  In Trino, a **catalog** is what other databases call a database — it's a configured connection to an underlying data source (such as Iceberg, Hive, Postgres, or Snowflake). A Trino cluster can expose multiple catalogs, each containing schemas and tables. Throughout this guide, the Omni connection field labeled **Database** refers to a Trino catalog.
</Note>

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions in Omni
* **In Starburst Galaxy**:
  * Permissions that allow you to create roles, users, and assign privileges. The `accountadmin` role includes all these permissions.
  * An existing Galaxy cluster

## Setup

<Steps>
  <Step title="Create a Galaxy role for Omni">
    In this step, you'll [create a dedicated Galaxy role](https://docs.starburst.io/starburst-galaxy/security-and-compliance/manage-galaxy-access/manage-users-roles-and-tags/index.html#add-a-role) for Omni. You'll assign privileges to the role in a later step.

    1. In Galaxy, navigate to **Access > Roles and privileges**.
    2. Click **Create role**.
    3. Enter a name (for example, `omni`) and an optional description.
    4. Check the **Grant to the creating role** checkbox. This grants the new role to your current role so that you can continue to administer it.
    5. Click **Create role**.
  </Step>

  <Step title="Grant privileges to the role">
    Next, you'll grant privileges to the Omni role that will allow it to access the cluster and the catalogs and schemas it contains.

    <Steps>
      <Step title="Grant cluster access to the role">
        Start by granting the role permission to run queries on the cluster Omni will connect to.

        1. On the **Roles and privileges** page, click the `omni` role you just created.
        2. Open the **Privileges** tab.
        3. Click **Add privileges**.
        4. Click the **Cluster** tab.
        5. In the **Cluster alias** dropdown, select the cluster Omni will connect to.
        6. Set **Do you want to allow access?** to **Allow**.
        7. Under **What can they do?**, select **Use cluster**. The dialog should look like the following:

           <Frame>
             <img alt="Configured cluster access privileges for the Omni role in the Starburst Galaxy UI" />
           </Frame>
      </Step>

      <Step title="Grant data privileges to the role">
        Next, grant the role [access to the catalogs and schemas](https://docs.starburst.io/starburst-galaxy/security-and-compliance/manage-data-access/data-privileges.html) you want to model in Omni.

        1. Still on the **Add privileges** dialog, click the **Data** tab.

        2. In the **Scope** dropdown, select a catalog you want Omni to access.

           You can also toggle a catalog open to grant access on a per-schema basis:

           <Frame>
             <img alt="List of schemas in a catalog in the Starburst Galaxy UI" />
           </Frame>

        3. Set **Do you want to allow access?** to **Allow**.

        4. Under **What can they do?**, select **Select from table**. The dialog should look like the following:

           <Frame>
             <img alt="Configured data access privileges for the Omni role in the Starburst Galaxy UI" />
           </Frame>

        5. Repeat this for every catalog and schema you want Omni to query.

        6. Click **Save privileges**.
      </Step>
    </Steps>
  </Step>

  <Step title="Create the Omni user in Galaxy">
    Next, you'll create a dedicated Galaxy user for Omni and assign it the role you configured.

    1. In Galaxy, navigate to **Access > Users**.

    2. Click **Create user**.

    3. Enter an email address for the new user (for example, `omni@yourcompany.com`).

       <Note>
         Galaxy will send an invitation email to this address. You'll need access to the inbox to complete the account setup and set a password.
       </Note>

    4. In **Roles**, select the `omni` role you created earlier.

    5. In **Default role**, select the `omni` role. The dialog should look like the following:

       <Frame>
         <img alt="Initial settings for creating an Omni user in the Starburst Galaxy UI" />
       </Frame>

    6. Click **Add user**.

    7. Open the invitation email and follow the link to set the user's password. Save the password somewhere secure — you'll need it when configuring the Omni connection.
  </Step>

  <Step title="Set up a table upload schema">
    <Callout icon="hand-point-up">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    To use [table uploads](/analyze-explore/data-input-csvs), the [Galaxy `omni` role](#create-omni-role) needs write access to a dedicated schema in a writable catalog. This schema can't be used for other modeled tables.

    Generally, the steps to set up a table upload schema will look like:

    1. Verify that the Galaxy connector (data source) associated with the catalog supports write operations. Some connectors - like Google Sheets and Salesforce - are read-only and can't be used for table uploads.
    2. In the underlying data source (e.g., Postgres, MySQL), create a schema in a catalog that the Galaxy `omni` role has access to.
    3. Verify that the new schema is accessible to Galaxy.
    4. In Galaxy, add privileges to the [Galaxy `omni` role](#grant-data-access) that will allow the Omni Galaxy user to:
       * Access the catalog and schema used for table uploads
       * Create new tables in the schema
       * Select from, insert into, update, and delete from tables in the schema
  </Step>

  <Step title="Get the connection details from Galaxy">
    1. In Galaxy, navigate to **Partner connect**.
    2. Click the **Connection info** section to open it.
    3. Select the cluster you want to connect to Omni.
    4. In the **Other clients** section, note the **Host** and **Port** values — you'll need these in the next step. The port for Galaxy is always `443`.

    <Frame>
      <img alt="Highlighted Other Clients connection info in the Starburst Galaxy UI" />
    </Frame>
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If your Galaxy cluster restricts access by IP address, add Omni's IPs to the allowlist.

    Omni's IP addresses can be found on an individual connection's page in Omni, accessed by navigating to **Settings > Connections** and clicking a connection.

    If your cluster doesn't restrict access by IP, skip this step.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Trino** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <ParamField>
         The name of the Trino catalog Omni should connect to.
       </ParamField>

       <IncludeOther />

       <Default />

       <Offloaded />

       <TableUploads />

       <ParamField>
         The Omni Starburst user's email address, followed by `/` and the role name. The role suffix tells Galaxy which role to use for the session. The `omni` role should be the default for this user, but adding the role suffix explicitly sets the role.

         For example, if the user is `omni@yourcompany.com` and the role is `omni`, enter `omni@yourcompany.com/omni`.
       </ParamField>

       <Password />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <TrustServerCertificate />

       <AutoGenerateRelationshipsAllModes />

       <AlwaysScopeViewNames />

       <BaseAccess />

    4. When finished, click **Create connection**.

    <Note>
      Galaxy clusters auto-suspend after an idle period (configurable per cluster). The first query Omni runs after suspension will be slower while Galaxy resumes the cluster. This is expected behavior and doesn't require any additional setup.
    </Note>
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting StarRocks to Omni
Source: https://docs.omni.co/connect-data/setup/starrocks

Learn how to create a database user, grant permissions, and connect your StarRocks database to Omni.

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Permissions in StarRocks** that allow you to create database users

## Setup

<Steps>
  <Step title="Create a database user for Omni">
    In your StarRocks database, run the following command to create a database user for Omni:

    ```sql title="Create Omni user" theme={null}
    CREATE USER omni IDENTIFIED WITH mysql_native_password BY '<password>';
    ```

    Next, run the following command to grant the Omni user access to the database:

    ```sql title="Grant SELECT permissions to Omni user" theme={null}
    GRANT SELECT ON <database_name>.* TO 'omni'@'%';
    ```
  </Step>

  <Step title="Allowlist Omni's IP addresses">
    If access to the StarRocks database is limited by IP address, you'll need to add Omni's IPs to the allowlist before you create the database connection.

    Omni's IP addresses can be found on an individual connection's page, accessed by navigating to **Settings > Connections** and clicking a connection.
  </Step>

  <Step title="Create the connection in Omni">
    1. In Omni, click **Settings > Connections**.

    2. Click the **StarRocks** option.

    3. On the connection setup page, fill in the connection details:

       <DisplayName />

       <Host />

       <Port />

       <Default />

       <Include />

       <Offloaded />

       <TableUploads />

       <Username />

       <Password />

       <DatabaseTimezone />

       <QueryTimezone />

       <AllowUserSpecificTimezones />

       <AutoGenerateRelationships />

       <QueryTimeout />

       <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection


# Connecting to Snowflake using AWS or Azure PrivateLink
Source: https://docs.omni.co/connect-data/snowflake-privatelink

Connect Omni to your Snowflake instance over a private network using AWS PrivateLink or Azure Private Link endpoints.

Omni can connect to your Snowflake instance in Amazon Web Services (AWS) or Azure via PrivateLink. In this configuration, Omni establishes an encrypted connection from our network to the Snowflake network.

## Requirements

To follow the steps in this guide, you'll need:

* Snowflake Business Critical or higher (PrivateLink is not available on Standard or Enterprise editions)
* A Snowflake user with the `ACCOUNTADMIN` role

Additionally, your Snowflake account should be on the same cloud provider as your Omni instance. For example, if Omni is hosted on AWS, your Snowflake account should also be on AWS.

## Setup

The setup process is slightly different between AWS and Azure. Follow the section for your Snowflake account's cloud provider.

### AWS setup

Before Omni can provision anything, Snowflake must authorize Omni's connection at the AWS account level. You'll need to open a support ticket with Snowflake to start this process, as self-service `SYSTEM$AUTHORIZE_PRIVATELINK` is not available for third-party vendors like Omni on AWS.

<Steps>
  <Step>
    Open a Snowflake support case asking them to add Omni's AWS account ID `767117061426` to your account's PrivateLink allow list.

    Reference [Snowflake's AWS PrivateLink documentation](https://docs.snowflake.com/en/user-guide/admin-security-privatelink#enable-aws-privatelink) for more information.
  </Step>

  <Step>
    Once Snowflake confirms the authorization, as `ACCOUNTADMIN`, run the following in Snowflake and save the JSON output:

    ```sql theme={null}
    select SYSTEM$GET_PRIVATELINK_CONFIG();
    ```
  </Step>

  <Step>
    Contact Omni support with:

    * The JSON output from step 2
    * Your Snowflake account's AWS region
  </Step>

  <Step>
    Omni will create the AWS VPC endpoint and finish wiring up your Snowflake connection. Omni will notify you when the connection is ready to use.
  </Step>
</Steps>

### Azure setup

On Azure, Omni creates the Private Endpoint first, and you authorize it after the fact by running SQL commands that Omni provides.

<Steps>
  <Step>
    As `ACCOUNTADMIN`, run the following in Snowflake and save the JSON output:

    ```sql theme={null}
    select SYSTEM$GET_PRIVATELINK_CONFIG();
    ```
  </Step>

  <Step>
    Contact Omni support with:

    * The JSON output from step 1
    * Your Snowflake account's Azure region
  </Step>

  <Step>
    Omni will create the Azure Private Endpoint.
  </Step>

  <Step>
    Omni will also send you two SQL commands that look like the following:

    ```sql wrap theme={null}
    select SYSTEM$AUTHORIZE_PRIVATELINK('<pe-resource-id>', '<federated-token>');
    select SYSTEM$AUTHORIZE_STAGE_PRIVATELINK_ACCESS('<pe-resource-id>');
    ```

    Run both commands in Snowflake as `ACCOUNTADMIN`. The Private Endpoint connection will move from `Pending` to `Approved`.
  </Step>

  <Step>
    Omni will finish wiring up your Snowflake connection. Omni will notify you when the connection is ready to use.
  </Step>
</Steps>

## References

* [Snowflake — AWS PrivateLink](https://docs.snowflake.com/en/user-guide/admin-security-privatelink)
* [Snowflake — Azure Private Link](https://docs.snowflake.com/en/user-guide/privatelink-azure)


# Getting started with Snowflake semantic views
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/index

Import Snowflake semantic views as topics and query them in Omni. Requirements and setup steps.

Omni imports each Snowflake semantic view as a topic, with the semantic view's field definitions, relationships, and AI instructions. You keep your semantic definitions in one place — Snowflake — and explore and visualize them in Omni. Changes to a semantic view in Snowflake reach Omni on the next [schema refresh](/modeling/develop/schema-refreshes).

## What you can do with Snowflake semantic views in Omni

<CardGroup>
  <Card title="Sync semantic views to Omni" icon="arrows-rotate" href="/connect-data/snowflake-semantic-views/sync/trigger-sync">
    Run a schema refresh to import semantic views as topics, and see what each part of a definition becomes in Omni.
  </Card>

  <Card title="Query a semantic view topic" icon="magnifying-glass-chart" href="/connect-data/snowflake-semantic-views/querying">
    Find the imported topics and explore them in workbooks.
  </Card>

  <Card title="Push Omni topics to Snowflake" icon="arrow-up-from-bracket" href="/connect-data/snowflake-semantic-views/push-to-snowflake">
    Convert a topic you built in Omni into a Snowflake semantic view definition.
  </Card>
</CardGroup>

## Requirements

To use this integration, you'll need:

* Semantic views created in your Snowflake account
* **Organization Admin** or **Connection Admin** permissions on the Snowflake connection in Omni. This is required to modify the connection's settings.
* An existing [Snowflake connection in Omni](/connect-data/setup/snowflake)

## Setup

Follow these steps to import the semantic views on a Snowflake connection as Omni topics.

<Steps>
  <Step title="Grant database permissions">
    1. Confirm that the Omni user role has the permissions outlined in [step 1 of the Snowflake setup guide](/connect-data/setup/snowflake#create-a-database-user-for-omni). This must include read access to the schemas, tables, and views that back your semantic views.
    2. Grant the Omni user role read access to your semantic views. Semantic views are their own object type in Snowflake, so grants on tables and views don't cover them:

       ```sql title="Snowflake semantic view user grants" theme={null}
       grant usage on database <database> to role omni_role;
       grant usage on schema <database>.<schema> to role omni_role;
       grant select, references on all semantic views in schema <database>.<schema> to role omni_role;
       grant select, references on future semantic views in schema <database>.<schema> to role omni_role;
       ```
  </Step>

  <Step title="Include the schema in your connection">
    In your Omni connection settings, make sure the schema containing your semantic views is included:

    1. Navigate to **Settings > Connections** and click your Snowflake connection.
    2. Verify that the schema is listed in the **Include Other Databases** or default database configuration.
  </Step>

  <Step title="Enable the semantic view setting">
    In your Omni connection settings, scroll to the bottom of the page and enable the **Enable DW Semantic View Integration** setting. This makes semantic views available in workbooks and the model IDE.
  </Step>

  <Step title="Update the connection and refresh the schema">
    1. Click **Update and Test Connection** to save your connection settings and verify the connection.
    2. Run a [schema refresh](/modeling/develop/schema-refreshes) on the model associated with this connection.

    After the schema refresh completes, your semantic views appear in the model as topics.
  </Step>
</Steps>

## Limitations

Some parts of a semantic view definition don't import, and some import in a fixed way. See [Snowflake semantic view limitations](/connect-data/snowflake-semantic-views/limitations) before you rely on a topic.

## Next steps

* Learn [what a schema refresh creates for each semantic view](/connect-data/snowflake-semantic-views/sync/trigger-sync)
* [Query a semantic view topic](/connect-data/snowflake-semantic-views/querying)
* Resolve [schema refresh warnings and missing topics](/connect-data/snowflake-semantic-views/sync/trigger-sync#troubleshooting)
* Check the [limitations](/connect-data/snowflake-semantic-views/limitations) of imported topics


# Snowflake semantic view limitations
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/limitations

What Omni doesn't import from a Snowflake semantic view, and what imports in a fixed way.

Omni imports most of a Snowflake semantic view definition. This page lists the parts that don't import, and the parts that import in a fixed way. If you need one of these, reach out to Omni support.

## Verified queries aren't imported

Verified queries defined on a semantic view don't import. The generated topic has no [`sample_queries`](/modeling/topics/parameters/sample-queries).

## Relationships always import as `many_to_one`

Snowflake doesn't expose the cardinality of a relationship, so every relationship imports with [`relationship_type: many_to_one`](/modeling/relationships/parameters/relationship-type) from the foreign-key table to the referenced table.

## ASOF and RANGE relationships aren't imported

`ASOF` and `RANGE` relationships aren't imported. The topic imports without those joins. A view left with no relationship to the rest of the topic gets a [validation warning](/connect-data/snowflake-semantic-views/sync/trigger-sync#troubleshooting).

## Topics don't follow dbt virtual schemas

Semantic view topics query the tables named in the semantic view's definition, so switching your dbt environment doesn't change what they read. Use [`included_schemas`](/modeling/models/included-schemas) to import from your production schema only. Topics can't follow [dbt virtual schemas](/integrations/dbt/virtual-schemas).

## Next steps

* Learn [what Omni creates for each semantic view](/connect-data/snowflake-semantic-views/sync/trigger-sync)
* See [what each part of a definition becomes in Omni](/connect-data/snowflake-semantic-views/sync/metadata-reference)
* [Query a semantic view topic](/connect-data/snowflake-semantic-views/querying)


# Pushing Omni topics to Snowflake
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/push-to-snowflake

Use the omni-to-snowflake-semantic-view agent skill to convert an Omni topic into a Snowflake semantic view definition.

The [`omni-to-snowflake-semantic-view` agent skill](https://github.com/exploreomni/omni-agent-skills/tree/main/skills/omni-integrations/skills/omni-to-snowflake-semantic-view) converts an Omni topic into a Snowflake semantic view. Run it in an AI agent such as Claude Code, Cursor, OpenAI Codex, or Snowflake Cortex Code. See [Agent skills](/developers/agent-skills) for installation.

The skill:

1. Reads the topic, its views, and its relationships through the Omni API.
2. Translates them into a semantic view YAML definition — dimensions, time dimensions, facts, metrics, filters, and relationships, with descriptions and synonyms.
3. Creates the semantic view in Snowflake with [`SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML`](https://docs.snowflake.com/en/sql-reference/stored-procedures/system_create_semantic_view_from_yaml), using your Snowflake connection or CLI.

After the semantic view exists in Snowflake, run a [schema refresh](/modeling/develop/schema-refreshes) to import it as a topic. See [Setup](/connect-data/snowflake-semantic-views#setup) for the grants and connection settings the import needs.

## Next steps

* Learn [what Omni creates for each semantic view](/connect-data/snowflake-semantic-views/sync/trigger-sync)
* Look up [what each part of a definition becomes in Omni](/connect-data/snowflake-semantic-views/sync/metadata-reference)
* Resolve [schema refresh warnings and query messages](/connect-data/snowflake-semantic-views/sync/trigger-sync#troubleshooting)


# Querying Snowflake semantic view topics
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/querying

Where imported Snowflake semantic view topics appear in Omni and how to query them in workbooks.

After a [schema refresh](/modeling/develop/schema-refreshes) imports your semantic views, each one is a topic you can query like any other. This page covers where the topics appear and what to expect when querying them.

## Where the topics appear

Imported topics carry a **Snowflake mark** in the topic picker, field browser, and model IDE; hover it to see the fully qualified semantic view name. In the IDE file browser they sit in a **Snowflake Semantic Views** folder. Set a [`group_label`](/modeling/topics/parameters/group-label) to move one into a group of your own.

## Querying a semantic view topic

In a workbook, pick the topic and select fields as in any other topic. Filtered measures, level-of-detail calculations, dynamic top N, column totals, period-over-period comparisons, pivots, and [composite topics](/modeling/composite-topics) all work.

Metrics use [symmetric aggregates](/analyze-explore/sql/symmetric-aggregates) keyed on the `PRIMARY KEY` of the logical table the metric reads from, so a metric queried across a one-to-many join counts each row once.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Query messages on a semantic view topic">
    | Message                                                                                                                                                                                                              | What to do                                                                                              |
    | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
    | `No single join path connects all of "<view>", "<view>" in topic "<topic>". ...` — the selected fields sit on views the relationships don't connect in one direction, such as two fact tables that share a dimension | Add a field from the table that holds the foreign keys, or run separate queries.                        |
    | `"<field>" uses a window function, which Omni doesn't support on semantic view topics yet. ...` — also appears as `uses an aggregate in a dimension` and `nests one aggregate inside another`                        | Remove the field. A metric that references another metric, such as `${orders.count} + 1`, is supported. |
    | `Add a field from the topic to the query before saving this calculation to the workbook`                                                                                                                             | Add a field from the topic, then save the calculation.                                                  |
  </Accordion>

  <Accordion title="A metric is too high when combined with fields from another table">
    [Symmetric aggregates](/analyze-explore/sql/symmetric-aggregates) key on the logical table's `PRIMARY KEY`. Check that the logical table in the semantic view declares one, then run a [schema refresh](/modeling/develop/schema-refreshes).
  </Accordion>
</AccordionGroup>

## Next steps

* Learn [what Omni creates for each semantic view](/connect-data/snowflake-semantic-views/sync/trigger-sync)
* Look up [what each part of a definition becomes in Omni](/connect-data/snowflake-semantic-views/sync/metadata-reference)
* [Push a topic you built in Omni to Snowflake](/connect-data/snowflake-semantic-views/push-to-snowflake)


# Snowflake semantic view example
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/sync/example

A Snowflake semantic view definition and the Omni topic generated from it, covering comments, synonyms, filters, and AI instructions.

This page shows a Snowflake semantic view definition and the topic Omni generates from it. The semantic view uses comments, synonyms, a filter-labeled fact, and AI instructions. For the full mapping behind each line, see the [metadata reference](/connect-data/snowflake-semantic-views/sync/metadata-reference).

```sql title="Snowflake semantic view" theme={null}
CREATE SEMANTIC VIEW ANALYTICS.SALES.ORDERS_USERS
  TABLES (
    ORDERS AS ANALYTICS.SALES.RAW_ORDERS PRIMARY KEY (ORDER_ID) COMMENT = 'One row per order',
    USERS  AS ANALYTICS.SALES.RAW_USERS  PRIMARY KEY (USER_ID)
  )
  RELATIONSHIPS (
    ORDERS_TO_USERS AS ORDERS (USER_ID) REFERENCES USERS (USER_ID)
  )
  FACTS (
    ORDERS.AMOUNT AS AMOUNT,
    ORDERS.LARGE_ORDER LABELS = (FILTER) AS AMOUNT > 500 COMMENT = 'Orders over $500'
  )
  DIMENSIONS (
    ORDERS.STATUS AS STATUS,
    USERS.REGION AS REGION WITH SYNONYMS ('territory')
  )
  METRICS (
    ORDERS.TOTAL_REVENUE AS SUM(AMOUNT) WITH SYNONYMS ('sales') COMMENT = 'Gross order value'
  )
  COMMENT = 'Orders joined to their users'
  AI_QUESTION_CATEGORIZATION = 'Questions about orders, revenue, or customers belong here.'
  AI_SQL_GENERATION = 'Revenue means TOTAL_REVENUE. Filter on STATUS = ''COMPLETE'' unless asked otherwise.'
```

Omni generates this topic. `SALES` is the connection's default schema, so the names are not schema-prefixed:

```yaml title="orders_users.topic" theme={null}
semantic_view: ANALYTICS.SALES.ORDERS_USERS
label: Orders Users
description: Orders joined to their users
ai_context: |
  Use these instructions for question categorization: Questions about orders, revenue, or customers belong here.

  Use these instructions for SQL generation: Revenue means TOTAL_REVENUE. Filter on STATUS = 'COMPLETE' unless asked otherwise.

relationships:
  - join_from_view: orders_users__orders
    join_to_view: orders_users__users
    on_sql: ${orders_users__orders.user_id} = ${orders_users__users.user_id}
    relationship_type: many_to_one

views:
  orders_users__orders:
    label: Orders
    description: One row per order
    table_name: RAW_ORDERS
    dimensions:
      order_id:
        sql: '"ORDER_ID"'
        primary_key: true
        hidden: true
      user_id:
        sql: '"USER_ID"'
        hidden: true
      status:
        sql: '"STATUS"'
      amount:
        sql: '"AMOUNT"'
      large_order:
        sql: ${orders_users__orders.amount} > 500
        description: Orders over $500
        hidden: true
    filters:
      large_order__filter:
        bind_to: large_order
        label: Large Order
        group_label: Filters
        description: Orders over $500
    measures:
      total_revenue:
        sql: SUM(${orders_users__orders.amount})
        description: Gross order value
        synonyms: [sales]

  orders_users__users:
    label: Users
    table_name: RAW_USERS
    dimensions:
      user_id:
        sql: '"USER_ID"'
        primary_key: true
        hidden: true
      region:
        sql: '"REGION"'
        synonyms: [territory]
```

`large_order` is hidden; users apply `large_order__filter` from the **Filters** group.

## Next steps

* Look up [what each part of a definition becomes in Omni](/connect-data/snowflake-semantic-views/sync/metadata-reference)
* Learn [what Omni creates for each semantic view](/connect-data/snowflake-semantic-views/sync/trigger-sync)
* Resolve [schema refresh warnings and query messages](/connect-data/snowflake-semantic-views/sync/trigger-sync#troubleshooting)


# Snowflake semantic view metadata reference
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/sync/metadata-reference

A complete list of what each part of a Snowflake semantic view definition becomes in the topic Omni generates from it.

Omni reads a semantic view's definition and writes it into the [topic](/modeling/topics) it generates. This page lists what each part of the definition becomes in Omni.

## What Snowflake metadata becomes in Omni

| From Snowflake                                              | In Omni                                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMMENT` on the semantic view, a logical table, or a field | [`description`](/modeling/topics/parameters/description) on the topic, view, or field                                                                                                                                                                                               |
| `SEMANTIC_VIEWS.AI_QUESTION_CATEGORIZATION`                 | Topic [`ai_context`](/modeling/topics/parameters/ai-context), prefixed `Use these instructions for question categorization: `                                                                                                                                                       |
| `SEMANTIC_VIEWS.AI_SQL_GENERATION`                          | Topic `ai_context`, prefixed `Use these instructions for SQL generation: `                                                                                                                                                                                                          |
| `WITH SYNONYMS` on a dimension or metric                    | [`synonyms`](/modeling/dimensions/parameters/synonyms) on the field                                                                                                                                                                                                                 |
| `DIMENSIONS` and `FACTS`                                    | [Dimensions](/modeling/dimensions) on the logical table's view                                                                                                                                                                                                                      |
| `METRICS`                                                   | [Measures](/modeling/measures) on the logical table's view                                                                                                                                                                                                                          |
| `LABELS = (FILTER)`                                         | A [filter-only field](/modeling/filters) named `<field>__filter` that users can apply in workbooks. It uses [`bind_to`](/modeling/templated-filters#bind_to) to apply the filter through a [hidden](/modeling/dimensions/parameters/hidden) dimension holding the fact's expression |
| `PRIMARY KEY`                                               | [`primary_key: true`](/modeling/dimensions/parameters/primary-key) on the key dimension, or [`custom_compound_primary_key_sql`](/modeling/views/parameters/custom-compound-primary-key-sql) for a compound key                                                                      |
| Key columns not declared as dimensions                      | [Hidden](/modeling/dimensions/parameters/hidden) dimensions, so keys and joins resolve                                                                                                                                                                                              |
| `RELATIONSHIPS`                                             | [Relationships](/modeling/relationships) from the foreign-key table to the referenced table                                                                                                                                                                                         |
| Logical table defined by an inline SQL query                | A [SQL view](/modeling/views/parameters/sql) with the declared dimensions and metrics                                                                                                                                                                                               |

## Next steps

* See a [semantic view and the topic Omni generates from it](/connect-data/snowflake-semantic-views/sync/example)
* Learn [what Omni creates for each semantic view](/connect-data/snowflake-semantic-views/sync/trigger-sync)


# Syncing Snowflake semantic views
Source: https://docs.omni.co/connect-data/snowflake-semantic-views/sync/trigger-sync

Run a schema refresh to import Snowflake semantic views as topics, and learn what Omni creates for each one.

A [schema refresh](/modeling/develop/schema-refreshes) imports the semantic views on your Snowflake connection. Each semantic view arrives in Omni as one [topic](/modeling/topics). Its logical tables become views scoped to that topic, and its `RELATIONSHIPS` clause becomes the topic's relationships.

## Requirements

To sync semantic views, you'll need:

* A connection with the [integration set up](/connect-data/snowflake-semantic-views#setup)
* **Modeler** or **Connection Admin** permissions, which are required to [trigger schema refreshes](/modeling/develop/schema-refreshes#requirements)

## Triggering a sync

To sync, run a schema refresh on the model associated with the Snowflake connection. Omni imports new semantic views and updates topics whose semantic view changed in Snowflake. See [Schema refreshes](/modeling/develop/schema-refreshes) to learn how to trigger one manually or on a schedule.

If a semantic view is skipped, the schema refresh shows a warning. See [Troubleshooting](#troubleshooting) for each warning and how to resolve it.

## What Omni creates

One `.topic` file per semantic view:

* **`semantic_view` replaces [`base_view`](/modeling/topics/parameters/base-view).** The value is the fully qualified `CATALOG.SCHEMA.NAME` of the source. Because there is no fixed base view, Omni joins in only the views each query needs.
* **Views and relationships belong to the topic**, not the model, so they stay scoped to the semantic view they came from.
* **Names are schema-qualified when needed.** For a semantic view outside the connection's default schema, Omni prefixes the topic and view names with the schema (`sales__orders_users`), so same-named semantic views in different schemas both import.

## Which schemas Omni imports from

Omni imports a topic from every schema on the connection that contains a semantic view. To narrow that set, use [`included_schemas`](/modeling/models/included-schemas) or [`ignored_schemas`](/modeling/models/ignored-schemas) in the model file.

## Troubleshooting

<AccordionGroup>
  <Accordion title="My model has views from the previous version of this integration">
    Before Omni imported semantic views as topics, it created a folder of view files for each semantic view, and you may have built topics on them by hand. Those views and topics keep working. Each [schema refresh](/modeling/develop/schema-refreshes) regenerates them alongside the semantic view topics, so dashboards and workbooks built on them are unaffected.

    Two name collisions can appear in the schema refresh warnings:

    * **A topic from the previous version has the generated name** — the existing topic is kept and the schema refresh warns — see **Schema refresh warnings for skipped semantic views** below. Delete it and run a schema refresh to import the semantic view as a topic.
    * **A topic you wrote by hand has the generated name** — the generated content merges into your file and validation reports that the topic sets both `semantic_view` and `base_view` / `joins`. Rename or delete your topic and run a schema refresh.

    To retire the previous version's views and topics for a schema, delete them (or drop the semantic views in Snowflake) and run a schema refresh.
  </Accordion>

  <Accordion title="Semantic view not appearing after a schema refresh">
    * Confirm the schema containing the semantic view is included in your [connection's schema configuration](/connect-data/snowflake-semantic-views#include-the-schema-in-your-connection), and isn't excluded by [`included_schemas`](/modeling/models/included-schemas) or [`ignored_schemas`](/modeling/models/ignored-schemas) in the model file.
    * Confirm the [Omni database user](/connect-data/snowflake-semantic-views#grant-database-permissions) can read the semantic view and the tables behind it.
    * Check that [**Enable DW Semantic View Integration**](/connect-data/snowflake-semantic-views#enable-the-semantic-view-setting) is turned on in the connection settings.
    * Check the schema refresh for warnings. If Omni skipped the semantic view, the warning names it and the reason — see **Schema refresh warnings for skipped semantic views** below.
  </Accordion>

  <Accordion title="Schema refresh warnings for skipped semantic views">
    When Omni skips a semantic view during a schema refresh, the warning summary names the schema (`Skipped semantic view content in "<catalog>.<schema>"`) and the detail names the semantic view and the reason. A skipped semantic view creates no topic. If an earlier import created one, that topic stays in the model until a [schema refresh](/modeling/develop/schema-refreshes) that rebuilds the schema removes it.

    | Reason in the warning detail                                                                                                                            | What to do                                                                                                    |
    | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
    | `Omni could not parse the SQL expression for <TABLE.FIELD>`                                                                                             | Review that field's expression in Snowflake.                                                                  |
    | `Omni could not read a base table or SQL definition for its logical table <TABLE>`                                                                      | Confirm the logical table resolves in Snowflake and the Omni role can read it.                                |
    | `Omni could not determine the columns of the SQL definition for its logical table <TABLE>`                                                              | Confirm the inline SQL runs for the Omni role in the connection's default database and schema.                |
    | `it has more than 500 logical tables; semantic views this large are not supported`                                                                      | Split the semantic view.                                                                                      |
    | `its relationships form a cycle involving <T1, T2>; Omni requires an acyclic relationship graph`                                                        | Remove the cycle from `RELATIONSHIPS`.                                                                        |
    | `more than one join path connects <A> to <B>; Omni cannot yet choose between parallel join paths`                                                       | Keep one path between the two logical tables, or split them into separate semantic views.                     |
    | `its Omni topic name "<name>" is already taken by semantic view <OTHER>. Rename one of them`                                                            | Two semantic views in the schema resolve to the same Omni name. Rename one in Snowflake.                      |
    | `its Omni topic name "<name>" is taken by a previously imported topic. Delete the previously imported topic and refresh the schema again to import it.` | A topic from the previous version of this integration owns the name. Delete it and run a schema refresh.      |
    | `Failed to read semantic view ...` (views, tables, column types, dimensions and facts, metrics, or relationships)                                       | Check the grants in [step 1 of the setup](/connect-data/snowflake-semantic-views#grant-database-permissions). |
    | `semantic view metadata exceeds the cache size limit`                                                                                                   | Reach out to Omni support.                                                                                    |

    A single relationship can be skipped while the topic still imports (`The topic imports without this join.`). A view left with no relationship to the rest of the topic gets a validation warning:

    ```text theme={null}
    View "<view>" in topic "<topic>" has no relationship to the topic's other views. Queries combining it with other views will fail.
    ```

    Query that view on its own, or add an equality relationship in Snowflake.
  </Accordion>

  <Accordion title="Two topics show the same name">
    Two semantic views with the same name in different schemas share a label. Hover the Snowflake mark for the fully qualified `CATALOG.SCHEMA.NAME`.
  </Accordion>
</AccordionGroup>

## Next steps

* Look up [what each part of a definition becomes in Omni](/connect-data/snowflake-semantic-views/sync/metadata-reference)
* See a [semantic view and the topic Omni generates from it](/connect-data/snowflake-semantic-views/sync/example)
* [Query a semantic view topic](/connect-data/snowflake-semantic-views/querying)


# Connecting databases using SSH
Source: https://docs.omni.co/connect-data/ssh-tunnels

SSH tunnels allow you to connect to a database in a private network or add another layer of network encryption.

In this configuration, Omni establishes an encrypted connection to an SSH server on your network, and then uses SSH's Local Forwarding feature to route traffic through the SSH connection to the database in your network.

<Danger>
  Modifying a connection with an established SSH tunnel may result in disruptions **if you don't contact Omni support beforehand**.

  Changes include modifying the connection's `host` or `port` as well as rebuilding the SSH server and thus changing the SSH host keys. Refer to [Maintaining host keys](#maintaining-host-keys) for how to avoid this.
</Danger>

## Setup

<Steps>
  <Step title="Set up the SSH server in your network">
    Omni recommends using OpenSSH server to complete this step, as it's guaranteed to be compatible with the OpenSSH client Omni uses to establish a connection. Most Linux distributions come with OpenSSH installed or easily installable through a package manager.

    Your SSH server must:

    * Be in a network that accepts traffic on the SSH port from Omni's [outbound IP addresses](/administration/security/omni-ip-addresses)
    * Be able to route traffic to the network that the database resides in
    * Be configured so that the database's firewall accepts traffic from the SSH server
  </Step>

  <Step title="Contact Omni support">
    After you set up the SSH server, contact Omni support with the following information:

    * **For the SSH server** - The host, port, and user needed to connect
    * **For the database you want to connect to Omni** - The type of database, along with its host and port. The host should be a private IP address or a DNS entry that resolves to a private IP.
  </Step>

  <Step title="Authorize the public key">
    After Omni support receives the required information, we will generate an authentication keypair and send you the public key to authorize on your SSH server.
  </Step>

  <Step title="Confirm the connection">
    Once this is complete, Omni support will confirm the SSH connection can be established and add the new database connection to your Omni instance. The connection can then be used like any other database connection.
  </Step>
</Steps>

## Maintaining host keys

Omni verifies your SSH server's host key on every connection. If that key changes, connections will fail until you contact Omni support to update the key we have on file.

If your patching process replaces SSH servers instead of upgrading them in place, Omni highly recommends maintaining constant host keys across replacements. Otherwise, every patch cycle generates a new host key and breaks the tunnel.

The typical approach is to generate the host keys once, store them in a secrets manager - such as [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html), [Google Secret Manager](https://cloud.google.com/secret-manager/docs/overview), or [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/secrets/kv) - and write them to `/etc/ssh/` while provisioning the new server, before `sshd` starts.

On cloud images, [cloud-init's SSH module](https://docs.cloud-init.io/en/latest/reference/yaml_examples/ssh.html) supports this directly through the [`ssh_keys` config key](https://docs.cloud-init.io/en/latest/reference/modules.html#ssh), which installs the host keys you provide instead of generating new ones on first boot.

<Note>
  If you use a load balancer or autoscaling group in front of multiple SSH servers, all servers behind it must present the same host key.
</Note>


# Understanding timezone conversion & connection settings
Source: https://docs.omni.co/connect-data/timezones

Learn how connection settings impact timezone conversion in your data, how to determine the converting timezone, and how to prevent conversion.

Omni can convert time-based data to different timezones, performing the conversion when it generates SQL for a query. The underlying data is not changed. Omni converts the query results using the connection's timezone settings.

## Defining connection timezone settings

Connections have a few settings that allow you to specify how time-based data is converted:

<ParamField>
  Defines the timezone the database is in. The specified timezone is used as the source timezone for any timezone conversions.
</ParamField>

<ParamField>
  Defines the timezone to convert data to when querying.

  * **If Do Not Convert is selected**, the **Query Timezone** will be UTC and no conversion will occur.
  * **If a timezone is selected**:
    * When querying, data will be converted from the **Database timezone** to the selected timezone
    * In Omni, fields with timezone data will display in the **Query Timezone**. This also applies to filters with references to relative times and dates, such as today, yesterday, and so on.
    * **And the connection is to Snowflake**, if you specify any `timestamp_tz` fields will be displayed in that timezone. Otherwise, they will keep their timezone offset as-is.
</ParamField>

<ParamField>
  If enabled, individual users' **Query Timezone** setting will be used as the query timezone for the connection.
</ParamField>

## Determining the converting timezone

Omni determines the converting timezone using the following priority order:

1. **Per-page timezone override** (if enabled) — Set via the [timezone picker](/visualize-present/dashboards/timezone-override) on dashboards and workbooks
2. **User profile timezone** (if connection allows user-specific timezones) — Set in the user's profile settings
3. **Connection query timezone** — Set in the connection settings
4. **Connection system timezone** — Defaults to UTC

The following diagram shows how Omni evaluates these settings to determine which timezone to use for conversion:

```mermaid actions={false} theme={null}
graph TB
  checkPageOverride("Is per-page timezone override
  enabled and a timezone selected?")
  yesPageOverride(Yes)
  noPageOverride(No)
  checkUserTz("Is the connection's 
  User-specific Timezone setting checked?")
  yesUserTz(Yes)
  noUserTz(No)
  userHasQueryTz("Is the user's 
  Query Timezone setting defined?")
  yesUserHasQueryTz(Yes)
  setQueryTz("Is the connection's
  Query Timezone setting defined?")
  yesQueryTz(Yes)
  noQueryTz(No)
  dbTzToPageOverride("Convert from 
  Database Timezone to per-page override timezone")
  dbTzToUserTz("Convert from 
  Database Timezone to the user's Query Timezone")
  dbTzToQueryTz("Convert from 
  Database Timezone to connection's 
  Query Timezone")
  noConversion("No conversion occurs; timezone is UTC")

  checkPageOverride --> yesPageOverride --> dbTzToPageOverride
  checkPageOverride --> noPageOverride --> checkUserTz
  checkUserTz --> yesUserTz --> userHasQueryTz --> yesUserHasQueryTz --> dbTzToUserTz
  userHasQueryTz --> noUserTz
  checkUserTz --> noUserTz --> setQueryTz --> yesQueryTz --> dbTzToQueryTz
  setQueryTz --> noQueryTz --> noConversion
```

For more information about using the per-page timezone override, see [Enabling timezone selection on documents](/visualize-present/dashboards/timezone-override).

## Preventing timezone conversion

To prevent timezone conversion for a field, add the `convert_tz: false` property to the [field in model](/modeling/dimensions/parameters/convert-tz). **Note**: This applies only to fields that don't contain timezone information.


# Troubleshooting connection issues
Source: https://docs.omni.co/connect-data/troubleshooting

Diagnose and resolve common database connection errors in Omni, including cross-database queries, timeouts, and authentication.

<AccordionGroup>
  <Accordion title="PostgreSQL does not support cross-database queries">
    If you receive this error when querying a PostgreSQL database connection, it means that the query includes tables from two databases.

    While you can include multiple databases in a single Omni PostgreSQL connection, PostgreSQL itself does not allow queries that reference more than one database or cross-database joins.
  </Accordion>

  <Accordion title="Trino/Starburst Galaxy 'Number of stages in the query exceeds allowed maximum'">
    By default, Omni's Trino connector sets `query_max_stage_count` to `200`. You can override this default with the [`sql_preamble`](/modeling/models/sql-preamble) parameter.

    Add the following to the model's settings file:

    ```yaml theme={null}
    sql_preamble: |
      SET query_max_stage_count = <some_higher_threshold>
    ```
  </Accordion>

  <Accordion title="Schemas missing from model">
    If you can't find a schema you included in a connection, it may be that the schema needs to be 'activated' to appear in the field browser in the workbook.

    To resolve this issue, try the following:

    <Steps>
      <Step title="Edit the schema in the model IDE">
        Open the schema in the model IDE. Add a blank space to any view in the schema and save the changes.

        Once saved, the schema should be activated and appear in the workbook's field browser.
      </Step>

      <Step title="Verify the connection's schema settings">
        If you open the model IDE but don't see the schema, the issue may be an incorrectly configured connection setting or that schemas are unknowingly being restricted.

        When the **Included schemas** setting is used, Omni will include the only specified schemas in the model. If using this field:

        1. Open the connection's settings page
        2. Verify that the schema is present
        3. Verify that the syntax is correct

        Additionally, verify that schemas aren't restricted via the model's [`ignored_schemas`](/modeling/models/ignored-schemas) parameter.
      </Step>

      <Step title="Manually query views">
        If the schema is loaded into the model but has not been activated, try manually querying views.

        In a workbook, open the **All views & fields** view in the field browser. Click the **Schema** button and select the schema from the dropdown.
      </Step>

      <Step title="Check if the view has been 'ignored'">
        If you're able to see the schema in the model IDE but are missing a specific view in the schema, it may be that the view has been [`ignored`](/modeling/views/parameters/ignored).

        1. In the model IDE, toggle the view mode to **Model**. The dropdown may default to **Combined**, so be sure to update it if needed.
        2. Navigate to the file for the view and check for an `ignored: true` parameter.
        3. Remove the parameter and promote the changes to the shared model.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>


# User-selected connection environments
Source: https://docs.omni.co/connect-data/user-selected-environments

Let users pick which database connection environment their queries, dashboards, and schedules run against.

With *user-selected environments*, a user can choose which [connection environment](/connect-data/dynamic-environments) their queries run against — directly from a workbook, dashboard, or schedule — instead of being routed solely by a [user attribute](/administration/users/attributes). Admins control which environments each user or group can reach by granting access on the connection.

This builds on [dynamic connection environments](/connect-data/dynamic-environments). It doesn't replace branch-based switching or user-attribute assignment — it adds a third, user-driven way to choose an environment and defines how all three interact.

## How environment selection is resolved

A single model can have an environment chosen for it in more than one way at once. Omni resolves them in a fixed priority order, using the first that applies:

1. **Branch selection** — if you're in a [branch](/content/develop/branch-mode) that has environment switching enabled, the branch's environment wins.
2. **User-selected environment** — the environment the user picked for this model (covered on this page).
3. **User-attribute assignment** — the environment the user's [user attribute](/connect-data/dynamic-environments#setup) routes them to.
4. **Base connection** — if none of the above apply, queries run against the primary (base) connection.

<Info>
  This is the same priority order surfaced in the product, in the connection's **Environments** tab: *"When multiple environment sources apply, the priority order is: branch selection, then user-selected environment, then user attribute assignment."*
</Info>

If a user's selection later becomes invalid — for example, their access is revoked or the environment connection is deleted — Omni falls back to the next applicable source: their user-attribute assignment, or the base connection. The query still runs and routes as if no selection had been made.

### How the three mechanisms compare

| Mechanism                                                       | Who controls it                            | Scope                                         | Best for                                                                 |
| --------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------ |
| [Branch switching](/connect-data/dynamic-environments)          | The person working in the branch           | The branch                                    | Validating model or content changes against a non-production database    |
| [User-attribute assignment](/connect-data/dynamic-environments) | Admin (through user attribute values)      | Every query the user runs, by default         | Routing each user or tenant to a default environment automatically       |
| **User-selected environments**                                  | The end user (within admin-granted access) | The specific model, until the user changes it | Letting trusted users move between environments they're allowed to reach |

## Requirements

* **Omni Organization Admin** permissions are required to grant or revoke environment access.
* The connection must already have one or more [environments configured](/connect-data/dynamic-environments#setup). User-selected environments reuse the same environments you set up for dynamic connections.
* A user only sees the environment picker once they've been **granted access** to at least one environment beyond their default.

## Grant environment access

Access is managed per environment, on the connection's **Environments** tab. Org admins have implicit access to every environment; everyone else needs an explicit grant.

<Steps>
  <Step title="Open the connection's Environments tab">
    1. Navigate to **Settings > Connections** and open the primary connection.
    2. Click the **Environments** tab. Each environment you've added is listed here.
  </Step>

  <Step title="Add users or groups to an environment">
    Under an environment, find the **Access** section and choose whether you're granting access to **Users** or **Groups**:

    * To grant a user, search in **Add a user...** and select them.
    * To grant a group, switch to **Groups** and search in **Add a group...**.

    Granting a group gives access to every member of that [user group](/administration/users/groups), which is the easiest way to manage access at scale. Granted users and groups appear under **Existing access**, where you can remove access at any time.

    <Note>
      You don't need to grant access to org admins — they can reach every environment implicitly.
    </Note>
  </Step>
</Steps>

### Granting access to the base connection

When dynamic (user-attribute) environment selection is enabled on a connection, the base connection appears as its own selectable environment, pinned to the top of the **Environments** list and labeled **Base connection**.

This exists so you can grant base-connection access to users whose user attribute routes them somewhere else by default. For example, a user whose attribute pins them to **Staging** has no path back to production unless you grant them access to the base connection here.

<Note>
  The **Base connection** row is managed automatically — it appears whenever user-attribute selection is enabled and can't be unlinked. Grant or revoke access to it the same way you would any other environment.
</Note>

## Select an environment as a user

Once a user has access to more than one environment, they can switch between them from within a workbook or dashboard.

1. Open the **File** menu and hover **Connection**.
2. Choose an environment from the submenu. **Default** routes you to your normal environment — the one your user attribute assigns, or the base connection if you have none. Any other entry routes you to that specific environment.

The selection is **saved per model and per user** and persists across sessions until it's changed — there's no need to reselect it each visit. After switching, Omni confirms with a *"Switched connection environment."* message and reruns affected queries against the newly selected environment.

<Note>
  The **Connection** submenu only appears when you have access to an environment other than your default. If you can reach exactly one environment, there's nothing to switch between and the menu is hidden.
</Note>

### Selecting an environment in branches

While you're in a [branch](/content/develop/branch-mode) that has environment switching enabled, the **File > Connection** picker is disabled and shows *"Use branch environment settings to change the connection."* This is by design: branch selection takes precedence over a personal selection, so the branch's environment governs every query you run in it. Switch environments using the branch's own settings instead.

## Pin an environment on a schedule

Schedules can run against a specific environment too. Because a [schedule runs as its owner](/share/deliveries), the environment picker in the delivery form shows the **owner's** accessible environments — even when an admin is editing someone else's schedule.

1. Open the delivery (schedule) form for a dashboard or workbook.
2. In the **Connection** field, choose **Default** or a specific environment.
3. Save the schedule.

The chosen environment is applied on **every scheduled run** and on **Send now**. If the **Connection** field isn't shown, the schedule owner has no environments to choose between, and the schedule runs against their default.

<Warning>
  If a schedule changes hands — through **Duplicate** or an ownership **Transfer** — the pinned environment carries over only when the new owner also has access to it. If they don't, the pin is dropped and the schedule falls back to the new owner's default connection.
</Warning>

## Limitations

* **Schemas across environments should be as close to identical as possible.** As with [dynamic environments](/connect-data/dynamic-environments#limitations), switching an environment swaps the schema model while keeping the overarching model the same. A model that references an object missing from the selected environment will surface modeling errors.
* **Selecting an environment doesn't grant data access** — it only routes queries to a connection the admin has already permitted. Revoking access removes both the ability to select that environment and any existing selection that points to it.
* **Branch environment switching takes precedence.** Inside a branch with environment switching enabled, personal selections are ignored in favor of the branch's environment.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A user doesn't see the Connection picker">
    The **File > Connection** submenu only appears when the user has access to an environment *other than* their default. Confirm they've been granted access to a second environment on the connection's **Environments** tab (directly or through a group).
  </Accordion>

  <Accordion title="Queries are running against the wrong environment">
    Check the resolution order. A branch with environment switching enabled overrides a personal selection, which in turn overrides a user-attribute assignment. If a user's selection was made against an environment they can no longer reach, Omni falls back to their user-attribute assignment or the base connection.
  </Accordion>

  <Accordion title="A user with a non-base user attribute can't reach production">
    Their user attribute routes them away from the base connection. Grant them access to the **Base connection** row on the **Environments** tab so they can select it explicitly.
  </Accordion>
</AccordionGroup>

## Next steps

* [Dynamic connection environments](/connect-data/dynamic-environments) — set up the environments and user-attribute routing this feature builds on
* [Branch Mode](/content/develop/branch-mode) — switch environments while developing in a branch
* [User attributes](/administration/users/attributes) — assign default environments to users
* [User groups](/administration/users/groups) — manage environment access for many users at once


# Defining view name generation for database connections
Source: https://docs.omni.co/connect-data/view-name-generation

Control how Omni generates view names from database tables by always including catalog and schema prefixes.

Omni generates view names from your database tables, optionally including catalog and schema prefixes. The **Always Scope View Names** connection setting forces Omni to include catalog and schema prefixes for all tables, rather than only for tables outside the default catalog or schema. This produces predictable, fully-qualified view names across your model — useful when you work with multiple catalogs or schemas.

The setting is enabled by default for connections created on or after April 30, 2026 to supported databases. Older connections have it disabled for backward compatibility — see [Existing connections](#existing-connections) for more information.

## Supported databases

This setting is only available for databases that support multiple catalogs: [Athena](/connect-data/setup/), [Databricks](/connect-data/setup/databricks), Databricks Lakebase, [Postgres](/connect-data/setup/postgres), [Redshift](/connect-data/setup/redshift), [Snowflake](/connect-data/setup/snowflake), and Trino.

## How view naming works

Without this setting enabled, Omni generates view names differently depending on whether a table is in the default catalog and schema:

| Setup                                | View name in Omni           |
| ------------------------------------ | --------------------------- |
| default catalog + default schema     | `<table>`                   |
| default catalog + non-default schema | `<schema>__<table>`         |
| non-default catalog + any schema     | `<catalog_schema>__<table>` |

With **Always Scope View Names** enabled, all views include the full catalog and schema prefix:

| Setup                                | View name in Omni           |
| ------------------------------------ | --------------------------- |
| default catalog + default schema     | `<catalog_schema>__<table>` |
| default catalog + non-default schema | `<catalog_schema>__<table>` |
| non-default catalog + any schema     | `<catalog_schema>__<table>` |

## When to use this setting

Enable this setting when you want:

* **Consistent naming** across all views, regardless of catalog or schema location
* **Predictable references** when working with multiple catalogs or schemas

Additionally, this setting can be useful for single catalog connections as it will create shorter, more convenient view names for references.

## Enabling or disabling the setting

<Note>
  **Connection Admin** permissions are required to modify connection settings.
</Note>

### New connections

Connections created **after** the setting was introduced (**April 30, 2026**) have the setting enabled by default. You can disable it while setting up the connection, if needed.

### Existing connections

Connections created **before** this setting was introduced (**April 30, 2026**) have it disabled by default to preserve backward compatibility.

<Warning>
  After the next schema refresh, every view from the connection's default catalog will be renamed in the schema model. Workbooks, dashboards, queries, and shared models that reference the current view names will break and need to be updated.
</Warning>

To enable the setting for an existing connection:

<Steps>
  <Step title="Open the connection details">
    1. Navigate to **Settings > Connections**.
    2. Click a connection.
    3. Locate the **Always Scope View Names** toggle in the connection settings.
  </Step>

  <Step title="Toggle the setting">
    1. Click the **Always Scope View Names** toggle to enable the setting.
    2. When prompted, confirm the change.
  </Step>

  <Step title="Save & apply the changes">
    1. When finished, click **Update and Test connection**.
    2. Trigger a [**schema refresh**](/modeling/develop/schema-refreshes) to apply the changes to your Omni model.
  </Step>

  <Step title="Update model references">
    After the schema refresh completes, you'll need to update references to the views in the shared model and any content built on the shared model.

    Use the [Content Validator](/modeling/develop/content-validator) to identify and fix broken references in your documents and workbooks.
  </Step>
</Steps>

## Next steps

* Learn how to [refresh your schema](/modeling/develop/schema-refreshes) to apply connection changes
* Understand how [view names](/modeling/views/parameters/name) work in Omni's model
* Use the [Content Validator](/modeling/develop/content-validator) to identify broken model references in your content


# Tracking recent work with the My Activity page
Source: https://docs.omni.co/content/activity

Track your recent work and navigate back to workbooks, models, dashboards, and chat sessions you've been working on.

The **My Activity** page helps you quickly find and return to content you've recently worked on in Omni.

## Viewing your activity

Click **Activity** in the [sidebar](/administration/settings/sidebar) to open the **My activity** page.

<Note>
  The  sidebar item may display differently or not at all if your organization uses a [custom sidebar](/administration/settings/sidebar).&#x20;
</Note>

This page displays a deduplicated list of workbooks, models, dashboards, and chat sessions, grouped by time period. This makes it easier to quickly navigate back to specific content without scrolling through repeated entries.

### Filtering by activity type

Use the type filter toggle in the page header to focus on specific types of activity:

* **All** (default) - Shows all activity across chats, saved content, and unsaved explorations
* **Chat** - Shows only chat sessions
* **Content** - Shows only saved documents (workbooks, dashboards, and apps)
* **Exploration** - Shows only unsaved explorations

Your filter selection is stored in the URL (via a `filter` search parameter), so it persists across page reloads. When loading more activity, the selected filter will apply to newly loaded items.

Activity is organized based on when you last worked on the content:

* **Today** - Content you've accessed or modified today
* **Yesterday** - Content from the previous day
* **This week** - Content from earlier this week
* **Older** - Content from previous weeks

Each content item shows:

* The document name and description. For unnamed - typically unsaved - analyses, Omni will automatically generate titles and descriptions to make it easier for you to find your work. You can update titles and descriptions when you [save the workbook](/analyze-explore/workbook-basics#saving-a-workbook).
* The folder location and breadcrumb path (for workbooks, models, and dashboards)
* The date and time you last worked on it
* The area of the document you last worked on:
  * **Exploring** - Action occurred in an unsaved document
  * **Workbook** - Action occurred in the workbook part of the document
  * **Dashboard** - Action occurred in the dashboard part of the document
  * **App** - Action occurred in the app part of the document
  * **Chat** - Activity in a chat session with the Omni Agent
* Visual bar indicators that reflect how much activity you've had on the content. Hover over a bar to see the number of changes (for workbooks, dashboards, and apps) or messages (for chat sessions).

### Chat sessions

Chat sessions appear in your activity with a <Icon icon="message" /> icon and a **Chat** type label. The activity bars for chat sessions scale based on the number of messages in the conversation, with each bar representing approximately two messages. Hover over the bars to see the total message count for that session.

### Loading more activity

As you scroll to the bottom of the list, you can load more activity by clicking **Load more**. New items are merged into the existing time-period sections, allowing you to browse up to 1,000 entries at a time. The currently selected activity type filter will apply to newly loaded items.

## Next steps

* [Navigate content](/content/navigate) to learn more about organizing and finding content in Omni
* [Organize content with folders and labels](/content/organize) to keep your work structured
* [Omni Agent](/ai/chat) to learn about using chat sessions in Omni


# Archiving and restoring content
Source: https://docs.omni.co/content/archive-restore

Move documents to the trash and restore them from the Trash page or a direct link.

When you no longer need a workbook or dashboard, you can archive it by moving it to the trash. In Omni, archiving a document means moving it to the trash. Archived documents aren't deleted — they remain recoverable from the **Trash** page, and users with sufficient permissions can also restore them directly when following a link to archived content.

<Note>
  The  sidebar item may display differently or not at all if your organization uses a [custom sidebar](/administration/settings/sidebar).&#x20;
</Note>

## Requirements

**Editor**, **Manager**, or **Owner** permissions are required to archive and restore archived documents.

If you own personal content that has been shared organization-wide from **My Documents**, you retain archive and restore rights on that content even after sharing it with the organization.

## Archiving documents

When you archive a document, the document's workbook and dashboard will also be archived.

<Steps>
  <Step>
    In a published document (workbook or dashboard), click **File > Move to trash**.
  </Step>

  <Step>
    When prompted, click **Move to trash** to confirm.
  </Step>
</Steps>

## Restoring documents

You can restore an archived document in two ways: from the **Trash** page, or from a direct link to the archived document.

### Restoring documents from the trash

To restore a document from the Trash, click the **restore arrow** (highlighted in the following image) next to the content you want to restore:

<img alt="Restore arrow next to a document in the Trash" />

<Note>
  **Missing something?** Content archived longer ago than your organization's [**Trash visibility window** setting](/administration/settings#trash-visibility-window) will be hidden from the **Trash** and will not appear in trash counts.
</Note>

### Restoring documents from a direct link

If you follow a direct link to an archived document and you have sufficient content permissions, you'll see a page similar to the following:

<Frame>
  <img alt="Archived document page with the Restore content button" />
</Frame>

Use the **Restore content** button on this page to restore the document.

If you don't have permission to restore the document, you'll see a message explaining why:

* **Insufficient permissions** - You don't have the required permissions to restore the document
* **Model in trash** - The underlying model has been archived. If you have permission to restore the document, you'll see the model name and ID so you can locate it in the trash.

<Note>
  Users without view access and embed users will see a generic error page when following a direct link to archived content.
</Note>

## Next steps

* [Navigating content](/content/navigate)
* [Organizing content with folders and labels](/content/organize)
* [Sharing content](/share)


# Developing content and models with Branch Mode
Source: https://docs.omni.co/content/develop/branch-mode

Use Branch Mode to safely test model and content changes in isolation before merging them into your production environment.

More structured than draft-only mode but less complex than the git integration, Branch Mode brings lightweight version control to Omni, letting you test changes to models and content before making them visible to your teammates.

By creating a separate space to experiment with updates, you can develop confidently without disrupting production data. This approach supports scalable and reliable workflows, reducing the need for reactive fixes while improving traceability and accountability in the development process.

## Branching in Omni

<AccordionGroup>
  <Accordion title="What's a branch?">
    If you're familiar with version control systems like git - and it's okay if you're not! - branches in Omni are similar.

    In Omni, a branch is an isolated space that allows you to make changes to a model and/or content without affecting the live versions, typically referred to as production. This enables you to experiment, update, and refine your changes before applying any modifications to the live environment.
  </Accordion>

  <Accordion title="Why use branches?">
    To demonstrate why branches are useful, let's look at an example that starts with a change to a shared model.

    When changes are made directly to a shared model, the model's history might look like this:

    ```mermaid theme={null}
    ---
    title: "Model changes without Branch Mode"
    ---
    %%{init: { 'theme': 'default' , 
              'themeVariables': {
                  'git0': '#3F4755',
                  'commitLabelFontSize': '14px',
                  'commitLabelColor': '#000000',
                  'commitLabelBackground': '#ffffff'
                },
              'gitGraph': {
                  'showBranches': true, 
                  'showCommitLabel': true,
                  'mainBranchName': 'Production'
              }
          }
      }%%
    gitGraph TB:
        commit id: "Add topic"
        commit id: "Add field"
        commit id: "Change field logic"
        commit id: "..."
    ```

    **The changes in this example were immediately applied to the model.** If a query had been using the modified field, its logic and results could have changed unexpectedly. These differences might not be noticed right away, potentially leading to incorrect conclusions or broken content.

    Now consider this example, where changes to the model and impacted documents were made together in a branch:

    ```mermaid theme={null}
    ---
    title: "Model & document changes with Branch Mode"
    ---
    %%{init: { 'theme': 'default' , 
              'themeVariables': {
                  'git0': '#FF5FA2',
                  'git1': '#3F4755',
                  'gitBranchLabel1': '#ffffff',
                  'commitLabelFontSize': '14px',
                  'commitLabelColor': '#000000',
                  'commitLabelBackground': '#ffffff'
                },
              'gitGraph': {
                  'showBranches': true, 
                  'showCommitLabel': true,
                  'mainBranchName': 'Production model',
                  'mainBranchOrder': 1
              }
          }
      }%%
    gitGraph TB:
        commit id: "Add topic "
        commit id: "Add field "
        branch "Omni branch"
        checkout "Omni branch"
        commit id: "Change field logic "
        commit id: "Update Document A"
        commit id: "Update Document B"
        checkout "Production model"
        merge "Omni branch" id: "Merge "
        commit id: "..."
    ```

    In this example, **the branch contained updates to the field logic and impacted documents**. You could navigate to documents that use the field, open the branch, and make the changes required to ensure the updated data was correct.

    When everything worked as expected, you would then merge the branch, applying the changes to the live version of the model and publishing new versions of the documents at the same time.

    <Tip>
      Check out [our blog post](https://omni.co/blog/why-the-software-development-lifecycle-is-critical-for-bi) to learn more about why traditional development practices - like branches - are useful for modern data teams.
    </Tip>
  </Accordion>

  <Accordion title="What's the difference between a branch and a document draft?">
    Unlike a document draft which is specific to a single document, branches can include changes to a model and multiple documents. This makes branches especially useful for updating a model and any impacted content at the same time.

    Branches shouldn't be thought of as entirely separate from document drafts - they act more as a layer of additional functionality on top of document drafts. When content changes are made in a branch, a draft of each modified document is attached to the branch. Publishing the branch publishes new versions of the documents.

    Refer to the [Editing and publishing guide](/content/develop) for a detailed overview, including a comparison between drafts and branches.
  </Accordion>

  <Accordion title="Where can branches be used?">
    Branches can be used in the [model IDE](/modeling/develop/model-management) and documents.
  </Accordion>

  <Accordion title="Who can use branches?">
    Your [connection permissions](/administration/users/permissions) determine the level of access you have to branches:

    |                         | View branches | Create branches | Merge branches |
    | ----------------------- | ------------- | --------------- | -------------- |
    | **Viewer**              | X No          | X No            | X No           |
    | **Restricted Queriers** | X No          | X No            | X No           |
    | **Queriers**            | ✓ Yes         | ✓ Yes           | X No           |
    | **Modelers**            | ✓ Yes         | ✓ Yes           | ✓ Yes          |
    | **Connection Admins**   | ✓ Yes         | ✓ Yes           | ✓ Yes          |

    **Note**: **Create branches** also includes the ability to make changes within a branch.
  </Accordion>

  <Accordion title="Do branches work with the git and dbt integrations?">
    Yes, but only for changes to models. If a branch includes content changes, those changes will not be pushed to the connected git repository. However, the drafts of the content will be published when the branch is merged.

    When the [git](/integrations/git) is configured for a connection, Branch Mode is required to make changes to the connection's models. The [dbt integration](/integrations/dbt) uses branches to enable switching [dbt environments](/integrations/dbt/environments).
  </Accordion>

  <Accordion title="Can extension models have their own branches?">
    Yes. Extension models that use the `extends` parameter can be configured to support isolated branches. These branches are scoped to the extension model and remain separate from the parent shared model's branches.

    Refer to [Using isolated branches with extension models](/modeling/develop/shared-extensions/extension-branches) for more information.
  </Accordion>
</AccordionGroup>

## Creating branches

<Note>
  **Connection Admin**, **Modeler**, or **Querier** permissions are required to create branches.
</Note>

1. In a workbook or the model IDE, click **Model > New branch** or **Model > Branch > New branch**.
2. When prompted, enter a name for the branch.

   <Accordion title="Want to group branches in the branch menu?">
     To group (or nest) branches in the branch menu, you can use forward slashes. For example, these branch names:

     ```text theme={null}
     - add-new-topic
     - field-updates/add-new-calc
     - field-updates/rename-fields
     - field-updates/update-field-def
     - remove-topic
     ```

     Would create this structure in the branch menu:

     ```text theme={null}
     - add-new-topic
     - field-updates
       - add-new-calc
       - rename-fields
       - update-field-def
     - remove-topic
     ```
   </Accordion>
3. Use the **Branch from** dropdown to select the starting point for the branch:
   * **Shared model (latest)** - Creates a branch from the latest version of the shared model
   * **Existing branch** - Creates a branch from an existing branch
   * **Specific version** - Creates a branch from a specific version of the underlying model
4. Click **Create**.
5. A green and pink header will display at the top of the page, indicating that you're in the branch:

   <img alt="The green and pink branch header displayed at the top of a workbook" />

At this point, you can begin making changes. **Note**: If you created the branch in a workbook, you'll be automatically placed in a document draft.

<Note>
  If the model's connection has [environments](/connect-data/dynamic-environments) configured, creating a branch will also display an environment switcher. While in a branch, user attribute-based environment assignment is ignored - refer to [How environment selection is resolved](/connect-data/user-selected-environments#how-environment-selection-is-resolved) for how the environment sources interact.
</Note>

## Editing documents

<Note>
  **Connection Admin**, **Modeler**, or **Querier** permissions are required to edit documents in branches.
</Note>

To open an existing branch in a document, click **Model > Branch** and select your branch. If your model has 10 or more branches, you can use the **Search branches...** option to quickly find the branch you need.

You'll be placed in a draft and any changes will be auto-saved as you work.

You can add changes to the model associated with the document by opening the branch in the [model IDE](#editing-models).

### Moving drafts to branches

Branches can include changes to multiple documents. If the draft you want to move uses the same model as any documents in the branch, you can attach it to a branch.

To attach an existing draft to a branch:

1. Open the draft.
2. Click **File > Move to branch**.
3. Select the branch. The draft header at the top of the page will be updated to include the branch.

You can detach a draft from the branch at any time by clicking **File > Move to different branch > Detach from branch** in the workbook.

<Warning>
  If a draft for a document is already attached to the branch, it will be overwritten if another draft for the same document is moved. For example, a branch has a draft for **Document A** attached to it. If a different draft for **Document A** is moved to the branch, the original draft will be overwritten.

  The opposite is also true - if you detach a draft from a branch and the source document already has a draft, it will be overwritten. You'll be prompted to confirm the detachment when this occurs.
</Warning>

### Viewing document changes

For every change you make in a document, an entry will be added to the **Draft changes** panel. Click **See changes** in the branch header or **View workbook changes** on the left side of the page to open the panel:

<img alt="The Draft changes panel showing a list of changes made to a document" />

**Note**: The **Draft changes** panel will only display changes for the current document.

### Requiring pull requests to publish document changes

For high-impact or sensitive documents, you may want to ensure that all changes are reviewed before they go live. Enabling **Require pull requests to publish** enforces a pull request–based workflow, so updates must be proposed, reviewed, and approved before they are published.

When this setting is enabled:

* Direct edits to the published document are blocked
* Any change requires opening a branch and submitting a pull request
* The document is only updated once the pull request is approved and merged

<img alt="The Require pull requests to publish setting in document settings" title="Require pull requests to publish setting" />

This setting is applied per document, allowing you to selectively enforce review workflows only where they’re needed. First enable the document setting under **Settings > Content Permissions**. Then turn it on for a given document from the **File > Document settings** menu.

<img alt="The Content Permissions section in organization settings with the Require pull requests to publish option" title="Content Permissions settings" />

To use this feature:

* The git integration must be configured for the model the document is built on
* You must have the Content Manager role on the document to enable or disable this setting
* Users making changes must have the **Querier** role or higher, as changes require creating a branch

## Finding and managing branches

When working with branches in the model IDE, you have two ways to find and select the branch you need:

* **Click Model > Branch** and select your branch from the dropdown menu. To search for a branch, click the **Search branches** option to open a searchable dialog that makes it easier to find the branch you need. You can filter branches by name, then either switch to the branch or press **Enter** to select it.
* **The Branch management page**, accessed by clicking the <Icon icon="gear" /> icon in the IDE sidebar:

  <img alt="The Branch management page in the model IDE showing a list of branches" />

  You can view and manage all branches for a model on the **Branches** page. This page displays a list of all branches with key information like branch name, creator, and last updated time.

## Switching branches via URL

<Note>
  This section is only applicable to **workbooks and dashboards**. To switch branches in the model IDE, use the **Model > Branch** menu.
</Note>

You can load a document on a specific, existing branch by appending the `?branch=` query parameter to its URL. This approach is useful when you want to:

* Bookmark a direct link to a document on a specific branch
* Share a branch-specific view of a document with a colleague
* Quickly switch between branch states without navigating the UI

For example:

```text wrap theme={null}
https://<your-omni-instance>/dashboards/<dashboard-id>?branch=<branch-name>
```

Replace `<branch-name>` with the exact name of the **existing** branch you want to load. For example, if you want to load a workbook on a branch named `feature/new-metrics`:

```text wrap theme={null}
https://yourcompany.omniapp.co/workbooks/abc123?branch=feature%2Fnew-metrics
```

When adding the name of the branch, keep in mind that:

* **The branch must already exist**. This parameter doesn't create new branches. Additionally, if the branch name does not match an existing branch, the document will load without a branch.
* **You'll need to URL-encode special characters**. For example, `/` becomes `%2F`.

## Editing models

<Note>
  **Connection Admin**, **Modeler**, or **Querier** permissions are required to edit models in branches.
</Note>

After selecting your branch using one of the methods above, you can begin making changes to the model.

<Note>
  **Save to branch** captures changes made in the shared model IDE while in a branch. If you've added fields or calculations to your workbook model using the workbook UI (for example, quick aggregates or custom SQL fields), those changes are stored in the workbook layer and won't be staged automatically. To include them in the branch, open the workbook model changes drawer and click **Add to branch**. See [Promoting workbook changes in a branch](/modeling/develop/promotion#promoting-workbook-changes-in-a-branch) for steps.
</Note>

Click **Save to branch** to add your IDE changes to the branch:

<img alt="The Save to branch button in the model IDE" />

While you're working, you may want to periodically see how your changes will impact documents. You can do this by using the [Content Validator](/modeling/develop/content-validator) or [opening the branch in a workbook](#editing-documents).

### Viewing staged model changes

Each time you save a change in the IDE, an entry will be added to the **Model history** panel. Open this panel to view the changes currently on the branch, as well as the before and after (also called a diff) of each change:

<img alt="The Model history panel showing changes saved to a branch" />

To view only the model files you've changed (and saved) in the branch, click the **Browse mode** dropdown in the file picker, then **Staged**. The IDE will update to filter out any unchanged files:

<img alt="The Browse mode dropdown in the model IDE file picker with the Staged option selected" />

### Validating changes with the Content Validator

As you make changes to the model, Omni recommends using the **Content Validator** to check your work. This tool makes it easy to identify issues in content and proactively address them.

Refer to the [Content Validator guide](/modeling/develop/content-validator) for more information and the [Common publishing workflows guide](/content/develop/workflows) to learn how to incorporate validation into your development strategy.

## Publishing and merging branches

<Note>
  **Connection Admin** or **Modeler** permissions are required to merge branches.
</Note>

After you've verified your changes work as expected, you'll need to merge the branch to apply them. The steps to merge a branch will vary if the git integration is enabled.

If the integration is enabled, you'll see a **Create pull request button** in the branch header:

<img alt="The Create pull request button in the branch header" />

Click this button to create a pull request in the connected git repository. The changes in the branch will be applied to production once the pull request is merged. If the branch includes content changes, the drafts of the impacted documents will be published.

When creating a pull request from a branch with draft content, Omni automatically adds a link to view the branch content in the pull request description. This makes it easier for reviewers to see what documents will be published when the pull request is merged, reducing the risk of stale branches overwriting newer changes.

<Note>
  The automatic PR description link works for GitHub and GitLab pull requests. Azure DevOps and Bitbucket do not support pre-filling pull request descriptions via URL parameters, so the link will not be added for these providers.
</Note>

If git isn't enabled or pull requests aren't required, follow these instructions:

1. In the branch header at the top of the page, click **Publish content drafts** or **Merge** (which will display if the branch contains model changes).
2. You'll be prompted to confirm the merge. **Note**: If the branch contains modeling changes, you'll also see a **Delete branch after merge** box. Omni recommends leaving this checked.

   <img alt="The merge branch confirmation dialog with the Delete branch after merge option" />
3. Click **Merge branch**.

### Working with out of date drafts

There may be times when you see the following **out of date** warning when preparing to publish content:

<img alt="The out of date warning displayed when a draft is older than the published version" />

When a draft is marked out of date, it means that a new version of the document has been published since the draft was created. Publishing the outdated draft will overwrite the currently published version of the document.

1. Identify the changes in the outdated draft.
2. Discard the draft.
3. Create a new draft of the document.
4. In the new draft, redo any changes you identified in step 1.
5. When finished with all your changes, merge the branch.


# Developing content with Draft-only mode
Source: https://docs.omni.co/content/develop/drafts

Every Omni document has two states: draft and published.

Drafts are isolated instances of a document, including its workbook and dashboard. When a draft is published, a new, read-only version of the document is created. All users who have access to the document will see this version.

## Document drafts in Omni

<AccordionGroup>
  <Accordion title="What's a draft?">
    A draft is an isolated copy of a document, including its workbook and dashboard. In a draft, you can make changes to the queries in the document, add visualizations, modify the dashboard, and so on without impacting the live - or published - version of the document.
  </Accordion>

  <Accordion title="Why use drafts?">
    Incorporating drafts into your Omni workflow allows you to:

    * **Make incremental progress.** With small, manageable goals, it's easy to show progress without waiting for your work to be perfect.
    * **Explore without commitment.** Whether you're working solo or with a team, utilizing drafts lets you iterate on ideas without worrying about the final product.
    * **Increase your efficiency.** Drafts enable you and your teammates to view each other's changes and collaborate in a controlled environment, preventing overlap and ensuring that everyone's contributions remain distinct.
  </Accordion>

  <Accordion title="Who can use drafts?">
    Users with the ability to create documents can use drafts. The initial draft for a document is created when the document is saved.

    To access or publish drafts for other users' documents, you'll need permissions that allow you to edit the document.
  </Accordion>

  <Accordion title="Do drafts work with models and themes?">
    No, models and themes don't work with drafts.

    * **Workbook models** - While you can make changes to a workbook model while in a draft, workbook model changes can only be promoted from the [published version of a document](#publishing-drafts). Refer to the [Model management guide](/modeling/develop/model-management#shared-model-promotion) for more information about promoting model changes.

    * **Themes** - Themes can only be managed from the published version of a document. The **File > Theming** option will be disabled while viewing a draft. Exit the draft to access and manage themes.
  </Accordion>

  <Accordion title="Can I start in a draft and move to a branch?">
    Yes! In a workbook, click **File > Move to branch** to move the current draft to an existing branch. Refer to the [Branch mode guide](/content/develop/branch-mode#moving-drafts-to-branches) for more information.

    You can also detach a draft from a branch if you change your mind. While in the branch, click **File > Move to different branch > Detach from branch** to detach the draft.

    <Warning>
      Branches can have one draft per document per branch. If you move a document draft to a branch that already has a draft for the same document, the draft already on the branch will be overwritten.
    </Warning>
  </Accordion>
</AccordionGroup>

## Opening and editing drafts

Analyses must be [saved](/analyze-explore/workbook-basics#saving-a-workbook) as documents before you can create a draft. To create or open a draft, click **File > Edit** or the **Edit** button in the top right corner of the document. **Note**: If a draft already exists for a document, this opens the existing draft.

Changes in a draft - including those to models, queries, or the dashboard - are only visible in the draft, meaning they won't affect the [published version](#publishing-drafts) of the document. This ensures that you can safely iterate without impacting those viewing the published document.

Clicking **Leave draft** saves the changes made to the draft and opens the published version of the document.

### Collaborating in drafts

To collaborate efficiently, Omni recommends:

* **Ensuring only one user at a time edits a draft,** which will reduce the likelihood of authors stepping on each other. This is because, currently, a document can only have one draft at a time, which means authors will 'share' the draft.
* **Working small**. Creating and publishing small changes allows you to work more quickly and make a document's version history easier to follow.

<Accordion title="Want to explore without opening a draft?">
  Sometimes, it can be useful to explore a document without creating a draft. For example, when multiple authors want to edit the same document.

  There are a few ways to create copies that will allow you to explore without overwriting changes in a draft:

  | I want to copy...                         | Document state | How to                                                                                          |
  | ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
  | An entire document (workbook & dashboard) | Published      | **File > Duplicate**                                                                            |
  | Current workbook tab                      | Any            | **Tab > Explore** or the (**Compass**) icon next to **Both** (published) or **Options** (draft) |
  | Workbook only                             | Any            | **Explore** button in top right corner of the document                                          |

  <Note>
    The ability to duplicate and create new explorations is controlled by the document's settings and your organization's [content permissions](/administration/content-permissions).
  </Note>
</Accordion>

### Drafts and branches

Drafts can be [added to or removed from branches](/content/develop/branch-mode#moving-drafts-to-branches) at any time, giving you the flexibility to pick the best workflow as you go. Refer to the [Common publishing workflows guide](/content/develop/workflows) for example workflows.

## Viewing and restoring draft changes

To view all changes made in a draft, click the 🕒 (clock icon) in a draft workbook. The **Draft changes** panel will display a list of all changes made to the draft workbook.

You can revert to an earlier version of the draft by clicking an individual change, then **Restore**.

<img alt="" />

## Archiving drafts

Archiving a draft allows you to remove an existing draft without deleting it. When a draft is archived, the draft is stored in a separate **Archived** section of the workbook. Archived drafts are retained for 30 days.

Any user with edit access to a document can archive or restore an archived draft:

1. Open the document's **Workbook**.
2. Click **View drafts** (document icon) near the bottom left corner of the page.
3. Click an **archived** draft and view it, restore it, or use it to start a new workbook.

**Note**: Restoring an archived draft will replace the document's active draft. Omni will prompt you to confirm the restoration before proceeding.

<img alt="" />

## Publishing drafts

When a draft is published, the changes in the draft will replace the currently published version of the document. The published version of a document is **read-only**, but you can still drill down and use dashboard filters. To make changes to the workbook or dashboard, [open a draft](#opening-and-editing-drafts) of the document.

You can restore a previously published version of a document using the **File > Version history** option. Refer to the [Workbook documentation](/analyze-explore/workbook-basics#workbook-versions) for more information.

### Viewing published documents

A document's folder location and permissions determine if it's visible to other users. For example, if you saved the document in your **Personal** folder but didn't grant access to anyone, only you will be able to see the document, regardless of whether it's been published.


# Editing & publishing content
Source: https://docs.omni.co/content/develop/index

Get started with Omni's content development workflows.

Omni supports two ways to create and modify content:

* [**Draft**](#draft-only)
* [**Branch Mode**](#branch-mode)

## Draft-only

Every Omni document has two states: **draft** and **published**. When you create a draft, you're creating a saved - but unpublished - version of a document, including its workbook and dashboard. You can make changes in the draft without impacting the live version of the document.

Publishing a draft creates a new, read-only version of the document, which is the version that users with access will see when they view the document. Drafts are specific to documents and a document can only have one draft at a time. This makes drafts ideal for things like [quick changes](/content/develop/workflows#applying-small-changes-to-one-document), such as adding a new chart or calculated field.

If you added a new field to a model, your workflow to add the field to documents might look like this:

```mermaid theme={null}
flowchart LR
  one("`Enter **Edit** 
  mode in a document`") 
  two("`Add new field
  to a query`")
  three("`Publish
  changes`")
  
  one --> two
  two --> three
```

## Branch Mode

If you're familiar with git - and it's okay if you're not! - branches in Omni are similar.

In Omni, a branch is an isolated space that allows you to modify a model and/or content without affecting the live versions, typically referred to as production. This enables you to experiment, update, and refine changes at your own pace.

Merging a branch immediately applies all changes in the branch to the live environment. It also publishes an updated version of any documents that were modified as part of the branch. The ability to stage changes across documents and the model that backs them makes branches ideal for bigger changes, such as adding a new field to visualizations in separate dashboards.

Let's go back to the example in the [drafts section](#draft-only), where you added a new field to a model. If you use Branch Mode, your workflow might look like this:

```mermaid theme={null}
flowchart TB 
  subgraph documentA
  direction LR
  editDoc("`Enter **Edit**
  mode`")
  fieldQuery("`Add new field
  to a query`")

  editDoc --> fieldQuery
  end

  subgraph modelIDE
  direction LR
  branch("`Create
  branch`")
  newField("`Add new 
  field  to view`")

  branch --> newField
  end
  
  repeat("`Repeat for
  documents B, C, & D`")
  merge(Merge branch)
  prod@{ shape: text, label: "Publish documents & integrate field into model" }

  modelIDE --> documentA
  documentA --> repeat
  repeat --> documentA
  repeat --> merge
  merge --> prod
```

## Comparing drafts and branches

While both drafts and branches allow you to make changes without impacting live content, there are times when one approach may be a better fit. If you need some guidance, use the following table as a starting point:

|                                          | Document drafts                                        | Branches                                                                                                     |
| ---------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| **Works with**                           | One document at a time                                 | Documents and the associated model                                                                           |
| **Useful for**                           | Changes to a single document                           | - Changes to multiple documents<br />- Changes to a model and documents                                      |
| **Drafts**                               | One per document at any given time                     | One per document, per branch                                                                                 |
| **Required permissions**                 | Editor or Manager content permissions for the document | - Querier, Modeler, Connection Admin to create a branch<br />- Connection Admin or Modeler to merge a branch |
| [**git integration**](/integrations/dbt) | Not supported                                          | Only commits model changes to git, but content changes are published when branches are merged                |

## Getting started

Check out these guides to get started working with your Omni content:

* [Drafting and publishing content](/content/develop/drafts)
* [Using Branch Mode](/content/develop/branch-mode)


# Common content and model publishing workflows
Source: https://docs.omni.co/content/develop/workflows

Omni offers flexible workflows for drafting, reviewing, and publishing changes to documents and the models that back them.

[edit-publish]: /content/develop/index

[drafts]: /content/develop/drafts

[branches]: /content/develop/branch-mode

[content-validator]: /modeling/develop/content-validator

[git-integration]: /integrations/git

Whether you’re fixing a typo, rolling out coordinated dashboard updates, or making sure content stays in sync with model or database changes, drafts and branches give you the control you need.

This guide walks through some common scenarios - ranging from quick edits to large, coordinated updates - so you can choose the right workflow for the job.

## Requirements

To follow this guide, you should be familiar with how [drafts][drafts] and [branches][branches] work in Omni. Refer to the [Editing & publishing content guide][edit-publish] for a general overview of both features.

## Applying small changes to one document

Sometimes you just need to fix something quickly, such as correcting a typo, adding context to a chart, or renaming a query. For these lightweight edits, drafts are the simplest way forward. Anyone with **Editor** permissions or higher can create a [draft][drafts], make the change, and publish when it’s ready.

## Publishing multiple documents

When you’re rolling out a set of related changes across multiple documents, it’s often best to group them together. For example, you might be updating a set of dashboards to reflect a new metric definition or aligning terminology across several reports. In these cases, branches let you bundle drafts and publish them all at once for a smooth, coordinated release. Here's how to do it:

1. Create a new branch.
2. Update documents as needed, ensuring that [drafts are attached](/content/develop/branch-mode#moving-drafts-to-branches) to the branch.
3. Merge the branch, which will publish all attached drafts at the same time.

<Tip>
  Currently, pull requests can only be created from Omni if a branch includes a model change. If you're using the [git integration][git-integration] **and** the **Pull requests required** setting is enabled, use the following steps to enable the pull request flow in Omni:

  1. Navigate to the model IDE.
  2. Add a whitespace to the [model file](/modeling/models).

  When you create a pull request from a branch with draft content, Omni will automatically include a link to view the branch content in the pull request description if you're using GitHub or Gitlab. This helps reviewers see what documents will be published when the pull request is merged.
</Tip>

## Coordinating content with model changes

If your model changes, your content often needs to change with it. For example, you might rename a field in the model or restructure a view to improve performance.

Using a branch ensures model changes and content updates happen together. Including the Content Validator in your workflow will help catch any issues, so you can feel confident that everything will work as expected when you publish. Here's how to do it:

1. Create a new [branch][branches].
2. Make the changes to the model.
3. Use the [Content Validator][content-validator] while in the branch to identify content issues.
4. Update the content as needed, ensuring that drafts are attached to the branch.
5. Recheck the Content Validator to verify your content is error-free.
6. Merge the branch, which will promote the model changes and publish the documents.

## Coordinating content with database changes

When the source database changes, Omni’s model and content may need to be modified to accommodate the updates. For instance, maybe a table is renamed, or new columns are added to a key dataset.

By creating a branch and running a schema refresh, you can safely update the model, validate impacted content, and publish once everything is aligned with the new database structure. Here's how:

1. Create a new [branch][branches].
2. In the model IDE, trigger a [schema refresh](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes).
3. Update the model as needed.
4. Use the [Content Validator][content-validator] to identify content issues created as a result of the database changes.
5. Update the content as needed, ensuring that drafts are attached to the branch.
6. Re-check the Content Validator to verify your content is error-free.
7. Merge the branch, which will promote the model changes and publish the documents.

## Approving changes in Omni before publishing

Omni doesn’t yet support a built-in approval workflow, but you can still use existing functionality to manage quality and oversight. We recommend using:

* [Content permissions](/share) to limit who can edit content
* [Drafts][drafts] to verify and share changes prior to publishing

## Testing changes in an embedded context

If you’re embedding Omni and want to test updates before pushing them to production, a copy-based workflow is currently the best option. For example, you can duplicate a document in a draft, try out your changes in the embedded environment, and then apply updates to the original once you’re confident everything works. Here's how to do it, step by step:

1. **In a draft**, use **File > Save As** to create a copy of the document.
2. Use the copy of the document to test the changes.
3. If needed, update the original document.
4. Publish the draft of the original document.


# Navigating Omni
Source: https://docs.omni.co/content/navigate

Find and navigate content in your Omni organization.

By default, the sidebar in Omni includes the following pages. Your navigation options may appear differently if your organization uses a [custom sidebar](/administration/settings/sidebar) or some features — like AI routines — aren't enabled.

<Columns>
  <Card title="Home" icon={<SidebarHomeIcon />}>
    [Curated](/administration/settings#homepage-content) or frequently viewed content in your organization.
  </Card>

  <Card title="Omni Agent" icon="sparkles" href="/ai/chat">
    Chat with the Omni Agent — ask questions, generate queries and visualizations, create [dashboards](/visualize-present/dashboards) and [apps](/visualize-present/apps), and more.
  </Card>

  <Card title="Routines" icon={<SidebarRoutinesIcon />} href="/ai/routines">
    Schedule recurring AI-powered tasks to run automatically on your data.
  </Card>

  <Card title="Skills" icon="scroll" href="/ai/skills">
    Save a set of AI instructions and run it by name — for standardized reports, guided lookups, and data quality checks.
  </Card>

  <Card title="Favorites" icon="star">
    Access content you've added to your favorites. Click the <Icon icon="star" /> icon on the content itself or in any of the content lists in Omni to add it to your favorites.
  </Card>

  <Card title="My documents" icon="person-walking">
    Access content you've created in Omni. To make this content available to other users, you'll need [to share it with them](/share). This item is visible if the [Allow personal content](/administration/users/settings#personal-content) setting is enabled in your organization.
  </Card>

  <Card title="Activity" icon={<SidebarActivityIcon />} href="/content/activity">
    Find and return to content you've recently worked on in Omni.
  </Card>

  <Card title="Hub" icon="building">
    Access content shared with your Omni organization.
  </Card>

  <Card title="Shared with me" icon="user-group">
    Content that has been directly shared with you, as well as personal content shared with the entire organization. Click a folder to access the documents and subfolders you have access to.
  </Card>

  <Card title="All" icon={<SidebarAllIcon />}>
    All content in your organization that you have permission to access.
  </Card>

  <Card title="Trash" icon="trash-can" href="/content/archive-restore">
    Your organization's archived content. While content is never permanently deleted, content archived longer ago than the organization's [Trash visibility window setting](/administration/settings#trash-visibility-window) will be hidden in the trash.
  </Card>

  <Card title="AI Hub" icon={<SidebarAiHubIcon />} href="/administration/ai-hub">
    Manage AI features and track usage in your organization. Requires Organization Admin permissions.
  </Card>

  <Card title="Analytics" icon="chart-simple" href="/administration/analytics">
    Details about how your organization uses Omni, product updates, and information about experimental and beta features. Requires Organization Admin permissions.
  </Card>

  <Card title="Develop" icon="layer-group" href="/modeling">
    Open the model IDE to build and manage your organization's data model. Requires Organization Admin permissions or a [model role](/administration/users/permissions) with IDE access.
  </Card>

  <Card title="Settings" icon="gear" href="/administration/settings">
    Configure organization-wide settings, such as [authentication](/administration/settings/authentication), [apps](/administration/settings/app-policy), and a [custom sidebar](/administration/settings/sidebar). Most pages require Organization Admin permissions.
  </Card>
</Columns>


# Organizing content with folders & labels
Source: https://docs.omni.co/content/organize

Organize dashboards and workbooks in Omni using folders for hierarchical access control and labels for cross-folder findability.

As your team creates content, finding the right balance between access and discoverability becomes crucial. Omni's content system allows you to efficiently manage your content with:

* **Folders**, which provide a simple, hierarchical structure for organizing content and controlling access
* **Labels**, which can enhance findability without the need for duplicating content across folders

By combining folders and labels, you can create an intuitive content organization system that supports your team’s collaboration by ensuring that the right content is always easy to find.

## Folders

Using folders for content organization allows you to maintain structure and determine how users access content. For example, folders could allow you to organize content and access for:

* Teams, such as **Operations** or **Finance**
* Employee level, such as **Manager** or **Executive**
* Projects
* Clients

Folders can contain documents and subfolders.

### Creating folders

<Tabs>
  <Tab title="Omni UI">
    To create a folder in the Omni UI, click **Add folder** in the **My documents** folder or your organization's **Shared** hub. **Note**: Your organization's [**Content organization** setting](/administration/settings) determines if users can create content in the root of the shared space.
  </Tab>

  <Tab title="API">
    To create a folder using the API, call the [Create folder](/api/folders/create-folder) endpoint.
  </Tab>
</Tabs>

Creating subfolders in folders is supported. The parent folder can contain up to seven levels of nesting, for example:

<FileTree>
  * . Shared (root)
    * Folder 1/
      * Folder 2/
        * Folder 3/
          * Folder 4/
            * Folder 5/
              * Folder 6/
                * Folder 7 (nesting limit)/
</FileTree>

### Moving folders

<Tabs>
  <Tab title="Omni UI">
    <Steps>
      <Step>
        To move a folder:

        * Open the folder and click the <Icon icon="ellipsis-vertical" /> icon next to the **Share** icon, or
        * On a page like the shared **Hub** or **My Documents**, click the <Icon icon="ellipsis-vertical" /> icon next to the folder: <img alt="" />
      </Step>

      <Step>
        Click **Move**.
      </Step>

      <Step>
        Select the folder to move to.
      </Step>

      <Step>
        Click **Save**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    To move a folder using the API, call the [Update folder endpoint](/api/folders/update-folder) and set the `path` request body parameter to the folder's new location.
  </Tab>
</Tabs>

### Accessing and sharing folders

When you share a folder, permissions cascade to all documents and subfolders inside it. This means that the access role you assign to a folder applies to everything the folder contains.

Content access roles on folders work differently than on individual documents. For a detailed comparison of folder and document permissions, and information about inheriting access roles, refer to the [Sharing content guide](/share#content-access-permissions).

### Scoping folder navigation with breadcrumb roots

You can configure a folder as a breadcrumb root to scope navigation to that folder and its contents. When a folder is set as a breadcrumb root, breadcrumbs for the folder and everything inside it start at that folder. Ancestor folders and the crumbs for the top-level spaces (**Shared** and **My Documents** by default) are hidden. If your organization has renamed these spaces, the hidden crumbs use the custom names instead — see [Group titles and visibility](/administration/settings/sidebar#group-titles). This setting affects:

* Folder page breadcrumbs and the file picker
* Dashboard and document title breadcrumbs and hover cards
* Content list location strings

This setting is useful for scoping navigation to a specific subtree, for example in embed use cases built around a specific [`contentPath`](/embed/setup/url-parameters/contentPath) folder.

To set a folder as a breadcrumb root:

<Tabs>
  <Tab title="Omni UI">
    <Steps>
      <Step>
        Open the folder and click the <Icon icon="ellipsis-vertical" /> icon next to the **Share** icon.
      </Step>

      <Step>
        Click **Folder settings**.
      </Step>

      <Step>
        In the **Advanced options** section, check the **Breadcrumb root** checkbox.
      </Step>

      <Step>
        Click **Save**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    To set a breadcrumb root using the API, use the `breadcrumbRoot` request body parameter when calling the [Create folder](/api/folders/create-folder) or [Update folder](/api/folders/update-folder) endpoints.
  </Tab>
</Tabs>

### Deleting folders

Folders can only be deleted if they're empty. Who can delete a folder depends on their [content access role](/share#content-access-permissions):

* **Editors** can delete empty folders they created
* **Managers** can delete any empty folder they have access to

<Tabs>
  <Tab title="Omni UI">
    To delete a folder in the Omni UI, click the folder's <Icon icon="ellipsis-vertical" /> icon and then **Delete**.
  </Tab>

  <Tab title="API">
    To delete a folder using the API, call the [Create folder](/api/folders/delete-folder) endpoint.
  </Tab>
</Tabs>

## Labels

While folders are helpful for maintaining structure and access, a document can only be in one folder at a time. For example, a dashboard is relevant to multiple teams, each of which has their own folder. Where should the document be located?

With labels, you could place the dashboard in a shared folder and add relevant labels, ensuring the right people can find the content. Labels allow you to organize your content in a way that doesn't require duplication or sacrifice findability.

Using labels, you can:

* Organize content by subject area, such as **Marketing** or **Support**

* Indicate the current working state of a document, such as **In progress**

* Use [label settings](#label-options) to:

  * Curate **Home** page content for your organization
  * Mark important content as **Verified**

### Applying labels

<Note>
  You must be in the published version of a document to apply labels.
</Note>

To apply a label to a document or a folder, click the **Labels** icon to the right of the document/folder name:

<img alt="" />

### Viewing label information

When you hover over a label, a tooltip displays additional information about the label, including:

* The label's description (if one has been added)
* Who applied the label and when it was applied

This metadata helps you understand the context and history of labels applied to content. You can view this information wherever labels appear in Omni, including:

* Document and folder detail pages
* Content listings (Home page, My Documents, folders)
* Search results
* The curation popover

<Note>
  In embedded Omni instances, the tooltip shows the label description and timestamp, but not the name of the user who applied the label.
</Note>

### Managing labels

Labels are managed in the **Label settings** page, which can be accessed by:

* Navigating to **Settings > Labels**, or
* Clicking the **Labels** icon in a document or folder, then the **gear icon**

On the **Label settings** page, you can:

* **Add a label** by clicking the **Add Label** button.
* **Edit a label** by clicking on it or selecting **Edit** from the options menu (<Icon icon="ellipsis-vertical" /> icon). This opens the label editor where you can:
  * **Rename the label**
  * **Choose a color** using the color picker, which includes preset color swatches, a custom color picker, and an eyedropper tool
  * **Add a description** to provide additional context about the label's purpose or usage
  * **Set label options** using the [Verified and Homepage checkboxes](#label-options) (requires appropriate permissions)
* **Delete a label** by clicking the **options menu** (<Icon icon="ellipsis-vertical" /> icon) next to the label and selecting **Delete**. **Note**: Labels can't be deleted if they're currently in use.

When you add a color to a label, it will be displayed with that background color throughout Omni. Text on colored labels automatically adjusts for optimal contrast and readability. For information about viewing label descriptions and metadata, see [Viewing label information](#viewing-label-information).

### Label options

<Note>
  **Organization Admin** permissions are required to apply the options outlined in this section to labels.
</Note>

Labels can be configured with special options that provide additional functionality. These options are set in the label edit dialog and require specific permissions.

#### Homepage

Enabling the **Homepage** option allows you to select content to display on your users' **Home** page, in the **For you** section.

This can be useful for:

* Providing helpful starting points for new users in your organization
* Ensuring content relevant to all users is easily accessible

#### Verified

Enabling the **Verified** option allows you to mark important content, such as dashboards that are monitored for correctness. This can be helpful for conveying to your users which content is actively maintained or has been vetted.

To apply these options to a label:

<Steps>
  <Step>
    Open the **Label settings** page by navigating to **Settings > Labels** or by clicking the **Labels** icon in a document and then the <Icon icon="gear" /> icon.
  </Step>

  <Step>
    Click the label you want to edit, or select **Edit** from the label's **options menu** (<Icon icon="ellipsis-vertical" /> icon).
  </Step>

  <Step>
    In the edit dialog, check the **Homepage** and/or **Verified** checkboxes as needed.
  </Step>

  <Step>
    Click **Save** to apply your changes.
  </Step>
</Steps>

When these options are enabled, the corresponding label will be highlighted to increase prominence. Labels with the **Verified** option will be highlighted green with a checkmark, while those with the **Homepage** option will have a **Home Page** badge:

<img alt="" />


# Searching content
Source: https://docs.omni.co/content/search

Use content search with facets to quickly find specific dashboards, workbooks, and folders in your Omni instance.

Content search provides powerful filtering capabilities to help you quickly find specific content in your Omni instance. With search facets, you can narrow down results by various criteria.

## Accessing search

To access content search, click the **search bar** at the top of the page:

<img alt="" />

<Note>
  Only content that the searching user has access to will be returned in results.
</Note>

## Refining results with facets

Content search supports the following facets, which you can combine to refine your search:

<ParamField>
  Filter results to content created by a specific user.

  **Example**: `creator:john` shows content created by users named John.
</ParamField>

<ParamField>
  Filter results to content directly inside a specific folder, scoping your search to a particular area of your content hierarchy.

  **Example**: `in:Marketing`
</ParamField>

<ParamField>
  Filter results to content with a specific [label](/content/organize#labels) attached.

  **Example**: `label:Marketing` shows content tagged with the Marketing label.
</ParamField>

<ParamField>
  Filter results by content type. Supported types: `dashboard`, `workbook`, `folder`.

  **Example**: `type:dashboard` shows only dashboards.
</ParamField>

<ParamField>
  Filter results to content favorited by a specific user. This helps you find content that you or your colleagues have marked as important.

  **Example**: `favorited:jane`
</ParamField>

<ParamField>
  Filter results by verification status. To be verified, the content must have a label with the [**Verified** option](/content/organize#verified) applied.

  **Example**: `verified:true` shows only verified content; `verified:false` shows only unverified content.
</ParamField>

<ParamField>
  Filter results by space: `hub:true` for content in the org's **Shared** space, `hub:false` for content in the user's **Personal** space. If your organization has renamed these spaces, the facet's suggested options use those names instead of the defaults — see [Group titles and visibility](/administration/settings/sidebar#group-titles).

  **Example**: `hub:true` shows only content from the **Shared** space; `hub:false` shows only content from the **Personal** space.
</ParamField>

## Using facets in search

To use search facets, type the facet name followed by a colon in the search box. As you type, Omni will suggest relevant options based on the facet type. You can combine multiple facets to create precise search queries.

For example, to find all verified dashboards created by a specific user in your Marketing folder, you could search for:

```text title="Find verified dashboards by Jane in Marketing folder" theme={null}
type:dashboard creator:jane in:Marketing verified:true
```

## Facet examples

```text title="Find verified workbooks with a Sales label" theme={null}
type:workbook verified:true label:Sales
```

```text title="Find all content favorited by Blobby in the Product folder" theme={null}
favorited:blobby in:Product
```

```text title="Find all content created by Blob Ross" theme={null}
creator:Blob Ross
```

```text title="Find Hub-published dashboards with Sales label" theme={null}
type:dashboard hub:true label:Sales
```


# October 20, 2023
Source: https://docs.omni.co/demos/2023/20231020

Embedded user management &  more table calculations

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## More table calculations

*Richard Czechowski · `calcs` `table` `workbook`*

An overhaul of our table interaction model to allow keyboard nav, editable quick-calcs, and in-line drill-down

<Frame>
  <iframe />
</Frame>

## Embedded user management

*Elliot Park · `embed` `administration`*

Embedded session management for fine-grained control of ephemeral SSO user sessions

<Frame>
  <iframe />
</Frame>


# October 27, 2023
Source: https://docs.omni.co/demos/2023/20231027

More embedding, KPI colors, ignored_views, Snowflake Info Schema App, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## More Embedding

*Nate Agrin · `embed`*

More user management and permissioning controls for building embedded URLs

<Frame>
  <iframe />
</Frame>

## KPI colors

*Richard Czechowski · `visualization`*

Configurable KPI colors for those green churn reduction arrows

<Frame>
  <iframe />
</Frame>

## More table calculations

*Richard Czechowski · `calcs` `workbook`*

More developments for spreadsheet lovers - blank columns to make formulas simple and easy to build

<Frame>
  <iframe />
</Frame>

## ignored\_views

*Conrad Slimmer · `modeling`*

Model configuration to wildcard out unwanted views in the model

<Frame>
  <iframe />
</Frame>

## Snowflake info schema app

*Colin Zima · `modeling` `administration` `analysis-pattern`*

A micro app we build to explore and understand the Snowflake info schema -active queries, storage metadata, query volumes over time by source and much more.

<Frame>
  <iframe />
</Frame>


# November 3, 2023
Source: https://docs.omni.co/demos/2023/20231103

Google Sheets embedding, Transpose & measures on rows, Calculations refinement, & more 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

#### Google Sheets embedding

*Jack Sweeney · `workbook` `dashboard` `analysis-pattern` `embed`*

A quick demo of what the dynamic embedding in Omni opens up. Here we show an embedded Google Sheet for end-user input on dashboards. The results are auto-pushed to BQ and joined into other queries dynamically.

<Frame>
  <iframe />
</Frame>

#### Transpose and measures on rows

*Steven Talbot · `table` `visualization` `workbook`*

Fresh controls for transposing tables, or even just transposing metrics independently. All of the goodness around calculations and charting comes along with the new measure controls.

<Frame>
  <iframe />
</Frame>

#### Calculations refinement

*Richard Czechowski · `calcs` `workbook`*

More refinement of the Excel/Sheets syntax. Dynamic column naming and formatting, easier empty calculation columns, and more elegant loading of results on only changed functions.

<Frame>
  <iframe />
</Frame>

#### Autovis

*Jamie Davidson · `visualization`*

Lots of improvements to retain changes to the visualization configuration while adapting to dynamic querying and exploration.

<Frame>
  <iframe />
</Frame>

#### Timezone configuration

*Cathy Lennon · `modeling` `administration`*

The launch of timezone configuration in Omni at the query and database level.

<Frame>
  <iframe />
</Frame>

#### Dynamic schema

*Conrad Slimmer · `modeling` `administration` `analysis-pattern`*

New model configuration for dynamic schema handling (ie a single model that can be configured to different schemas for each user)

<Frame>
  <iframe />
</Frame>

#### KPIs

*Elliot Park · `visualization`*

Some clean-up of the KPIs with value formatting

<Frame>
  <iframe />
</Frame>

#### Exploring calculation usage

*Colin Zima · `calcs`*

Live exploration of early calculation function usage, plus a demo of the calculation UX live doing some string parsing.

<Frame>
  <iframe />
</Frame>

#### Dynamic IP allowlists

*Brian Frantz · `administration`*

New IP allowlist functionality

<Frame>
  <iframe />
</Frame>


# November 10, 2023
Source: https://docs.omni.co/demos/2023/20231110

Dashboard drill iframe, Vis config overhaul, Table layout designs, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard drill iframe

*Alisa Tatarinova · `dashboards`*

A first look at inline dashboard drill-down

<Frame>
  <iframe />
</Frame>

## Vis config overhaul

*Jamie Davidson · `visualization` `workbook`*

The final touches on our overhaul of visualization that maintains ad hoc changes, but still intelligently updates as queries change

<Frame>
  <iframe />
</Frame>

## Table layout designs

*Sarah Waterson · `table` `visualization` `workbook`*

Some design explorations to improve table layouts with pivots

<Frame>
  <iframe />
</Frame>

## Embed

*Nate Agrin · `embed` `administration`*

More progress on embedded user management

<Frame>
  <iframe />
</Frame>

## New embed site

*Jared Hardy · `marketing` `embed`*

Some in-progress designs on the new embedded analytics content for omni.co core website

<Frame>
  <iframe />
</Frame>


# November 17, 2023
Source: https://docs.omni.co/demos/2023/20231117

Seamless dashboard drill-down, UX odds & ends, Permission groups, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Seamless dashboard drill-down

*Alisa Tatarinova · `dashboards`*

Soon-to-be-released dashboard drill menus to keep the full experience in the dashboard, and the groundwork for visualization drilling

<Frame>
  <iframe />
</Frame>

## UX odds & ends

*Luke Bowerman · `workbook` `dashboards` `design`*

Lots of UX clean-up throughout the app - cleaner SQL workflows; improved color picker for charts; and aligned shortcuts across the workbook and dashboard, including cache clearing

<Frame>
  <iframe />
</Frame>

## Permission groups

*Eli Cohen · `permissions`*

Better workflows for managing and permissioning user groups in Omni

<Frame>
  <iframe />
</Frame>

## Point labels on charts

*Jamie Davidson · `visualization` `workbook` `dashboards`*

An early look at flexible point labeling on charts

<Frame>
  <iframe />
</Frame>

## Fast dimension fill

*Steven Talbot · `workbooks` `performance` `analysis-pattern`*

More intelligent dimension fill means faster queries and fill even over thousands of rows (via recursive CTEs); also some bonus work on binning

<Frame>
  <iframe />
</Frame>

## Column totals in spreadsheet calculation

*Colin Zima · `calcs` `workbook`*

New references for column totals in calculations, allowing for percent of total even with count distincts

<Frame>
  <iframe />
</Frame>

## Clearer bin names

*Sarah Waterson · `workbook`*

Tuning up our naming for bins to make the borders clear with integers

<Frame>
  <iframe />
</Frame>


# December 1, 2023
Source: https://docs.omni.co/demos/2023/20231201

Embedded demo, Field picker 2.0, Topic permissions, Better binning, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Embedded demo launch (Gleam)

*Nate Agrin · `embed` `dashboards`*

The launch of our embedded demo. A more full-featured flavor of the experience can be created embedding Omni, including authentication, some nice visuals, and custom navigation controls.

<Frame>
  <iframe />
</Frame>

## Field picker 2.0

*Luke Bowerman · `workbook`*

Elegant new controls for simpler, more-powerful search in the field picker of the workbook, with a specific focus on SQL queriers

<Frame>
  <iframe />
</Frame>

## Topic permissions

*Steven Talbot · `workbook` `modeling`*

New controls to allow topic-by-topic permissions in a single model

<Frame>
  <iframe />
</Frame>

## Hideable dashboard filters

*Elliot Park · `dashboard`*

More controls for dashboards, now including the ability to selectively hide a filter on the dashboard, but still apply to many tiles dynamically. Most useful in embedded contexts where not all filters may be displayed to end users.

<Frame>
  <iframe />
</Frame>

## Better binning

*Sarah Waterson · `workbook`*

Some touch up to the binning and grouping UI in Omni after some customer feedback on 1. how bins can be easier to set-up and 2. more clear bin boundaries

<Frame>
  <iframe />
</Frame>

## Query timing debug

*Jonathan Swenson · `performance` `administration`*

A rich debugger for every step of the query, so both customers and Omni can better understand and improve speed in the app

<Frame>
  <iframe />
</Frame>

## Visualization gridlines and restricted row display

*Jamie Davidson · `visualization` `workbook`*

New visualization gridlines controls and an early look at restricting which rows in the data table are visualized.  This is on hold for a bit, but we'd like to get here.

<Frame>
  <iframe />
</Frame>

## Single dashboard tile scheduling

*Corey Ruderman · `scheduling` `dashboard`*

Single dashboard tile scheduling, for when you don't want the whole dashboard in your inbox, just a single query

<Frame>
  <iframe />
</Frame>

## Email login

*Chris Merrick · `administration`*

A new login flow for email-password users

<Frame>
  <iframe />
</Frame>


# December 8, 2023
Source: https://docs.omni.co/demos/2023/20231208

Improved performance, SQL viewer permissions, Quick rollback CLI, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard performance designs

*Sarah Waterson · `design` `performance` `dashboards`*

Performance matters above all other features. We show some new (pretty gorgeous) designs that help admins debug dashboard performance.

<Frame>
  <iframe />
</Frame>

## SQL viewer permissions

*Chris Merrick · `administration` `workbook` `dashboards`*

A new permission that allows viewers to see any SQL-based content, even without explicit model permissions. New flexibility for folks who want to protect the database but still build lots of dashboards with SQL.

<Frame>
  <iframe />
</Frame>

## Quick rollback CLI

*Brian Frantz · `performance` `internal-productivity`*

Some new internal tools for quick rollbacks - making sure we can ship code quickly and minimize impact in rollbacks

<Frame>
  <iframe />
</Frame>

## Connection management redesign

*Eli Cohen · `administration` `design`*

A redesign of our connection management to make permissioning, dbt management, and deletion simpler

<Frame>
  <iframe />
</Frame>

## More spreadsheet formula work

*Colin Zima · `calcs` `workbook`*

More new spreadsheet calculations - better type handling, null handling, and lots of other UX improvements

<Frame>
  <iframe />
</Frame>


# December 15, 2023
Source: https://docs.omni.co/demos/2023/20231215

Content system, Custom homepage, Topic joins, Composed model history, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard and workbook permissions

*Luke Bowerman · `content-discovery` `workbook` `administration`*

The first look at our entirely new content system. This offers the flexibility of Google Docs style permissioning - content level controls, global defaults, folders, SQL access boost, and user-specific sharing.

<Frame>
  <iframe />
</Frame>

## Custom homepage designs

*Sarah Waterson · `design` `content-discovery`*

Some super flexible designs that open up curation and recommendation for relevant dashboards for every end user in Omni with lots of nice-looking visuals

<Frame>
  <iframe />
</Frame>

## Filter polish

*Alisa Tatarinova · `workbook` `dashboard`*

New polish around the filter experience, including consolidation of custom filtering for easier dynamic dates (2023-01-01 for 6 months, 2018, 8 fiscal months ago for 6 months, etc) and easier pasting of long lists from spreadsheets.

<Frame>
  <iframe />
</Frame>

## Topic joins

*Conrad Slimmer · `modeling` `analysis-patterns`*

Omni tries to make joins as reusable as possible, but sometimes you just need a special join for a given topic. Now joins can exist globally in the relationships file or inside an individual topic.

<Frame>
  <iframe />
</Frame>

## Composed model history

*Conrad Slimmer · `modeling` `administration`*

Improvements to model history to understand changes more clearly at each level of the model - workbook, shared, or schema.

<Frame>
  <iframe />
</Frame>

## Better heatmaps, flexible visualization labels

*Jamie Davidson · `visualization` `workbook`*

Couple of new visualization improvements - better heatmaps and new labels on charts that can flexibly map to other series.

<Frame>
  <iframe />
</Frame>

## Databricks connector

*Steven Talbot · `modeling` `administration`*

The first look at our new Databricks connector live in production. We're launching Databricks with full dialect support across the entire querying surface area.

<Frame>
  <iframe />
</Frame>

## Table cleanup

*Jared Hardy · `table` `workbook`*

Some polish to make table layouts cleaner

<Frame>
  <iframe />
</Frame>

## Query cancelling

*Nate Agrin · `workbook` `dashboard` `performance` `administration`*

Simpler query canceling in the workbook

<Frame>
  <iframe />
</Frame>


# December 22, 2023
Source: https://docs.omni.co/demos/2023/20231222

Gleam embed site, Early content permissions, Extends, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Embedded demo

*Nate Agrin · `embed` `dashboards`*

Gleam: A demo of our embedded site, a reporting service for an eCommerce retailer sharing data with their suppliers

<Frame>
  <iframe />
</Frame>

## Content permissions

*Luke Bowerman · `content-discovery` `dashboards` `administration`*

More early look at content permissions, mirroring the simplicity of Google Drive for every dashboard or workbook; a demo of audit logs on the content permissions; and a quick look at filtering on topics in all views and fields

<Frame>
  <iframe />
</Frame>

## Extends

*Jamie Davidson · `modeling`*

The launch of `extends: `in the data model, improving code reusability and model depth

<Frame>
  <iframe />
</Frame>

## Spreadsheet functions (keyboard nav)

*Richard Czechowski · `calcs` `workbook`*

Continued work on spreadsheet functions, now with full keyboard support during formula construction so you don't need to bail out to the mouse building post-processing calculations

<Frame>
  <iframe />
</Frame>

## Permission groups + permissions UX

*Eli Cohen · `administration`*

More work on the permissions experience, including clear traceability at how a diverse set of permissions resolve for a given user plus a look at permission groups

<Frame>
  <iframe />
</Frame>

## Omni.co polish + visualization docs

*Colin Zima · `marketing` `design` `docs`*

A glow up for the omni.co website plus big improvements to visualization docs

<Frame>
  <iframe />
</Frame>

## Conditional format chained rules

*Jamie Davidson · `workbook` `visualization` `table`*

Improvements to conditional formatting for layered rules

<Frame>
  <iframe />
</Frame>


# 2023 Demos
Source: https://docs.omni.co/demos/2023/index

Browse all 2023 Omni product demo videos covering embedding, content permissions, field pickers, dbt integration, and more.

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.
</Note>

* [December 22, 2023](/demos/2023/20231222): Gleam embed site, Early content permissions, Extends, & more
* [December 15, 2023](/demos/2023/20231215): Content system, Custom homepage, Topic joins, Composed model history, & more
* [December 8, 2023](/demos/2023/20231208): Improved performance, SQL viewer permissions, Quick rollback CLI, & more
* [December 1, 2023](/demos/2023/20231201): Embedded demo, Field picker 2.0, Topic permissions, Better binning, & more
* [November 17, 2023](/demos/2023/20231117): Seamless dashboard drill-down, UX odds & ends, Permission groups, & more
* [November 10, 2023](/demos/2023/20231110): Dashboard drill iframe, Vis config overhaul, Table layout designs, & more
* [November 3, 2023](/demos/2023/20231103): Google Sheets embedding, Transpose & measures on rows, Calculations refinement, & more
* [October 27, 2023](/demos/2023/20231027): More embedding, KPI colors, ignored\_views, Snowflake Info Schema App, & more
* [October 20, 2023](/demos/2023/20231020): Embedded user management &  more table calculations


# January 5, 2024
Source: https://docs.omni.co/demos/2024/20240105

Calcs GPT, Caching controls, Content permissions, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Calculations GPT

*Richard Czechowski · `ai` `calcs` `workbook`*

Our chat GPT integration for spreadsheet calculations. The huge advantage of building our calculations with syntactic parity to Excel and Sheets is the deep library of techniques for analysis on the web. This is a first look at natural language table calculations in Omni. Truly magical stuff.

<Frame>
  <iframe />
</Frame>

## Cache controls

*Jonathan Swenson · `administration` `modeling` `performance`*

Fine grained controls for the caching system in Omni. These controls are available globally, by topic, by workbook, or by query, so any permutations that matter are available in the system.

<Frame>
  <iframe />
</Frame>

## Content permissions

*Luke Bowerman · `content-discovery` `administration` `dashboards`*

The last look at content permissions before launch, smart but flexible defaults, simple sharing, folders, etc.

<Frame>
  <iframe />
</Frame>

## API key management

*Chris Merrick*

Our administrative experience for API key management, a simple way to organize API users for specific use cases in Omni for better security and administration.Tags: Administration

<Frame>
  <iframe />
</Frame>


# January 12, 2024
Source: https://docs.omni.co/demos/2024/20240112

Adding free text, Better filtering, New calcs, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Free text spreadsheeting

*Richard Czechowski · `workbook` `calcs`*

Have you ever wanted to just add text to each rows by hand in the BI tool? Now you can. A new spreadsheet interaction for adding free text. We need to open up more and more possibilities for these, but simple annotations, re-aggregation of hand grouping, or just quick classifications are all now possible directly in the table.

<Frame>
  <iframe />
</Frame>

## Better dashboard filter mapping

*Alisa Tatarinova · `dashboards`*

A renovation of our filter selection on dashboards, curating the experience to active topics making organization cleaner and simpler

<Frame>
  <iframe />
</Frame>

## Pivot spreadsheet calculations

*Richard Czechowski · `calcs` `workbook`*

New calculations for inside pivots - easy cohorting, period-over-period, or other more complex calculations over pivoted data sets

<Frame>
  <iframe />
</Frame>

## Embedding in Safari

*Nate Agrin · `embed` `administration`*

Embedded support for Safari, handling more restrictive cookie-ing in the browser

<Frame>
  <iframe />
</Frame>

## Vega not Lite

*Jamie Davidson · `visualization`*

A first look at building visualizations with Vega rather than Vega lite. While usually too complex, this opens up some options for more advanced visualizations that are not currently buildable in Vega Lite.  Doesn't look like this will make it into product without more thought.

<Frame>
  <iframe />
</Frame>

## bind\_all\_filters

*Steven Talbot · `modeling` `workbook` `analysis-pattern`*

The release of `bind_all_filters `that allow for subqueries and fact tables that listen to filters inside a query, handy for more dynamic SQL compilation at multiple levels in the query.

<Frame>
  <iframe />
</Frame>


# January 19, 2024
Source: https://docs.omni.co/demos/2024/20240119

Field level permissions, Content validator, Access filters, Pivots & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Field permissions

*Steven Talbot · `modeling` `workbook` `administration`*

Field-level permissions for use cases where specific columns may be important to hide from some users (PII, customer data, financials, etc)

<Frame>
  <iframe />
</Frame>

## Better content validation and change management

*Steven Talbot · `modeling` `administration`*

Improvements to the content validator to make sure database changes or structural model changes can flow through living dashboards well without disruption

<Frame>
  <iframe />
</Frame>

## Pivot spreadsheet functions

*Richard Czechowski · `calcs` `workbook`*

The launch of calculations for pivoted queries - interleaved metrics inside pivots (like cohorts) or metrics outside the pivot (like totals or aggregates over a cohort)

<Frame>
  <iframe />
</Frame>

## Bulk CSV scheduling

*Corey Ruderman · `scheduler` `export` `dashboards`*

Batch CSV scheduling and downloading for simpler bulk data delivery

<Frame>
  <iframe />
</Frame>

## Multiple `access_filters`

*Elliot Park · `modeling` `workbook` `administration`*

Support for multiple `access_filters` in topic and field permissions, often useful for manager views across many direct reports, or multi-region owners, or admin views in tightly permissioned use cases

<Frame>
  <iframe />
</Frame>

## Better joins with `dynamic_schema`

*Conrad Slimmer · `workbook` `modeling` `analysis-pattern`*

Better support in `dynamic_schema` use cases, to create simpler join management

<Frame>
  <iframe />
</Frame>

## Dashboard sharing and discovery

*Luke Bowerman · `content-discovery`*

Another deep dive into our about-to-launch content organization system including simple sharing workflows and flexible access management for hybrid SQL/model use cases

<Frame>
  <iframe />
</Frame>


# January 26, 2024
Source: https://docs.omni.co/demos/2024/20240126

Calculations date math & pivot progress, Filtered dashboard emailing, dbt, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Filtered scheduling

*Alisa Tatarinova · `scheduler`*

Filtered dashboard emailing - sometimes you need to send the same dashboard with different filters to tens or hundreds of users. Now you can.

<Frame>
  <iframe />
</Frame>

## Spreadsheet date math

*`calcs` `workbook`*

Date math!  Dealing with time math in the database is brutal.  For of the pain with numeric dates in Excel, they are trivial to work with - easy addition and subtraction, they just work.  Now Omni users get that same delight.

<Frame>
  <iframe />
</Frame>

## Spreadsheet pivot calcs

*`calcs` `workbook`*

We're also continuing to make progress on pivoted spreadsheet calculations - inside and outside pivots, relative references, and full row math.  Huge step forward for flexible cohorting.

<Frame>
  <iframe />
</Frame>

## Improved dbt configuration and connectivity

*Buck Ryan · `dbt` `modeling`*

More development on the dbt configuration with Omni, continuing to make dbt and Omni link together seamlessly.

<Frame>
  <iframe />
</Frame>

## Dashboard auto-refresh + more

*Luke Bowerman · `dashboards`*

A grab bag of dashboard improvements - auto-refresh with time settings and runtime metadata.  Some quick website polish too.

<Frame>
  <iframe />
</Frame>


# February 2, 2024
Source: https://docs.omni.co/demos/2024/20240202

Slack scheduling, usage analytics and more!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Slack scheduling

*Corey Ruderman · `scheduler`*

Slack scheduling!  Deliver those beautiful Omni dashboards to where your company lives (we already have 4-5 running internally)

<Frame>
  <iframe />
</Frame>

## Model pushdown for spreadsheet calcs

*`calcs` `workbook` `modeling`*

Model pushdown for spreadsheet formulas.  We've been blown away at how much spreadsheet UX has opened up data modeling.  Soon you can save a reuse those calculations anywhere.

<Frame>
  <iframe />
</Frame>

## Content foldering

*Luke Bowerman · `content-discovery`*

Foldering (personal and shared) for dashboards and workbooks - continuing to make the most robust sharing system for dashboards of any BI app

<Frame>
  <iframe />
</Frame>

## Better dashboard filtering and sorting

*`dashboards`*

Lots of nice polish - More seamless dashboard interactivity (no more flashing on sort); more single record config

<Frame>
  <iframe />
</Frame>

## Single record config

*Nate Agrin · `visualization` `workbook`*

New controls for formatting single record visualizations.

<Frame>
  <iframe />
</Frame>

## Omni usage analytics GA (with SSO)

*`administration` `embed`*

Omni usage analytics for everyone - launching analytics to every Omni admin

<Frame>
  <iframe />
</Frame>


# February 9, 2024
Source: https://docs.omni.co/demos/2024/20240209

Dashboard styling control designs, Content validator + Clickhouse, Spreadsheet calcs over pivots, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard styling control designs

*Sarah Waterson · `design` `dashboards` `embed`*

Some beautiful new designs for deepening the CSS and visual control for dashboards in the app

<Frame>
  <iframe />
</Frame>

## Content validator + ClickHouse

*Steven Talbot · `modeling` `administration`*

The launch of content validation to update Omni dashboards when database migrations inevitably happen beneath and new Clickhouse dialect support

<Frame>
  <iframe />
</Frame>

## Spreadsheet calcs over pivots

*Cathy Lennon · `calcs` `workbook`*

New functionality for spreadsheet calculations over pivoted data (think cohorts) - opening up lots more multi-dimensional querying

<Frame>
  <iframe />
</Frame>

## Column resizing

*Richard Czechowski · `table` `visualization` `workbook` `dashboards`*

Column resizing in the data tables, the first step in a series of huge improvements on the data table

<Frame>
  <iframe />
</Frame>

## Embed URL generator

*Elliot Park · `embed` `administration`*

Dynamic embed URL construction with filters

<Frame>
  <iframe />
</Frame>

## Better join modal in the UI

*Steven Talbot · `workbook` `modeling`*

Improvements to the join modal for new schemas that allow joins to any table from the UI

<Frame>
  <iframe />
</Frame>

## Website beautification

*Luke Bowerman · `marketing` `design`*

Lots of beautification of the Omni website, especially for release notes and these demo videos

<Frame>
  <iframe />
</Frame>


# February 16, 2024
Source: https://docs.omni.co/demos/2024/20240216

Complete CSS control for embed dashboard styling, Git workflows in data modeling,Filtering iframes, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Extreme dashboard styling (with CSS!)

*Jared Hardy · `embed` `dashboards`*

Complete embedded dashboard styling. Complete CSS control for the full dashboard experience. The visual controls are nearly limitless (see thumbnail below).

<Frame>
  <iframe />
</Frame>

## Git

*Steven Talbot · `git` `modeling`*

Git workflows in the data model. Our in-app versioning is great for quick fixes, but for more robust workflows and backups, git has become the standard. Now you get both in Omni.

<Frame>
  <iframe />
</Frame>

## Ability to pass filters in iFrames

*Elliot Park · `embed` `dashboards`*

Ability to pass filters in iframes - want to share drilling and filter experiences in the embedded context? Now you can!

<Frame>
  <iframe />
</Frame>

## Draggable dashboard filter layouts

*Richard Czechowski · `dashboards` `workbook`*

Draggable filter layouts - simple resorting and arrangement for dashboard filters

<Frame>
  <iframe />
</Frame>

## Dashboard filters for parsed SQL

*Steven Talbot · `dashboards`*

Filter mapping to parsed SQL - no more restrictions on the dashboard filter experience when Omni understands the SQL

<Frame>
  <iframe />
</Frame>

## Better model history + join modal search polish

*Jared Hardy · `modeling`*

Improvements to the model history experience in-app and the front-end join modal search

<Frame>
  <iframe />
</Frame>

## Better JSON parsing

*Jared Hardy · `workbook` `analysis-pattern`*

Better UX for our JSON parsing, especially around multi-select

<Frame>
  <iframe />
</Frame>

## More spreadsheet calculations

*Richard Czechowski · `calcs` `workbook`*

More calculation functions (based on watching what folks are trying to do!)

<Frame>
  <iframe />
</Frame>


# February 23, 2024
Source: https://docs.omni.co/demos/2024/20240223

Ridiculously fast embedded dashboards, Seamless dashboard refreshing, Bonus filter wiring & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Ridiculously fast embedded dashboards

*Nate Agrin · `embed` `dashboards`*

Ridiculously fast embedded dashboard tabbing. Why doesn't all embedded content work this way?

<Frame>
  <iframe />
</Frame>

## Seamless dashboard refreshing + bonus filter wiring

*Alisa Tatarinova · `dashboards`*

Seamless dashboard refreshing - no more blank pages, we'll keep the visualizations nicely in place as we reload underneath. Plus some bonus work on creating filters with the full field picker.

<Frame>
  <iframe />
</Frame>

## Period-over-period

*Steven Talbot · `workbook` `modeling` `analysis-pattern`*

Instant period-over-period builders - now you can dodge building calcs for simple offsets; lots more to develop on these. Plenty of conversation on future work.

<Frame>
  <iframe />
</Frame>

## Better model history

*Conrad Slimmer · `modeling`*

Better model history - now you can view shared model changes alongside workbook model changes for a complete understanding of the changes to a given model. Additionally, you can now explicitly compare across two versions to understand a bunch of changes at once.

<Frame>
  <iframe />
</Frame>

## Spreadsheet calculation pushdown

*Cathy Lennon · `calcs` `workbook` `modeling`*

The launch of spreadsheet calculation pushdown. Now any of your one-off IF statements or CONCATs can be one-off no more. Optional pushdown for relevant spreadsheet work. Everyone can model now!

<Frame>
  <iframe />
</Frame>

## Dynamic field names (linked to filters)

*Steven Talbot · `workbook` `dashboards` `modeling`*

Dynamic field names - when fields get attached to templated filters, naming can get messy. Now they can be wired together to make the experience feel more composed.

<Frame>
  <iframe />
</Frame>

## Content organization

*Luke Bowerman · `content-discovery`*

More polish on the slowly rolling out content organization experience - explaining permissions across folders and individual items

<Frame>
  <iframe />
</Frame>

## CalcsAI timezone function

*Colin Zima · `calcs` `workbook` `analysis-pattern`*

A quick demo of CalcsAI for mapping states to timezones - magical!

<Frame>
  <iframe />
</Frame>


# March 1, 2024
Source: https://docs.omni.co/demos/2024/20240301

SCIM user management, Design polish, Connection refresh error improvements (with dbt), Simpler permissions, & more 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## SCIM user management

*Chris Merrick · `administration`*

New configuration of Omni permissions via SCIM, so that user management can be deferred to the authentication provider and absorbed by Omni dynamically

<Frame>
  <iframe />
</Frame>

## Design polish: jump to definition in IDE and join modal search

*Jared Hardy · `design` `modeling`*

Always brushing up on the little things - now jump to the definition in the IDE properly scrolls to the desired location. Also introducing field search in the front-end join modal for faster table mapping.

<Frame>
  <iframe />
</Frame>

## Connection refresh error improvements, including dbt

*Buck Ryan · `administration` `modeling`*

Better handling of connection testing and refreshing to make sure we're sharing better warnings and clear notes on the dbt connection as well.

<Frame>
  <iframe />
</Frame>

## Simpler dashboard permissions

*Luke Bowerman · `dashboards` `content-discovery` `administration`*

With the introduction of folder permissions alongside content permissions, users can receive access to dashboards in a variety of ways. This work simplifies the understand of who can see what and makes it clear whether folders or dashboard-specific permissions are enabling a given user.

<Frame>
  <iframe />
</Frame>

## Better tables - alignment, row numbers, canvas testing

*Richard Czechowski · `table` `visualization` `workbook`*

Continued work to make the table experience first-class. The introduction of controls for showing row numbers, alignment of text (left, right, center), and some early exploration into a more scalable, faster-rendering framework.

<Frame>
  <iframe />
</Frame>

## Percentiles

*Steven Talbot · `workbook` `modeling` `analysis-pattern`*

The introduction of percentile measures for when the median isn't good enough.

<Frame>
  <iframe />
</Frame>

## Live schedules UX

*Sarah Waterson · `scheduler` `administration`*

Some UX polish to make it clear when editing whether the content is scheduled out, avoiding any unexpected impact

<Frame>
  <iframe />
</Frame>


# March 8, 2024
Source: https://docs.omni.co/demos/2024/20240308

ETL Freshness, Dynamic dbt schema switching, Period-Over-Period, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## ETL freshness update hooks

*Chris Merrick · `performance` `dashboard`*

A nice first-step towards the vision of more inter-connected ETL, transformation, and BI. Now you can kick-off ETL updates in Fivetran directly from the dashboard. This will be tied into dbt and other services down the line for transformation, but now developers can request fresh data directly from the dashboard.

<Frame>
  <iframe />
</Frame>

## Dynamic dbt schemas (schema switching)

*Buck Ryan · `dbt` `modeling`*

Dynamic dbt schemas: Often developers are working across one or many dbt schemas for new transformations. Omni can now gracefully move developers between schemas in branches to test changes on content or topics.

<Frame>
  <iframe />
</Frame>

## Period-over-period

*Steven Talbot · `workbook` `analysis-pattern`*

More period-over-period work, this time polishing the front-end user experience to select dynamic time offsets.

<Frame>
  <iframe />
</Frame>

## Dynamic SQL templating

*Steven Talbot · `workbook` `modeling`*

Templated SQL for ad hoc use cases where users may want to map raw SQL to filter blocks.

<Frame>
  <iframe />
</Frame>

## Vanity embed URLs (no more third party cookies)

*Gustav Staprans · `embed` `administration`*

Vanity embed URLs: now the embedded Omni app can share the same URL structure as the parent app, side-stepping third party cookies for a cleaner end-user experience.

<Frame>
  <iframe />
</Frame>

## In-app helpers (empty schemas, Slack API downtime, new topics)

*Eli Cohen · `design`*

Polish throughout the app for understanding totals (ungrouped aggregates) and dashboard filter mapping (no more long lists); also lots of helper text to get you unstuck (schema permissions blocking data to Omni, Slack downtime, etc).

<Frame>
  <iframe />
</Frame>


# March 15, 2024
Source: https://docs.omni.co/demos/2024/20240315

Looker migration, Tables (Row Height, Markdown), Conditional Formatting, & more 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Looker migration

*Jamie Davidson · `modeling` `administration` `workbook` `dashboard`*

A complete demo of migrating a Looker data model to Omni. Dashboard migration is also possible, but wasn't demoed live

<Frame>
  <iframe />
</Frame>

## Tables (row height, markdown)

*Richard Czechowski · `table` `visualization` `workbook` `dashboard`*

Lots of progress on improving tables in Omni. A first look at variable height rows (read: big rows), in-line images, in-line links, and even tables-in-tables.

<Frame>
  <iframe />
</Frame>

## Conditional formatting

*Jamie Davidson · `table` `visualization` `workbook` `dashboard`*

New functionality for banding and capping with conditional formatting.

<Frame>
  <iframe />
</Frame>

## Vanity URLs

*Gustav Staprans · `embed` `administration`*

The end of third party cookies for embedding. Now Omni dashboards can use vanity URLs to match the parent domain and avoid third-party cookies and more restrictive browser issues.

<Frame>
  <iframe />
</Frame>

## Auto-scaling infrastructure

*Brian Frantz · `performance` `administration`*

More work to allow auto-scaling for Omni's infrastructure. This ensures maximum performance for even the heaviest workloads.

<Frame>
  <iframe />
</Frame>

## Text() formulas

*Cathy Lennon · `calcs` `workbook`*

Bringing all the goodness of formatting in the formula to Omni, now the TEXT() function is available. Often useful when concatenating formatted data and text in a cell.

<Frame>
  <iframe />
</Frame>

## Query throttling

*Jonathan Swenson · `administration` `performance`*

Lots of work on keeping query pipelines sustainable. Here we demo some work to open up controls for user and organizational level query throttling to ensure the database isn't over-exercised

<Frame>
  <iframe />
</Frame>

## Folder tagging

*Luke Bowerman · `content-discovery`*

More work on organizing dashboards and workbooks, here bringing the tag system to folders.

<Frame>
  <iframe />
</Frame>


# March 22, 2024
Source: https://docs.omni.co/demos/2024/20240322

Dashboard PDF & CSV Downloads, Embed Themes (Gradients and Custom Fonts), & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard PDF and CSV downloads

*Corey Ruderman · `dashboard` `export`*

CSV downloads coming to dashboards - be able to kick out single-tile CSVs or zipped files of the entire dashboard

<Frame>
  <iframe />
</Frame>

## Embed themes (gradients and custom fonts)

*Elliot Park · `embed` `dashboard`*

More work on embedded themes, adding gradient backgrounds and custom font installation for perfect brand matching

<Frame>
  <iframe />
</Frame>

## Workbook-model-to-branch portability

*Alisa Tatarinova · `git` `modeling`*

The ability to lift one or many workbook models into a branch to understand the impact across multiple pieces of content. This brings a full workflow to promote one or many model changes and understanding that content is unimpacted (or impacted the way you want!)

<Frame>
  <iframe />
</Frame>

## More table work (column-by-column wrapping and frozen columns)

*Richard Czechowski · `table` `visualization` `workbook` `dashboard`*

Continued work on tables in the app - column-by-column wrapping controls plus frozen column controls for wide tables

<Frame>
  <iframe />
</Frame>

## Sankey custom visualization

*Colin Zima · `visualization`*

A new custom visualization template for Sankey visualizations in Vega-Lite

<Frame>
  <iframe />
</Frame>


# March 29, 2024
Source: https://docs.omni.co/demos/2024/20240329

Text-to-Vis (Vega Lite GPT), Text-to-Query (GPT Workbooks), Admin User Impersonation (Sudo), & more 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Text-to-vis (Vega Lite GPT)

*Nate Agrin · `ai` `visualization` `workbook`*

Text to vis for advanced Vega Lite visualization opens up more custom vis opportunities in the longtail

<Frame>
  <iframe />
</Frame>

## Text-to-query (GPT workbooks)

*Gustav Staprans · `ai` `workbook`*

Text to query for free text data exploration on top of the data model, but inside the bounds of the data model

<Frame>
  <iframe />
</Frame>

## Admin user impersonation (sudo)

*Jamie Davidson · `administration`*

New tools for admins to impersonate users to understand permissions and experience for any user in the app, including full logging during sudo

<Frame>
  <iframe />
</Frame>

## Selective workbook model promotion

*Jamie Davidson · `workbook` `modeling`*

Selective promotion from the workbook to the central data model, no more all-or-nothing promotion workflows

<Frame>
  <iframe />
</Frame>

## Dashboard on-page link anchors

*Arielle Strong · `dashboard`*

On page anchors for dashboards, to quickly link or navigate around longer dashboards via links

<Frame>
  <iframe />
</Frame>

## Private schedules

*Luke Bowerman · `scheduler` `administration`*

Private schedules, for deployments where users may self-serve scheduling but need to avoid interaction with other users

<Frame>
  <iframe />
</Frame>


# April 5, 2024
Source: https://docs.omni.co/demos/2024/20240405

Dynamic dbt Schema Swapping, 3-Argument SUMIF, Cell References in SUMIF AND COUNTIF, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dynamic dbt schema swapping

*Buck Ryan · `dbt` `modeling`*

Dynamic schema swapping for dbt development. Now you can test dbt changes in separate schemas trivially in the Omni front-end via branches.

<Frame>
  <iframe />
</Frame>

## 3-argument SUMIF, cell references in SUMIF AND COUNTIF

*Cathy Lennon · `calcs` `workbook`*

3-argument SUMIF, COUNTIF including field references. Dynamic SUMs are now trivial in Omni.

<Frame>
  <iframe />
</Frame>

## Selective workbook promotion (model cherry picking)

*Jamie Davidson · `workbook` `modeling`*

Selective promotion in the workbook. Now portions of the workbook can be promoted to the main model directly from the front-end - no more model plumbing to cherry-pick.

<Frame>
  <iframe />
</Frame>

## Collapsible subtotaling tables

*Richard Czechowski · `table` `visualizations` `workbook`*

New collapsible subtotals in the data table.

<Frame>
  <iframe />
</Frame>

## Pull requests and Git

*Conrad Slimmer · `git` `modeling`*

More development on pull requests and git in Omni

<Frame>
  <iframe />
</Frame>

## Soft calculation errors

*Cathy Lennon · `calcs` `workbook`*

Better calculation errors. Sometimes your Excel formulas aren't right. Now they don't blow up the original query and you can share them to debug together.

<Frame>
  <iframe />
</Frame>

## Case insensitive filtering

*Steven Talbot · `workbook` `dashboard`*

Case insensitive filtering for when the database isn't as clean as you wish.

<Frame>
  <iframe />
</Frame>

## Looker dashboard migration

*Jamie Davidson · `modeling` `administration` `workbook` `dashboard`*

One-click migration of Looker dashboard into Omni, including visualizations.

<Frame>
  <iframe />
</Frame>

## User attributes in front-end fields

*Steven Talbot · `workbook` `modeling`*

User attributes that can be used in field definitions via Mustache syntax

<Frame>
  <iframe />
</Frame>

## Gauge charts (custom vis)

*Colin Zima · `visualization`*

A new custom visualization gauge chart, for folks that miss the Salesforce dashboard experience.

<Frame>
  <iframe />
</Frame>


# April 12, 2024
Source: https://docs.omni.co/demos/2024/20240412

Incremental Model Promotion From the Workbook, Workbook Embedding, API + Schema Refresh Via API, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Incremental model promotion from the workbook (launched)

*Jamie Davidson · `workbook` `modeling`*

The launch of incremental model updating from the workbook. Now users can move quickly in an analysis, and easily decide which pieces of the model need to be contributed to the rest of the org or left in the workbook layer

<Frame>
  <iframe />
</Frame>

## Workbook embedding

*Gustav Staprans · `embed` `workbook`*

The first cut of workbook embedding, enabling richer app experiences for our customers' customers to build analyses on their own inside the iframe

<Frame>
  <iframe />
</Frame>

## API + schema refresh via API

*Chris Merrick · `administration` `modeling`*

A first look at the Omni API, here refreshing the schema model via an API hook

<Frame>
  <iframe />
</Frame>

## NLP feedback loop + internal tools

*Gustav Staprans · `ai` `workbook`*

A new evaluation system for NLP query construction in the app, currently internal only, but later will be a feedback loop for improving our LLM model

<Frame>
  <iframe />
</Frame>

## Embedded button color controls

*Jared Hardy · `embed` `dashboard`*

New controls for button styling in embed

<Frame>
  <iframe />
</Frame>

## Faster SQL on gigantic schemas (launched)

*Steven Talbot · `modeling`*

Improvements to speed up the SQL IDE on gigantic schema models where auto-complete was slowing typing and deletion

<Frame>
  <iframe />
</Frame>

## Image placeholder for KPI vis

*Sarah Waterson · `visualization` `design`*

Better image placeholders for KPI visualizations

<Frame>
  <iframe />
</Frame>

## Copy model field name for faster custom fields (launched)

*Jared Hardy · `modeling` `workbook`*

A quick action to copy field name out of the field picker, making custom field creation or SQL a little bit easier

<Frame>
  <iframe />
</Frame>


# April 19, 2024
Source: https://docs.omni.co/demos/2024/20240419

Dynamic Fields (Parameters), Sudo / Permissions Testing (Launched), In-Database Aggregate Awareness, & More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dynamic fields (parameters)

*Jamie Davidson · `workbook` `modeling`*

The first look at dynamic fields - fields coupled to filters for dynamic analysis. Toggling dimensions, measures, or timeframes can now be done through filters, allowing deep interactivity on content.

<Frame>
  <iframe />
</Frame>

## Sudo / permissions testing (launched)

*Jamie Davidson · `permissions`*

Sudo now allows admins to use the app as other non-admin users, ensuring permissions are set as intended for both application functionality or data access - no more guessing.

<Frame>
  <iframe />
</Frame>

## Bring your own aggregates / in-database aggregate awareness

*Steven Talbot · `modeling` `performance`*

Bring your own aggregates - aggregate awareness can now be configured in the data model for objects like dbt roll-ups. These can then be dynamic queries to reduce spend and improve performance. This will complement the browser-based DuckDB aggregate awareness.

<Frame>
  <iframe />
</Frame>

## Embed post requests / embed messaging system (launched)

*Elliot Park · `embed` `administration`*

A new framework for post requests in the embedded app, allowing for more dynamic experiences - here we show an order form modal

<Frame>
  <iframe />
</Frame>

## Dashboard explore workflow

*Luke Bowerman · `dashboard` `workbook`*

A UX reworks for exploring data from a dashboard (now without disrupting the dashboard's data model)

<Frame>
  <iframe />
</Frame>

## Tables rework + subtotals (launched)

*Richard Czechowski · `visualization` `table` `workbook` `dashboard`*

A new cleaner table experience, including subtotals and non-repeated values.

<Frame>
  <iframe />
</Frame>


# April 26, 2024
Source: https://docs.omni.co/demos/2024/20240426

Compound Filters, Pull Requests + Model History Cleanup, Dynamic dbt Warehouses, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Compound filters

*Alisa Tatarinova · `workbook` `dashboard`*

A preview of our new compound filter support - flexible AND/OR conditions for specific queries

<Frame>
  <iframe />
</Frame>

## Pull requests + model history cleanup (launched)

*Conrad Slimmer · `modeling` `git` `dbt`*

The launch of pull requests in Omni, including flexibility across dbt schemas and warehouses; also a preview of some touch-ups to model history, like viewing schema model changes

<Frame>
  <iframe />
</Frame>

## Dynamic dbt warehouses – supplementing dynamic schemas (launched)

*Buck Ryan · `dbt`*

<Frame>
  <iframe />
</Frame>

## URL restructuring (for tab reorder controls) (launched)

*Eli Cohen · `workbook`*

Lots of work into our URL restructuring, building the groundwork for tab re-arranging and more stable dashboard layouts

<Frame>
  <iframe />
</Frame>

## User attributes in link: (launched)

*Steven Talbot · `modeling` `analysis-pattern`*

The ability to use user attributes in model URLs for more dynamic, user-specific cross-linking

<Frame>
  <iframe />
</Frame>

## Force SAML login mode (launched)

*Chris Merrick · `administration`*

Forced SAML login, dropping Google Auth for deployments where SAML is the preferred method of login (and email/pw for admins to recover in case of issues with SAML)

<Frame>
  <iframe />
</Frame>

## Better dashboard foldering UX (launched)

*Luke Bowerman · `dashboard` `content-discovery`*

Some cleanup on the dashboard saving workflow to select folders to land changes in (rather than always landing in personal folders)

<Frame>
  <iframe />
</Frame>

## Optional zebra stripes on tables (launched)

*Sarah Waterson · `table` `visualization`*

Optional zebra striping for more readable tables

<Frame>
  <iframe />
</Frame>

## Better icons (launched)

*Jared Hardy · `design` `administration`*

Some touch up of user icons, always beautifying across the app

<Frame>
  <iframe />
</Frame>


# May 3, 2024
Source: https://docs.omni.co/demos/2024/20240503

XLOOKUP, Embedded Workbooks, Dynamic Fields / Select Fields From Filters, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## XLOOKUP (Launched behind a flag)

*Cathy Lennon · `calcs` `workbook`*

The launch of xlookup, bringing cross-tab analysis to any user. Now time series joins across tabs, fact lookups, etc are trivial in the workbook - continuing the strategy of bringing the best of spreadsheets into Omni.

<Frame>
  <iframe />
</Frame>

## Embedded workbooks (launched)

*Gustav Staprans · `embed` `workbook`*

A first look at the embedded workbook experience; now customers can share full analytical experiences with their customers alongside curated dashboards in embedded use cases

<Frame>
  <iframe />
</Frame>

## Dynamic fields / select fields from filters (launched)

*Jamie Davidson · `workbook` `modeling`*

The launch of dynamic fields in Omni, allowing tables columns to be controlled by filters entirely in the front-end - timegrain swappers, dimension swappers, and measure swappers are now available for flexible analysis workflows (dashboard support coming soon)

<Frame>
  <iframe />
</Frame>

## Parameters / filter passing into fields (launched)

*Steven Talbot · `workbook` `modeling` `analysis-pattern`*

Filters can now be injected into fields for parameterized reporting - opening up use cases like dynamic formatting, forecasting, or simply filters that can pass to calcs in the UI

<Frame>
  <iframe />
</Frame>

## Filter passing between dashboards (launched)

*Steven Talbot · `dashboard` `modeling` `analysis-pattern`*

Now model urls arguments can accept dashboard filters for complete context on cross-drilling experiences (passing the full filter context from one dashboard to another)

<Frame>
  <iframe />
</Frame>

## dbt dynamic schema migration (launched)

*`dbt` `modeling` `administration`*

New tooling to migrate a data model to dynamic schemas. This opens up the ability to test dbt changes on test schemas across the full app.

<Frame>
  <iframe />
</Frame>

## More tables - descriptions, conditional formatting bars (launched)

*Richard Czechowski · `table` `visualization` `workbook` `dashboard`*

Lots of work on tables: optional field descriptions in the table; touch-up to allow conditional formatting on table bar charts, and a bunch of polish across the table experience

<Frame>
  <iframe />
</Frame>

## Period-over-period clean-up (launched)

*Steven Talbot · `workbook` `analysis-pattern`*

Some touch-ups to the period-over-period experience to clearly explain the time slices

<Frame>
  <iframe />
</Frame>


# May 10, 2024
Source: https://docs.omni.co/demos/2024/20240510

Table Styling, Excel Downloads With Formulas (Launched), Stickier Vis Config (Launched), & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Table styling

*Sarah Waterson · `table` `visualization` `workbook` `dashboard`*

Lots of work to fully customize table styling - color controls for headers and table, better hover state, striping

<Frame>
  <iframe />
</Frame>

## Excel downloads with formulas (launched)

*Richard Czechowski · `calcs` `workbook` `export`*

Excel downloads that keep your formulas 🤯

<Frame>
  <iframe />
</Frame>

## Stickier vis config (launched)

*Nate Agrin · `workbook` `visualization`*

More work to keep vis config changes sticky with query updates

<Frame>
  <iframe />
</Frame>

## Hierarchical dimension drilling (launched)

*Steven Talbot · `modeling` `workbook` `dashboard` `git`*

The launch of hierarchical drilling for dimensions, plus an update to our git workflow

<Frame>
  <iframe />
</Frame>

## Workbook nav + URL changes (launched)

*Luke Bowerman · `workbook`*

Improvements to workbook navigation, the launch of our new URL schema, and more workbook touch-up

<Frame>
  <iframe />
</Frame>


# May 17, 2024
Source: https://docs.omni.co/demos/2024/20240517

Filter by Query, Field Swappers on the Dashboard, New Permissions Reporting

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Filter by query

*Steven Talbot · `workbook` `dashboard` `analysis-pattern`*

The results of one tab can now be used as a filter for another query. This enables filtering for user lists or other ID sets (or even multiple user groups!) and then passing the results to another query. This opens up fast cohorting or on-the-fly analyses to end users without SQL.

<Frame>
  <iframe />
</Frame>

## Field swappers on the dashboard

*Jamie Davidson · `dashboard`*

The addition of field swappers to dashboards (still a work in progress). Soon swapping between dimensions, swapping between measures, or swapping between timeframes can be done through the filter UX on dashboards. More interactivity for end users.

<Frame>
  <iframe />
</Frame>

## New permissions reporting

*`permissions`*

No demo for this one, but here's a screenshot (names and emails hashed, but viewable and drillable in-app)!


# May 24, 2024
Source: https://docs.omni.co/demos/2024/20240524

Omni In-App Logging, Tab Rearranging and Styling, Single-Dashboard-Only User Permission, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Omni in-app logging (launched)

*Chris Merrick · `administration`*

New logging in the app, adding observability to the most important actions in the app

<Frame>
  <iframe />
</Frame>

## Tab rearranging and styling

*Luke Bowerman · `workbook`*

A preview of tab rearranging (dragging) and styling for the workbook

<Frame>
  <iframe />
</Frame>

## Single-dashboard-only user permission

*`administration` `dashboard`*

A preview of "external" users - a new permission for users that receive only access to explicitly granted content, allowing the ability to strongly lock the app experience for some users

<Frame>
  <iframe />
</Frame>

## Embed event signaling + listeners (launched)

*Nate Agrin · `embed` `adminstration`*

A new event listening framework for embedded applications to understand activity inside the Omni iframe for orchestrating experiences external to Omni

<Frame>
  <iframe />
</Frame>

## Transparent vis colors

*Sarah Waterson · `visualization` `workbook` `embed` `dashboard`*

New controls for transparency in visualization colors, offering big improvements especially vis-a-vis light and dark mode toggling

<Frame>
  <iframe />
</Frame>

## More Calcs AI witchcraft - population calcs (launched)

*Conner Ching · `calcs` `ai` `workbook`*

A mind-blowing demo of calcs AI for pulling public data, here population data to rebase metrics

<Frame>
  <iframe />
</Frame>

## User attributes in filters

*Steven Talbot · `workbook` `dashboard`*

An early preview of user attributes in filters, for wiring user preferences into the filter experience

<Frame>
  <iframe />
</Frame>

## Filters that control other filters

*Jamie Davidson · `dashboard` `workbook`*

A new filter construct that allows one filter to control other filters - in this example allowing a user to toggle currency and control a pair of field selectors (rather than having to toggle them independently)

<Frame>
  <iframe />
</Frame>

## Dynamic column picker (launched)

*Colin Zima · `modeling` `analysis-pattern`*

Some interesting new modeling patterns for dynamic column pickers and dynamic table pickers using `IDENTIFIER`, including default filters to select a starting column or table

<Frame>
  <iframe />
</Frame>

## Dynamic table picker (launched)

*Steven Talbot · `modeling` `analysis-pattern`*

Some interesting new modeling patterns for dynamic column pickers and dynamic table pickers using `IDENTIFIER`, including default filters to select a starting column or table

<Frame>
  <iframe />
</Frame>

## Navigation and search very early preview

*Luke Bowerman · `content-discovery` `design`*

An early look at work to polish the navigation experience + in-app search

<Frame>
  <iframe />
</Frame>


# May 31, 2024
Source: https://docs.omni.co/demos/2024/20240531

Branch Mode + Git, Single-Tile Scheduling, Dynamic dbt Schema Improvements, & more 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Branch mode + Git (launched)

*Conrad Slimmer · `git` `modeling`*

The GA launch of branch mode in git

<Frame>
  <iframe />
</Frame>

## Single-tile scheduling (launched)

*Eli Cohen · `scheduling`*

The launch of single-tile scheduling for dashboards, also the underpinning for in-app alerting

<Frame>
  <iframe />
</Frame>

## Dynamic dbt schema improvements (launched)

*`dbt` `modeling` `workbook`*

More work to improve dynamic dbt schemas in Omni - making sure we can adapt to any style of dbt modeling

<Frame>
  <iframe />
</Frame>

## Omni AI improvements (filters + error handling)

*Gustav Staprans · `ai` `workbook`*

Some work on error handling and filter construction for Omni's AI functions, continuing to make exploring simpler for end users

<Frame>
  <iframe />
</Frame>

## Table colors (almost launched)

*Richard Czechowski · `visualization` `table` `workbook` `dashboard`*

The final cut of table color styling

<Frame>
  <iframe />
</Frame>

## New reporting (schedules, permissions) (launched)

*Colin Zima · `scheduling` `administration`*

New reporting for scheduler deliveries and permissions in-app, for better management and administration

<Frame>
  <iframe />
</Frame>

## Share modal designs

*Jared Hardy · `content-discovery` `design` `dashboard`*

Some design work to simplify and improve our sharing modals for dashboards

<Frame>
  <iframe />
</Frame>

## Docs glow up

*Anakarina McFadden · `docs` `design`*

More polish on the docs experience, especially for first-time users

<Frame>
  <iframe />
</Frame>


# June 7, 2024
Source: https://docs.omni.co/demos/2024/20240607

Dynamic Tables - Links and Events, Default Row Level Access Controls, Snowflake Native App, & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dynamic tables - links and events (launched)

*Richard Czechowski · `workbook` `dashboard` `visualization` `table`*

New controls for dynamic tables - links instead of text, event passing. Continuing to make tables fully dynamic.

<Frame>
  <iframe />
</Frame>

## Default row level access controls (launched)

*Conrad Slimmer · `modeling` `administration` `embed`*

Default row-level access controls. Now rather than encoding access-filters on individual topics, they can be default-set globally. A new best practice for embedded deployments to lock up data by default, even through topics.

<Frame>
  <iframe />
</Frame>

## Snowflake native app

*Chris Merrick · `snowflake`*

A first look at work on our Snowflake native app, with the full app deployed in Snowflake alongside the database

<Frame>
  <iframe />
</Frame>

## Embedded dashboard organization

*Elliot Park · `embed` `content-discovery`*

The first demo of embedded dashboard saving and sharing - the full power of the app in an iframe

<Frame>
  <iframe />
</Frame>

## Moving legends left/right (launched)

*Nate Agrin · `visualization` `workbook` `dashboard`*

New functionality to move legends around. Starting with left/right, the next focus of work will be on bottom/top legends. Some better erroring as well.

<Frame>
  <iframe />
</Frame>

## Access boost through access grants controls (launched)

*Steven Talbot · `modeling` `administration`*

A new control to allow access boost through grants. In rare cases with topic or column security, the raw data can remain locked, but optionally poked through on a specific piece of content. Will not allow for access filter (row-level) passthrough.

<Frame>
  <iframe />
</Frame>

## Front-end drill path controls

*Jamie Davidson · `workbook` `modeling`*

Everyone wants to sidestep modeling in the model, now drill paths can be controlled from the workbook - easier ad hoc drilling, and, like everything else, promotable to the shared data model

<Frame>
  <iframe />
</Frame>

## Scheduling single tiles on dashboards (launched)

*Luke Bowerman · `scheduling`*

The launch of single-tile scheduling. Now folks can send just one tile from a workbook or dashboard. Next up is alerts.

<Frame>
  <iframe />
</Frame>


# June 14, 2024
Source: https://docs.omni.co/demos/2024/20240614

AI Copilot + History, Environment Variables for dbt, Legend Controls & more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI copilot + history (behind a flag)

*Gustav Staprans · `workbook` `ai`*

New AI copilot for query building - completely new UI experience, plus clean history of prompts

<Frame>
  <iframe />
</Frame>

## Environment variables for dbt (launched)

*Buck Ryan · `dbt` `modeling`*

Environment variables for dbt. We need to be able to support in-production dbt environments, and that means coupling with environment variables for tight dynamic schema support

<Frame>
  <iframe />
</Frame>

## Top and bottom legend (launched)

*Nate Agrin · `visualization` `workbook` `dashboard`*

Top and bottom legends - continuing the push on new, better vis

<Frame>
  <iframe />
</Frame>

## Optionally unpivoted period-over-period (launched)

*Steven Talbot · `workbook`*

Unpivoted period-over-period metrics - making it simpler to rearrange tables even with our magical field typesTags: Workbook

<Frame>
  <iframe />
</Frame>

## Scheduler timezone controls (launched)

*Eli Cohen · `scheduling` `administration`*

Scheduler timezone control - making sure every schedule is completely clear on what time means

<Frame>
  <iframe />
</Frame>

## Better long names in the IDE (launched)

*Jared Hardy · `modeling`*

And little IDE brush up for long names

<Frame>
  <iframe />
</Frame>


# June 21, 2024
Source: https://docs.omni.co/demos/2024/20240621

Workbook UX (+ Tab Reordering), Vis Config Stickiness, Inline Images in Tables, & More 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Workbook UX (tab reordering!!!) + dashboard search (before July 1)

*Luke Bowerman · `workbook` `content-discovery`*

Improved workbook UX (tab reordering!!!!) + lots of work on search and discovery

<Frame>
  <iframe />
</Frame>

## Push to dbt workflow (launched)

*Buck Ryan · `dbt` `modeling`*

Continuing to build out dbt pushdown, now with editing workflow plus commit messages

<Frame>
  <iframe />
</Frame>

## Inline images and markdown in tables (launched)

*Richard Czechowski · `workbook` `dashboard` `visualization` `table`*

Launch of inline images and markdown for tables in the app

<Frame>
  <iframe />
</Frame>

## Vis config stickiness work

*Nate Agrin · `visualization`*

Work to keep vis config stickier. We have lots of work to do to make vis keep changes but still evolve with queries, but progress

<Frame>
  <iframe />
</Frame>

## In-app workbook analytics for admins (launched)

*Gustav Staprans · `in-app-analytics`*

New workbook experience for in-app analytics. Using our embedded workbook experience to expose more data to Omni admins

<Frame>
  <iframe />
</Frame>

## Website glow up (launched)

*Luke Bowerman · `marketing`*

Lots of work on website design and layout, including easier-to-navigate blogs

<Frame>
  <iframe />
</Frame>

## 30-minute embedded app (launched)

*Chris Merrick, Jack Sweeney · `marketing` `embed`*

A quick demo of an embedded analytics experience that we built and delivered in 30 minutes!

<Frame>
  <iframe />
</Frame>


# June 28, 2024
Source: https://docs.omni.co/demos/2024/20240628

Alerts, Email Bursting (User Attributes in Schedules), AI Querying, & More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Scheduled alerts (behind a flag)

*Corey Ruderman · `scheduling`*

Scheduled alerts! Now you can configure schedules to only send data when specific triggers are met, keeping the inbox lighter, and making schedules more actionable.

<Frame>
  <iframe />
</Frame>

## User attributes in schedules / bursting (behind a flag)

*Corey Ruderman · `scheduler` `permissions`*

User attribute bursting in the scheduler. One dashboard, 100 recipients, each with different filters, now in a couple clicks.

<Frame>
  <iframe />
</Frame>

## Semi additive measures / Omni Dimensionlize (about to launch)

*Steven Talbot · `modeling` `workbook`*

Semi additive measures. Working with data that doesn't aggregate over time (MAUs, credit balances, etc) can be painful. Now we have native operators that can handle all that nuance with minimal effort.

<Frame>
  <iframe />
</Frame>

## Omni usage logs + event collection (on request + in-app soon)

*Chris Merrick · `administration` `permissions`*

Custom logging pipeline for customers that need full usage details. Also the underpinnings of event collection for in-app usage reporting.

<Frame>
  <iframe />
</Frame>

## Better Git conflicts + commit history (launched)

*Conrad Slimmer · `modeling` `git`*

More improvements to the git integration to better handle conflicts between imported changes and activity in the app via commit history.

<Frame>
  <iframe />
</Frame>

## Embed SSO URL validation (launched)

*Nate Agrin · `embed`*

New tooling to validate embed SSO URL generation to ensure embed apps are easy to authenticate

<Frame>
  <iframe />
</Frame>

## Skinnier Omni payloads (launched)

*Nate Agrin · `performance`*

Massive improvements to data compression for large payloads, sometimes reducing data sizes by upwards of 50% for large data sets

<Frame>
  <iframe />
</Frame>

## Omni AI official launch (launched)

*Gustav Staprans · `workbook` `ai`*

A quick look at the launch of Omni AI for natural language querying in the app alongside the field picker - data any way you want it.

<Frame>
  <iframe />
</Frame>

## Dashboard filters in content validator (launched)

*Steven Talbot · `modeling` `dashboard`*

A bit more tuning to handle filters in the content validator - making sure dashboards are immune to schema changes.

<Frame>
  <iframe />
</Frame>


# July 8, 2024
Source: https://docs.omni.co/demos/2024/20240708

Content as code, Drill modals in workbook & dbt pushdown

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboards as code (ask us to kick the tires)

*Chris Merrick · `dashboard` `api`*

Content as code: a first look at serialized content that allows installability across connection, versioning, or code based editing for Omni dashboards

<Frame>
  <iframe />
</Frame>

## Drill modals in the workbook (coming soon)

*Alisa Tatarinova · `workbook` `drill`*

Drill modals on workbooks: simplifying the drill down experience to keep the experience clean.

<Frame>
  <iframe />
</Frame>

## dbt pushdown with  (about to launch)

*Buck Ryan · `dbt`*

dbt pushdown using `{{ref}}` syntax: making sure we write dbt jobs in dbt language during push down.

<Frame>
  <iframe />
</Frame>


# July 12, 2024
Source: https://docs.omni.co/demos/2024/20240712

Query API alpha, table enhancements, controls for controls and lots more!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Query API (ask us to kick the tires)

*Jamie Davidson · `api`*

Our new query API in alpha - take the Omni model anywhere you like.  Still refining the API, but can start opening up early testers.

<Frame>
  <iframe />
</Frame>

## Table refinements (coming soon)

*Sarah Waterson, Richard Czechowski · `table`*

More table controls and refinement.  We're still hammering out the last pieces of making Omni data tables feel amazing.  Better resize, better renaming, alignment controls, and more.

<Frame>
  <iframe />
</Frame>

## Custom dashboard cards (launched)

*Arielle Strong · `dashboard` `markdown`*

Some new code for dashboard cards - a really nice way to present data across a list different objects with many attributes

<Frame>
  <iframe />
</Frame>

## Controls for controls – multi-tile controls (launched)

*Jamie Davidson · `dashboard`*

The launch of controls for controls.  Now day/month/quarter selectors, or field selectors for an individual tile can be coordinated across many tiles.  This opens up use cases like full dashboard time swapping, or currency toggling at the dashboard level - all without touching the data model.

<Frame>
  <iframe />
</Frame>

## Better label handling (launched, bit more to do)

*Nate Agrin · `visualization`*

Better label handling with clipped axes

<Frame>
  <iframe />
</Frame>

## Better vis on mobile (coming soon)

*Sarah Waterson · `visualization` `dashboard` `mobile`*

Some experiments we are running to better handle legends on mobile - making sure they don't take up too much of the vis' space

<Frame>
  <iframe />
</Frame>

## Semi-additive measure drilldown (launched)

*Steven Talbot · `drill` `dashboard` `workbook`*

Drilling for semi-additive measures - doing the hard stuff to make them 'just work'

<Frame>
  <iframe />
</Frame>

## Sum distinct, average distinct (launched)

*Steven Talbot · `modeling`*

Sum distinct and average distinct in the data model - now users can flexibly aggregate over non-primary keys

<Frame>
  <iframe />
</Frame>


# July 19, 2024
Source: https://docs.omni.co/demos/2024/20240719

IDE error auto-fixing, refresh schema on schedule, KPI styling enhancements, improved SQL auto-complete and lots more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Model automatic error fixing! (coming soon)

*Steven Talbot · `modeling`*

The most difficult part about maintaining a data environment is the constant cleanup required as business logic evolves and transforms.  Inevitably, the outcome is errors in the data model.  Instead of fixing them one-by-one, what if they just resolved themselves?  Our new IDE errors now have a button to do just that!  Model cleanup is now as easy as accepting cleanup suggestions. Incredibly excited for this one for our own environment as well :)

<Frame>
  <iframe />
</Frame>

## Scheduler for schema refresh (coming soon)

*Corey Ruderman · `scheduling` `modeling`*

Now you can have Omni automatically stay in sync with database changes on a schedule.  This will automatically pull the info schema and update the data model to reflect reality.

<Frame>
  <iframe />
</Frame>

## More KPI controls (coming soon)

*Arielle Strong, Richard Czechowski, Sarah Waterson · `visualization` `dashboard`*

More styling controls for KPIs - text sizing and alignment to make sure they layout just how you want

<Frame>
  <iframe />
</Frame>

## Embed filter CSS controls (launched)

*Jared Hardy · `embed` `theme`*

New controls to style the filter via CSS.  Making sure everything is controllable for embedded environments.

<Frame>
  <iframe />
</Frame>

## Design touch-ups all over the place (launched)

*Jared Hardy · `design`*

Tons of instances of design polish throughout the app - cleaner styling, friendlier inputs, better UI and UX.

<Frame>
  <iframe />
</Frame>

## More autocomplete in SQL and custom field builder (coming soon)

*Arielle Strong, Richard Czechowski · `sql` `modeling`*

Better autocomplete in the SQL experience, and some nice drag and drop from the field picker for custom field building

<Frame>
  <iframe />
</Frame>

## Table color styling UX (launched)

*Sarah Waterson · `table`*

Improved the UX for table color styling, especially vis-a-vis transparency (gotta make sure dark mode looks nice too)

<Frame>
  <iframe />
</Frame>

## Website case studies (launched)

*Jared Hardy · `marketing`*

New marketing website page featuring customer case studies about working with Omni

<Frame>
  <iframe />
</Frame>

## New styling for dbt in the IDE (launched)

*Buck Ryan · `dbt` `modeling`*

New styling for the dbt import in our IDE - making sure the read-only sections are clear


# July 26, 2024
Source: https://docs.omni.co/demos/2024/20240726

IDE redesigns, lots of filter work, and much more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## IDE redesigns (early designs)

*`modeling`*

A whole bunch of design prototypes for upcoming work on the IDE.  Easier joins and topics, better navigation, lots of metadata and in-line documentation.

<Frame>
  <iframe />
</Frame>

## Field picker in-use toggle (launched)

*`Workbooks`*

A new filter control to quickly view only the fields in use for a given query (dimensions, measures, pivots, or filters)

<Frame>
  <iframe />
</Frame>

## Editing visualization from the dashboard (later, will be a bit)

*`Dashboards` `Visualization`*

Some very early prototypes for editing visualizations directly on the dashboard.  The goal is to avoid bouncing back and forth to the workbook when tuning visualizations.  Lots of work to do here to launch, but hopefully paints the picture of a much better editing experience.

<Frame>
  <iframe />
</Frame>

## Single pick filters (coming next week)

*`dashboards` `filters`*

A first look at new single-select filters on dashboards, removing the complexity of picking a filter type, and simply requiring a single filter input for a dashboard (think Customer Lookup, Region Picker, etc).

<Frame>
  <iframe />
</Frame>

## Filter suggestion cache busting (launched)

*`Workbook` `Dashboards` `Filters`*

New controls that allow for refreshing the filter suggestion cache.  Making sure all the entries from the database are available for suggestions.

<Frame>
  <iframe />
</Frame>

## Dashboard filter faceting controls (launched)

*`Dashboards` `Filters`*

New explicitly controls for whether one filter filters the suggestions of another filter.  Can be turned on or off as needed for the desired experience.

<Frame>
  <iframe />
</Frame>

## Period-over-period dashboard controls (launched)

*`Dashboards` `Filters`*

Now all the goodness of period-over-period controls is available from the dashboard as well.

<Frame>
  <iframe />
</Frame>

## Single tile schedules - bigger vis (launched)

*`Scheduler` `Dashboards`*

Now when single tile visualizations are scheduled, the visualizations are sized up for easier consumption.

<Frame>
  <iframe />
</Frame>

## Period-over-period compare to last period (launched)

*`Workbook` `Dashboards` `Filters`*

A new option for a period-over-period offset to the previous same-length period.  Want to look at 20-day performance vs previous 20-days, or 37-month vs 37-month - all out of the box now.

<Frame>
  <iframe />
</Frame>

## Calling filters in markdown (launched)

*`Workbook` `Dashboards` `Visualization`*

Now it's much easier to use a given query's filter configuration in markdown, allowing for easier drill down to dashboards or other queries in Omni.

<Frame>
  <iframe />
</Frame>


# August 2, 2024
Source: https://docs.omni.co/demos/2024/20240802

Dashboard themes, dashboard vanity URLs, XLOOKUP portability, in_query, single-use views in topics and much more!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard filter improvements

*`Dashboards` `Filters`*

A bit more work to improve performance when filters are left empty.

<Frame>
  <iframe />
</Frame>

## Table header styling (truncation)

*`Workbook` `Tables`*

New controls to truncate columns headers to two lines.  Always trying to make sure styling is in full control, and defaults look great.

<Frame>
  <iframe />
</Frame>

## Dashboard themes / styling manager

*`Dashboards` `Embed`*

Now dashboard styling (CSS, fonts, colors, backgrounds) can be stored into themes that can be used on any dashboard.  This new UX allows styling directly in the app, and easy management for consistent, custom styles with minimum effort.

<Frame>
  <iframe />
</Frame>

## Dashboard vanity URLs

*`Dashboards`*

New settings for vanity dashboard URLs, making navigation simple and contextual - now it's as easy as dashboard/CorporateDash instead of dashboard/1 or dashboard/lkjdfs (unless you want that!).  This also means that you can more easily make updates to an embedded dashboard without requiring an engineer to point from one identifier to another, by instead pointing to a fixed, immutable URL.

<Frame>
  <iframe />
</Frame>

## XLOOKUP and filter-by-query portability

*`Wrokbooks` `Calcs`*

Moving queries across workbooks is usually simple, but not when your queries reference other queries - until now.  Now you can move queries with XLOOKUPs or queries with filters from other queries to any workbook, and the dependencies come with - no more thinking, all just works.

<Frame>
  <iframe />
</Frame>

## SQL with sorts, column labels, and calcs

*`Workbook` `Sql`*

A first look at our effort to bring all of the Omni goodness to SQL queries as well.  Instead of forcing users to wedge calculations or column relabels or sorts into the SQL block, now it's just simple actions on top of the result table.  Little bit more work to do here, but coming soon.

<Frame>
  <iframe />
</Frame>

## in\_query model parameters

*`Modeling` `Workbook`*

More flexibility for your data models - in\_query allows for dynamic SQL generation based upon the structure of your query.  This opens up all sorts of new use cases for flexible SQL based upon the filters or columns selected.

<Frame>
  <iframe />
</Frame>

## Period-over-period with time columns

*`Calcs` `Workbook`*

The finishing touches on our period-over-period implementation now offer dynamic time offsets even with other time fields selected.  An easy way to pull up time offsets without impacting the structure of your baseline query.

<Frame>
  <iframe />
</Frame>

## Dynamic database connections

*`Modeling` `Administration`*

New functionality that allows for dynamically swapping the database connection from a branch.  Easily switch between prod or staging schemas (not just dbt) in the UI - great for testing data models across mirrored databases during migration or other more complex deployment use cases.

<Frame>
  <iframe />
</Frame>

## Snowflake key-pair authentication

*`Administration`*

Some fresh code for using key-pair authentication with Snowflake - providing an extra layer of security to basic authentication (ie. username and password) when accessing your Snowflake.  Wrapping up code review and tests on it, we expect it to be live next week.

<Frame>
  <iframe />
</Frame>

## Views in topics

*`Modeling`*

Sometimes you need to customize a view for the purpose of a single topic - new labels, new fields, maybe even different field definitions.  Now you can.

This work opens up a views: argument inside topics, that allow for ad hoc view declaration, extension, or overrides, without impacting the core view files.  Enormous flexibility with this feature to customize topics to any use case - now everything is fair game inside the topic specifically.

<Frame>
  <iframe />
</Frame>


# August 9, 2024
Source: https://docs.omni.co/demos/2024/20240809

Sticky visualization settings, better auto-vis, unlimited downloads, and more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Better, stickier visualization settings + autovis (soon)

*`Workbook` `Dashboards` `Visualization`*

Enormous improvements to stickiness in visualization settings and auto-vis.  Now chart facets will retain even after query changes; toggling visualization types will retain settings; and auto visualization will retain tuned settings.  The changes feel amazing after some internal testing, should see these shortly in the app

<Frame>
  <iframe />
</Frame>

## Unlimited downloads (soon)

*`Workbook` `Dashboards` `Tables`*

A preview of unlimited downloads - now you can take as much data as you want (with some time out limits) out of the Omni app

<Frame>
  <iframe />
</Frame>

## Faster dashboards, smaller models

*`Dashboards`*

Huge improvements to slim down the model size on dashboard loads to only the dependencies needed, often reducing dashboard download size by an order of magnitude for large models

<Frame>
  <iframe />
</Frame>

## Abstract models

*`Modeling`*

New `abstract` files in the model allow for fields, views, topics declarable without attachment to a table - this opens up new use cases for model inheritance and layering we'll be highlighting soon

<Frame>
  <iframe />
</Frame>

## Better filter dropdowns and tooltip refinement (soon)

*`Dashboards` `Workbook`*

Lots of improvements to filters - cleaner, searchable dropdowns, plus some tuning of our tooltips through the app

<Frame>
  <iframe />
</Frame>

## Cleaner single select filter (launched)

*`Dashboards` `Filters`*

Some improvements to the UX on single-select filters

<Frame>
  <iframe />
</Frame>

## Conditional / nested templated filters (launched)

*`Modeling`*

Layered templated filters for complex model parameterization

<Frame>
  <iframe />
</Frame>

## Sparse labels via advanced vis

*`Visualization` `Workbook` `Dashboards`*

A quick demo of an advanced vis with sparse data labels as we build out native coverage

<Frame>
  <iframe />
</Frame>


# August 16, 2024
Source: https://docs.omni.co/demos/2024/20240816

Unlimited downloads, even more custom visualizations in markdown, better advanced visualization UX, and more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Unlimited downloads + clean modal (launching this week)

*`Export` `Workbook` `Tables`*

The launch of unlimited downloads, including formatted or unformatted toggle, and custom row limits.  Also new affordances for hidden columns in result sets and how they are handled during export.

<Frame>
  <iframe />
</Frame>

## Better downloads with hidden columns

*`Export` `Workbook` `Tables`*

The launch of unlimited downloads, including formatted or unformatted toggle, and custom row limits.  Also new affordances for hidden columns in result sets and how they are handled during export.

<Frame>
  <iframe />
</Frame>

## Even more custom visualizations via iFrame (launched)

*`Visualization` `Workbook`*

New functionality that allows markdown tiles to serve completely custom visualizations (non-Vega) using data in results + POST message framework to render custom iframes

<Frame>
  <iframe />
</Frame>

## Better advanced vis saving (soon)

*`Workbook` `Visualization`*

Simpler UX for advanced visualizations, including retaining config with other UI vis config changes

<Frame>
  <iframe />
</Frame>

## Dashboard themes applied in UI (launched)

*`Dashboards` `Embed`*

Apply dashboard themes (both internal BI and embed) directly from the UI - no more JSON handling to apply dashboard themes

<Frame>
  <iframe />
</Frame>

## More magical dimension fill (launched)

*`Workbook` `Modeling`*

More magical dimension fill.  Sometimes fill is desirable even with two dimensions (say date + day-of-week).  Now rather than pairwise fill across both, Omni is smart and it all just works

<Frame>
  <iframe />
</Frame>

## Update query views from UI (launched)

*`Modeling` `Workbook`*

Update vs save for query views - some better workflows for tuning query views while retain model underneath

<Frame>
  <iframe />
</Frame>


# August 23, 2024
Source: https://docs.omni.co/demos/2024/20240823

Embed dashboard linking, send to Google Sheets, calculations on SQL, and 11 more!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard linking inside the iFrame

*`Dashboards` `Embed`*

New functionality to create links between embedded dashboards *inside* the iframe.  No more tearing down and rebuilding iframes, just super fast linking to make navigation feel 100% native

<Frame>
  <iframe />
</Frame>

## Google Sheets scheduler destination

*`Dashboards` `Scheduler`*

A pair of Zapier hooks to directly drop data into Google Sheets from Omni - functionality for both creating a new tab with data or overwriting the existing scheduled object.

<Frame>
  <iframe />
</Frame>

## SQL improvements - resize window + early work on spreadsheets

*`Workbook` `Sql`*

More work on calculations and sorting of SQL results - all the Excel goodness on top of raw SQL queries.  Also some nice improvements to space management for SQL including drag sizing on the SQL block.

<Frame>
  <iframe />
</Frame>

## dbt SQL in the UI

*`Sql` `Workbook` `dbt`*

New mode to write dbt SQL from the UI, including  references for simple push down to dbt

<Frame>
  <iframe />
</Frame>

## Embed URL builder improvements (especially for vanity domains)

*`Embed`*

Improvements to the SDK for vanity domains + a tool for URL building without the SDK

<Frame>
  <iframe />
</Frame>

## Model layering / extending with abstract

*`Modeling`*

The near-launch of abstract model objects - allowing complex model and field layering, and setting up the groundwork for remote dependencies in the data model

<Frame>
  <iframe />
</Frame>

## Topic descriptions

*`Workbook` `Modeling`*

Topic descriptions - better metadata to help end users

<Frame>
  <iframe />
</Frame>

## Workbook filter faceting controls

*`Workbook` `Modeling`*

Filter faceting control in the workbook - now filters on dashboard or the workbook can optionality filter other filters (or not)

<Frame>
  <iframe />
</Frame>

## Filter suggestion from topic controls

*`Modeling` `Workbook` `Filters` `Dashboards`*

Suggest from topic - for when you want to curate filter suggests based on a specific topic rather than the default behavior

<Frame>
  <iframe />
</Frame>

## Dynamic DB connections in the UI

*`Modeling` `Workbook`*

The launch of dynamic connections in branches allowing swapping to different databases directly from the workbook or dashboard for more complex use cases

<Frame>
  <iframe />
</Frame>

## Multi-line text support for vis

*`Workbooks` `Visualization`*

Multi-line support for axes labels, point labels, and fields names

<Frame>
  <iframe />
</Frame>

## Embed theme controls in the UI

*`Embed` `Dashboards`*

Embed themes can now be applied directly from the UI rather than requiring the URL builder to specify

<Frame>
  <iframe />
</Frame>

## On this day one year / month / etc ago

*`Filters`*

A small change - now "on this day one year ago" will indeed return a day; ie periods will not return the full period, rather than the specific date.

<Frame>
  <iframe />
</Frame>

## Advanced editor for pie charts

*`Workbook` `Visualization`*

<Frame>
  <iframe />
</Frame>


# August 30, 2024
Source: https://docs.omni.co/demos/2024/20240830

Drill queries, dashboard links, TEXT() promotion, and more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Drill queries

*`Workbook` `Dashboards`*

An early look at drill-by-query - more flexibility to build full queries for drill down.  This also lays the groundwork for drilling into visualizations

<Frame>
  <iframe />
</Frame>

## Instant dash linking (with filters)

*`Dashboards` `Embed`*

The launch of dashboard instant links - easily tab between dashboards, even inside iframes for much richer embedded experiences

<Frame>
  <iframe />
</Frame>

## Promote TEXT() dates from Excel to model

Model pushdown for TEXT() around dates - slowly building the ability to push as many Excel functions as possible into the data model

<Frame>
  <iframe />
</Frame>

## Schedule without titles + JSON download and scheduling

*`Scheduler` `Export`*

Two new scheduler and download knobs- Schedule without headers and titles

* Download or schedule as JSON

<Frame>
  <iframe />
</Frame>

## Escape filters for measures

*`Modeling` `Workbook`*

Escape query filters for measures - allowing even more flexible compare-to-population approaches

<Frame>
  <iframe />
</Frame>

## Icons for model URLs

*`Modeling` `Workbook` `Dashboards`*

Icons for URLs in the model

<Frame>
  <iframe />
</Frame>

## Better IDE readability with tabbing

Better IDE readability vis-a-vis tabs in YAML

<Frame>
  <iframe />
</Frame>

## Better filters UX (especially long suggestions)

*`Filtering` `Workkbook` `Dashboards`*

Better filter UX with long filter suggestions (resize and hover)

<Frame>
  <iframe />
</Frame>

## Embedding PDFs and documents via markdown

Embedding PDFs and other documents via markdown iframes (think contracts next to customer data)

<Frame>
  <iframe />
</Frame>

## Azure AD with SCIM

*`Administration`*

New support for Azure AD with SCIM for complex user management

<Frame>
  <iframe />
</Frame>

## Snowflake info schema installable model

*`Modeling` `Workbook` `Dashboards`*

Our first modeling code pattern for the Snowflake info schema - usage and billing info, soon to be installable

<Frame>
  <iframe />
</Frame>


# September 6, 2024
Source: https://docs.omni.co/demos/2024/20240906

Workbook Drafts Preview, SFTP Scheduling, Embedded Content Management, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Workbook drafts preview

*Luke Bowerman · `Workbook` `Dashboards`*

A first look at the new saving and editing workflow for workbooks.  This is a full rebuild of the editing workflow that underpins content as code as well as simpler deployment of complex changes, including alongside model changes.  Plenty of discussion as well on how to tune the experience as we approach launch.

<Frame>
  <iframe />
</Frame>

## SFTP scheduling

*Corey Ruderman · `Scheduler`*

The launch of scheduling to SFTP servers from Omni.  Now recurring data delivery use cases for customers and partners can be served trivially from the UI.

<Frame>
  <iframe />
</Frame>

## Embedded content management

*Elliot Park · `Embed` `Dashboards`*

An early look at bringing the entire folder and navigation system for dashboards to embedded users.  All of the saving and curation of dashboards in the core app will soon be accessible to any embedded deployment as well.

<Frame>
  <iframe />
</Frame>

## Cancel query filters for filtered measures

*Steven Talbot · `Modeling` `Filters` `Workbook`*

New functionality to ignore query-specific filters in favor of a filtered measure's specific filters.  This allows for escaping filters comparing to population totals over specific filters, and also underpins some new work for removing pivots from period-over-period for way easier calculations and layouts.

<Frame>
  <iframe />
</Frame>

## Faster IDE with large models

*Steven Talbot · `Modeling`*

Improved handling of large models in the IDE.  Instead of loading everything too frequently, we manage the payload to reduce network traffic and speed up page loads for modelers.

<Frame>
  <iframe />
</Frame>

## Adjustable topics on dashboard filters

*Jamie Davidson · `Dashboards` `Filtering`*

Quick new feature to allow tuning the topic for a dashboard filter without rebuilding or remapping.

<Frame>
  <iframe />
</Frame>


# September 13, 2024
Source: https://docs.omni.co/demos/2024/20240913

Global color palettes, cross-tab spreadsheet references and 12 (?!) more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Global color palettes

*Gustav Staprans · `Visualization` `Administration`*

A first look at global color palette controls - now manage palettes for the Omni environment including diverging and gradient palettes with a full admin UI

<Frame>
  <iframe />
</Frame>

## Cross tab cell references

*Cathy Lennon · `Calcs` `Workbook`*

Why isn't calling data from another query as easy as Excel or Sheets?  Just reference the field and put data next to each other.  Now you can with simple cross-sheet cell references to bring queries next to each other without joins or models or lookups, just "="

<Frame>
  <iframe />
</Frame>

## Smarter, stickier vis config

*Nate Agrin · `Visualization`*

The launch of sticky vis config over a huge number of user actions in the UI.  Smarter, better visualization as you refine queries in the app - sticky colors, retaining changes between different vis types, smarter retention of facets on new fields.

<Frame>
  <iframe />
</Frame>

## Branches for external Git pull requests

*Conrad Slimmer · `Modeling`*

New settings for git to create branches for pull requests created outside of Omni, for more robust change management in product for folks using git outside the app

<Frame>
  <iframe />
</Frame>

## Dynamic schemas in dbt

*Buck Ryan · `dbt` `Modeling`*

New dynamic schema controls with dbt

<Frame>
  <iframe />
</Frame>

## Better branch creation

*Conrad Slimmer · `Modeling` `Workbook`*

Smarter branch creation - adding existing changes on save to the new branches

<Frame>
  <iframe />
</Frame>

## Download for hidden columns

*Conrad Slimmer · `Export` `Workbook` `Dashboards`*

Controls to download hidden columns for curated data tables

<Frame>
  <iframe />
</Frame>

## Embed user management API

*Chris Merrick · `Embed` `Adminstration`*

A new API to manage embed users (list, delete), in order to manage privacy deletion in bulk

<Frame>
  <iframe />
</Frame>

## TEXT() pushdown for numerics and dates

*Cathy Lennon · `Calcs` `Workbook`*

The ability to push down more TEXT() metrics to the model - for both numeric formats like percent or decimal, and datetime formats

<Frame>
  <iframe />
</Frame>

## Content owner re-assignment

*Eli Cohen · `Workbook` `Dashboards`*

New controls to re-assign ownership for content

<Frame>
  <iframe />
</Frame>

## Better model join validation

*Steven Talbot · `Modeling`*

Better validation for joins through the context of topics

<Frame>
  <iframe />
</Frame>

## Grouping measures outside pivots

*Steven Talbot · `Workbook`*

Grouping measures inside pivots to cluster metrics instead of dimensions

<Frame>
  <iframe />
</Frame>

## IDE folding

*Jared Hardy · `Modeling`*

Folding in the IDE to open up quicker, easier navigation in large topics or view files

<Frame>
  <iframe />
</Frame>

## Aliased joins and renamed metrics inside topics (design pattern)

*Colin Zima · `Workbook` `Modeling`*

A quick design pattern for aliased joins inside topics, including renaming metrics specific to the topic (instead of globally)

<Frame>
  <iframe />
</Frame>


# September 20, 2024
Source: https://docs.omni.co/demos/2024/20240920

Exploding pivots, embedded dashboard sharing, global color palettes, and much more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Exploding pivots

*Steven Talbot · `Workbook` `Dashboards`*

A huge step forward in the flexibility of working with pivoted data.  Now pivots can be instantly turned into filtered measures.  This opens up a variety of new functionality:

* Flexible layout of calculations - work with pivots just like simpler data
* Color controls over pivoted series
* Rearranging pivot order ad hoc
* Keeping the top N pivots and allocating other series to "other"

The changes will also impact period-over-period, so now periods can be built with simple diffs and percentage changes.

<Frame>
  <iframe />
</Frame>

## Embedded dashboard saving and sharing

*Elliot Park · `Embed` `Dashboards`*

More preview of the embedded content system for saving and sharing ad hoc control inside a given tenant.

<Frame>
  <iframe />
</Frame>

## Global color palettes beta

*Gustav Staprans · `Visualization` `Embed` `Dashboards`*

Putting the finishing touches on global color palettes, including propagating tuning of the palette to live content using the global palette.  Full launch soon, but rolled out in beta to folks upon request.

<Frame>
  <iframe />
</Frame>

## Figma dashboard components

*Sarah Waterson · `Dashboards` `Design`*

Increasingly folks are building data products with full design input - we want to make it as simple as possible for design teams to be productive in their own tools.  So we've released new tools for embedded builders to design using Omni components.

<Frame>
  <iframe />
</Frame>

## Light / dark mode controls for embed URLs

*Nate Agrin · `Embed` `Dashboards` `Workbook`*

New controls for setting light / dark / dynamic for embedded URLs.  This means embedded builders can control their experience a bit more for end users.

<Frame>
  <iframe />
</Frame>

## Axis tick count

*Nate Agrin · `Visualization`*

New controls for tick count on the axis, allowing more sparse axis value labels - especially relevant for smaller numbers or non-decimals.

<Frame>
  <iframe />
</Frame>

## Map regions (zip, state, country)

*Rob Miller · `Visualization`*

Soon to launch region maps in Omni.  Here we demo states, but zip and countries will also be launching soon.

<Frame>
  <iframe />
</Frame>

## Color controls for map points

*Rob Miller · `Visualization`*

New config that opens up color controls on native lat, long maps

<Frame>
  <iframe />
</Frame>

## Snowflake native app

*Chris Merrick · `Administration`*

A quick demo of running the query application plane entirely inside Snowflake.  This will allow Omni to deploy entirely outside our infrastructure for Snowflake native apps or other deployments inside customer infrastructure.

<Frame>
  <iframe />
</Frame>


# September 27, 2024
Source: https://docs.omni.co/demos/2024/20240927

Embedded saving and sharing, map regions, period-over-period measures, Snowflake native deployment, and much more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Embed content sharing and saving

*Elliot Park, Nate Agrin · `Embed` `Workbook` `Dashboards`*

The launch of embedded content management controls.  Now users in the embed context can build and share content with teammates seamlessly.

<Frame>
  <iframe />
</Frame>

## Map regions and custom maps

*Rob Miller · `Visualization` `Workbook` `Dashboards`*

Soon to launch map regions on zoomable, pannable maps.  This will launch out of the box with the most common maps (countries, states, zips), but also offers BYO shape files for map charting on nearly anything in Omni.

<Frame>
  <iframe />
</Frame>

## Period-over-period filtered measures

*Steven Talbot · `Workbook`*

* Now period-over-period can be filtered measures series that can work as independent series as well as pivots.  This opens up much simpler calcs (think % change, and absolute change with a couple clicks) and flexible arrangement.  Plus a bunch of UX improvements to flattening pivots.

<Frame>
  <iframe />
</Frame>

## Snowflake native app

*Chris Merrick · `Administration`*

A quick demo of running the query application plane entirely inside Snowflake.  This will allow Omni to deploy entirely outside our infrastructure for Snowflake native apps or other deployments inside customer infrastructure.

<Frame>
  <iframe />
</Frame>

## Visualization axis tick spacing controls

*Nate Agrin · `Visualization`*

We've polished up the controls for axis ticks, especially for time groups.  Now builders will have fine-grain ability to tune axis breakpoints.

<Frame>
  <iframe />
</Frame>

## Trellising in advanced vis

*Nate Agrin · `Visualization`*

We've opened up size controls in our advanced Vega Lite spec.  This opens up the opportunity for trellising with some hand tuning of sizing.  This is a precursor to trellis / grid visualization controls natively in vis.

<Frame>
  <iframe />
</Frame>

## Global color palettes launch

*Gustav Staprans · `Visualization` `Administration`*

The open launch of our global color palette controls, along with some more elegant change management for folks tuning global palettes over time.

<Frame>
  <iframe />
</Frame>

## More time format options

*Sarah Waterson · `Visualization` `Workbook` `Dashboards`*

Opening up a few more time configuration controls for vis.

<Frame>
  <iframe />
</Frame>

## Drafts soft launch

*Luke Bowerman, Jared Hardy · `Workbook` `Dashboards`*

Now folks can take advantage of the new drafts workflow optionally.  Still a bit of cleanup to do for full launch, but now the full draft experience is testable by any user in the app.

<Frame>
  <iframe />
</Frame>

## Better merge conflict handling

*Steven Talbot*

Some improvements to warn when out-of-sync model changes may overwrite intermediate changes.  Now instead of developers stomping on each other editing, simple warnings can avoid unintentional overwrites.

<Frame>
  <iframe />
</Frame>

## Google Sheets export script

*James Ostergaard · `Scheduler` `Export`*

Our new script for maintaining live Omni content in Google Sheets without Zapier.

<Frame>
  <iframe />
</Frame>


# October 4, 2024
Source: https://docs.omni.co/demos/2024/20241004

dbt SQL mode, schema refresh via git, and new content permissions

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## dbt SQL mode (very soon)

*Buck Ryan · `dbt` `sql`*

A new UI mode for writing dbt SQL (ie. Jinja + refs).  Now for handwritten SQL folks can toggle into dbt SQL mode for confirming well composed SQL and results before pushing to dbt.

<Frame>
  <iframe />
</Frame>

## Git schema refresh (very soon)

*Conrad Slimmer · `Modeling`*

An early look at a new always-git mode for schema refresh.  Soon development team will have the option to also force schema refreshes through a pull request workflow.

<Frame>
  <iframe />
</Frame>

## More draft work for dashboards plus new content permission (soon)

*Luke Bowerman · `Workbook` `Dashboards` `Administration`*

Continuing work on drafts in Omni, this also offers content-level and global toggles for dashboard permissions, like blocking download or scheduling.

<Frame>
  <iframe />
</Frame>

## Richer tables (experimental)

*Nate Agrin · `Visualization` `Table`*

Some experimental work + conversation about adding more visual types to the data model.  Here we show some special handlers for hex colors that enable a more visual experience for end users.  This also sets up the groundwork for more style controls in the UI like pills for categorical fields, modeled conditional formatting, checkboxes, etc.

<Frame>
  <iframe />
</Frame>

## Global color palette launch plus rendering (launched)

*Gustav Staprans · `Administration` `Workbook` `Dashboards` `Visualization`*

The launch of global color palettes for everyone.  A bit of final cleanup to make sure these palettes carry to the renderer, and we show off a nice example in production.

<Frame>
  <iframe />
</Frame>

## Overlapping time period-over-period (launched)

*Steven Talbot · `Workbook`*

A quick demo of the live experience for period-over-period with time controls, so now even time dimensions can flexibly pull offsetting time periods with a couple clicks.

<Frame>
  <iframe />
</Frame>


# October 11, 2024
Source: https://docs.omni.co/demos/2024/20241011

New model controls for timeframes and filter value labels, more visualization configuration, and a nice demo of richer dashboard styling

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Filter value labels

*Steven Talbot · `Modeling`*

A brand new set of controls to label filter values, and pass said labels through as dynamic text.  Now filter text can be explicitly set and these values can pass through to fields for things like period-over-period or other filter-only field use case.

<Frame>
  <iframe />
</Frame>

## Better content validator

*Steven Talbot · `Modeling` `Administration`*

More functionality to understand the current overall state in the content validator - how much is errored and filtering to only errored content.

<Frame>
  <iframe />
</Frame>

## Git on non-main

*Conrad Slimmer*

New deeper git support for customers with and Omni repo that is not main.

<Frame>
  <iframe />
</Frame>

## Default timeframes

*Conrad Slimmer*

New controls to set default timeframes from the default set in Omni (date, week, month, quarter, year).  Now can be modeled explicitly.

<Frame>
  <iframe />
</Frame>

## Vis config locking

*Nate Agrin · `Visualization`*

Some pre-launch work and some conversation on locking the vis config to never reset user-inputted changes.  This would mean that even with significant query mutation, any user-facing input would remain in the visualization, reducing re-work over changes.

<Frame>
  <iframe />
</Frame>

## Draft history

*Luke Bowerman · `Workbook` `Dashboards`*

More work on draft-publish workflows with rich history on all of the drafts associated with a workbook or dashboard, and function to restore these drafts as well.

<Frame>
  <iframe />
</Frame>

## Better custom vis color palettes

*Gustav Staprans · `Visualization` `Dashboards`*

Richer UX for setting custom colors on a given visualization, mirroring the improved UX for global color palettes.

<Frame>
  <iframe />
</Frame>

## Custom colors in schedules and downloads

*Gustav Staprans · `Visualization` `Scheduler` `Dashboards`*

The last piece of work to put global color palettes into GA, allowing custom global palettes to pass to the renderer for downloads and scheduling.

<Frame>
  <iframe />
</Frame>

## NBA dashboard demo

*Jess Gaines · `Dashboards`*

A quick set of demo dashboards with stylized tables and charts for the NBA, using public data.

<Frame>
  <iframe />
</Frame>

## Better dbt schemas in IDE

*Buck Ryan · `Modeling`*

Clearer distinction between static schemas and dbt schemas in the IDE for easier model management.

<Frame>
  <iframe />
</Frame>


# October 18, 2024
Source: https://docs.omni.co/demos/2024/20241018

Smart IDE auto-complete, map regions, more dashboard CSS, embedded dashboard scheduling, 

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Intelligent IDE autocomplete (LLM powered)

*Richard Czechowski · `Modeling`*

A first look at some experimental work to bring intelligent auto-complete to the Omni IDE.  Powered by LLMs and model metadata, this would open up the opportunity to auto-model fields with simple auto-complete.  Very early work-in-progress

<Frame>
  <iframe />
</Frame>

## Map regions (near launch)

*Rob Miller · `Visualization` `Dashboards` `Workbook`*

The soon-to-launch map regions, including countries, states, counties, and zip codes out of the box, and simple workflow to BYO topojson or vector tiles.  Lots of work on making these big files performant on dashboards.

<Frame>
  <iframe />
</Frame>

## More dashboard CSS (filters popovers + buttons + more)

*Jared Hardy · `Embed` `Dashboards`*

A bunch of new CSS surface area for dashboards, plus some conversation about future work.  Want to make sure the experiences is 100% controllable for embedded deployments.

<Frame>
  <iframe />
</Frame>

## SQL sorting, calcs, formatting (soon)

*Richard Czechowski · `Sql` `Workbook`*

Another look at the work to enrich the SQL experience in Omni - simpler query construction, formatting, sorting, and all of the goodness of the Excel calculation layer on top of SQL

<Frame>
  <iframe />
</Frame>

## Embedded dashboard scheduling

*Elliot Park · `Embed` `Dashboards`*

Soon-to-launch scheduling for embedded users.  Now it will be trivial to enable dashboards via email for embed users.

<Frame>
  <iframe />
</Frame>

## Hiding axes and hiding axis labels

*Nate Agrin · `Visualization` `Workbook` `Dashboards`*

More work on vis - this time a quick demo of hiding axes labels

<Frame>
  <iframe />
</Frame>


# October 25, 2024
Source: https://docs.omni.co/demos/2024/20241025

Vis Config Locking, More Smart Autocomplete, Model Speeds-Ups and Some Table Polish

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Vis config locking

*Nate Agrin · `Visualization` `Workbook`*

The beta launch of locking the vis config.  While evolving the vis config dynamically as you query can be helpful in normal circumstances, when configs have been highly adjusted, locking the configuration to prevent updates on query structure changes offers a new alternative.

<Frame>
  <iframe />
</Frame>

## Smart SQL and IDE autocomplete

*Richard Czechowski · `Modeling` `Sql`*

More work on our intelligent autocomplete for both SQL and the IDE, allowing psuedo instant field compilation from even comments.  Show a nice example from the SQL block of a comment that automatically generates a query on the fly.

<Frame>
  <iframe />
</Frame>

## Better table search in all views and fields

*Steven Talbot*

Some significant improvements to search over massive database schemas.

<Frame>
  <iframe />
</Frame>

## Better templating handling in SQL compilation

*Steven Talbot · `Modeling` `Workbook`*

Some mostly invisible tweaks to how SQL is compiled with templating, reducing rare errors and improving performance.

<Frame>
  <iframe />
</Frame>

## Column rename polish

*Jared Hardy · `Workbook` `Table`*

Some new improvements to column header renaming, avoiding accidental resorts and making the app more delightful.

<Frame>
  <iframe />
</Frame>


# November 1, 2024
Source: https://docs.omni.co/demos/2024/20241101

User Specific Timezones, AI Query Tuning, Versioning Dashboards, and Much More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## User specific timezones

*Steven Talbot · `Administration` `Workbook` `Dashboards` `Embed`*

Users can now explicitly set their own timezones for dates in Omni.  This also includes controls for setting user-specific timezones on the fly in embedded contexts.

<Frame>
  <iframe />
</Frame>

## AI model tuning

*Gustav Staprans · `Workbook` `Modeling`*

Now descriptions can be used to tune the AI query in Omni.  This allows a vehicle for passing example filter values or other metadata to improve hit rates.

<Frame>
  <iframe />
</Frame>

## Dynamic schemas

*Conrad Slimmer · `Modeling`*

An early view of our work to allow for parameterizing schemas via filters (plus a quick preamble on modeling the debug logs, and why we needed it!)

<Frame>
  <iframe />
</Frame>

## Dashboard drafts and history

*Alisa Tatarinova · `Dashboards` `Workbook`*

A quick preview of history of drafted and archive dashboards.  This now means not only workbook querying and visualization can be versioned, but also dashboard layouts.  This will launch as part of the new publishing workflows.

<Frame>
  <iframe />
</Frame>

## Single select filters in model

*Steven Talbot · `Modeling` `Filters` `Workbook`*

Now string fields in the model can explicit be set to single-select dropdowns, allowing for cleaner usage of items like filter-only fields for templated filters or parameterization.

<Frame>
  <iframe />
</Frame>

## Cache debugging tools

*Steven Talbot · `Modeling` `Administration`*

Some new tools (mostly for Omnis) to debug caching hit rates.

<Frame>
  <iframe />
</Frame>

## dbt reader

*Buck Ryan · `dbt` `Modeling`*

An early preview of our dbt reader in Omni.  This allows Omni developers to view the entire dbt git repo, for simpler debugging rather than having to jump across apps to understand the dbt workflow beneath Omni.

<Frame>
  <iframe />
</Frame>

## Scheduler sender name and email controls

*Corey Ruderman · `Scheduler`*

New controls that allow admins to control the sender and reply-to email on scheduled emails via Omni.

<Frame>
  <iframe />
</Frame>

## Halloween themes

*Sarah Waterson · `Dashboards` `Embed`*

A few fun themes we made to celebrate Halloween and dashboard CSS controls.

<Frame>
  <iframe />
</Frame>

## Higher resolution PNGs in deliveries

*Jared Hardy · `Scheduler`*

We improved the resolution on PNG deliveries to improve the mobile dashboard experience in particular.

<Frame>
  <iframe />
</Frame>

## Treemaps advanced visualization

*Colin Zima · `Visualization`*

A quick view of a new advanced visualization spec for treemaps.

<Frame>
  <iframe />
</Frame>


# November 8, 2024
Source: https://docs.omni.co/demos/2024/20241108

AI Tuning, Lots of Visualization Improvements, Better Date Filtering, and Our First Customer Demo

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI conversation and better training hooks

*Arielle Strong, Gustav Staprans · `Blobby` `Workbook`*

Our AI is getting smarter.  Now Blobby can answer data questions like suggesting queries or offering follow-up questions.  Additionally we've added some metadata hooks in the model to improve how fields are selected, add example values, and more.

<Frame>
  <iframe />
</Frame>

## Maps guest demo with CamoAG

*`Visualization` `Dashboards`*

Chris gives us an overview of the different mapping and tiling systems in use at Camo, and shows off a few of the new Omni region mapping visualizations.

<Frame>
  <iframe />
</Frame>

## Map regions launch

*Rob Miller · `Visualization` `Dashboards`*

The general launch of map regions in GA, plus a demo of the new support for rendering these through the scheduler and more intelligent viewport setting when data gets filtered.

<Frame>
  <iframe />
</Frame>

## Visualization axis tick controls

*Nate Agrin · `Visualization`*

Lots of new toggles to make axes exactly right.  Now you can hide/show ticks, the axis line, and more.

<Frame>
  <iframe />
</Frame>

## Axis date format improvements

*Nate Agrin · `Visualization`*

We polished up the default datetime formats on x-axis to make it more intelligent and easier to read.

<Frame>
  <iframe />
</Frame>

## SQL autocomplete improvements

*Richard Czechowski · `Sql` `Workbook`*

Still striving to create a best-in-class SQL writing experience.  We overhauled the autocomplete UX to be more intelligent and prettier.

<Frame>
  <iframe />
</Frame>

## Change to date endpoints with filters

*Steven Talbot · `Workbook` `Filtering` `Dashboards`*

Date filters using between were set to mirror Looker's behavior, which means that the end date was non-inclusive.  We've heard lots of feedback that folks don't like that and have now changed the behavior and added an additional tooltip to explain (ie. now 2024-01-01 to 2024-06-01 will include June 1st rather than excluding it).

<Frame>
  <iframe />
</Frame>

## Bugfix for dash tiles moving on save

*Chris Merrick · `Dashboards`*

We finally got to the root of a frustrating bug that was moving visualizations on the dashboard after unrelated edits.

<Frame>
  <iframe />
</Frame>

## More drafts preview

*Luke Bowerman · `Workbook` `Dashboards`*

Luke gives us another demo of the soon-to-release drafts workflow.

<Frame>
  <iframe />
</Frame>

## Parameterized connections with user attributes

*Steven Talbot · `Administration` `Modeling`*

New tooling that allows database connections to be parameterized via user attributes.  This offers some optionality around permissioning (secure connection vs open connection) or even allowing large Snowflake warehouses for specific users or use cases.

<Frame>
  <iframe />
</Frame>

## Embed user permissions changes

*Nate Agrin · `Embed` `Administration`*

We've tuned the handling of embed user permissions.  Rather than using connection defaults, now external embed users will require explicit permission setting in the URL construction.  This makes app intent more clear and offers more nuance for internal/external shared deployments.

<Frame>
  <iframe />
</Frame>

## Model editing API

*Jamie Davidson · `Api` `Administration` `Modeling`*

<Frame>
  <iframe />
</Frame>


# November 15, 2024
Source: https://docs.omni.co/demos/2024/20241115

Flexible Totals (Including Dimensions and Calc), Calculations with Controls, Better SQL, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Totals for everything

*Cathy Lennon · `Calcs` `Workbook`*

Totals for everything!  Now users can toggle between native totals (ungrouped aggregates), simple totals, min, max, and count on any field.  This includes bring flexible totals to dimensions (!) and calculations (!).

<Frame>
  <iframe />
</Frame>

## Controls with calcs (calcs with field swappers)

*Jamie Davidson · `Calcs` `Workbook` `Dashboards`*

Now calcs work seamlessly with controls (field swappers).  So dashboards with dynamic timeframes, dimension swappers, and measure swappers can seamless build calculations on top.

<Frame>
  <iframe />
</Frame>

## Better SQL autocomplete + run highlighted SQL

*Richard Czechowski · `Sql` `Workbook`*

More work to polish up our SQL autocomplete system, then a demo of run highlighted SQL for folks that need to test as they build larger SQL statements.

<Frame>
  <iframe />
</Frame>

## in\_query

*Steven Talbot · `Modeling` `Workbook`*

Now in\_query works with both fields and views, plus a quick demo of how join trees are handled for in\_query.  Making sure whatever crazy dynamic field handlers you need are buildable.

<Frame>
  <iframe />
</Frame>

## Embedded dashboard sharing demo

*Elliot Park · `Embed` `Workbook` `Dashboards`*

A first look at the embedded dashboard building and sharing workflow (embedded content management).  Now embedded users can build their own dashboards and share with co-workers just like native app users.

<Frame>
  <iframe />
</Frame>

## Dashboard CSS docs that are beautiful

*Jared Hardy · `Embed` `Dashboards`*

Jared gives us a preview of the new documentation explaining all of the CSS control for dashboards in Omni.

<Frame>
  <iframe />
</Frame>

## Better form entry

*Luke Bowerman*

Some polish to make forms always focus to complete / save on Enter

<Frame>
  <iframe />
</Frame>

## Sort favorites alphabetically

*Luke Bowerman*

<Frame>
  <iframe />
</Frame>

## New toast system

*Luke Bowerman*

A quick demo of our new in-app toast system

<Frame>
  <iframe />
</Frame>


# November 22, 2024
Source: https://docs.omni.co/demos/2024/20241122

*Actual* Spreadsheets, Mapping Vis Colors in the Data Model, and Much More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## *Actual* spreadsheets

*Arielle Strong · `Workbook` `Dashboards`*

A first look at a new science project in Omni to add the *full* power of spreadsheets to the app. 100% of the freedom of the spreadsheet for presenting and manipulating governed data out of the warehouse. Lots to explore here, but some beautiful reports are opened up. Ping us if you'd like an early look.

<Frame>
  <iframe />
</Frame>

## Color mapping

*Rob Miller · `Workbook` `Dashboards` `Visualization` `Modeling`*

An early preview of some new controls to lock color attributes on a modeled object. This includes setting default colors for a measure, or setting the colors of specific values in a dimensions, like regions, customers, or other attributes. Goal is promotion from the UI to nicely modeled structure.

<Frame>
  <iframe />
</Frame>

## Join ERD

*James Ostergaard · `Modeling`*

A little python app James wrote to better understand all the relationships in the Omni environment.

<Frame>
  <iframe />
</Frame>

## More Git for schema refresh

*Conrad Slimmer · `Git` `Modeling`*

More work to make sure everything in Omni can go through git, including schema refresh

<Frame>
  <iframe />
</Frame>

## Dynamic connection environments

*Steven Talbot · `Modeling` `Administration`*

<Frame>
  <iframe />
</Frame>

## Customizing topics

*Colin Zima · `Modeling` `Workbook`*

A quick modeling pattern for customizing topics ad hoc (view sorting, labeling, etc)

<Frame>
  <iframe />
</Frame>

## More drafts

*Luke Bowerman · `Workbook` `Dashboards`*

Continuing to polish up the drafts experience, plus more navigation in product like faster new analysis links

<Frame>
  <iframe />
</Frame>

## Vis odds and ends

*Nate Agrin · `Visualization` `Workbook`*

Bunch of vis improvements for hiding inactive controls, and currency handling in app

<Frame>
  <iframe />
</Frame>

## Embed content sharing polish

*Elliot Park · `Embed`*

More work on the embedded content sharing

<Frame>
  <iframe />
</Frame>

## KPI alignment in renderer

*Jared Hardy · `Scheduler` `Dashboards` `Visualization`*

Some small tweaks to make KPIs export better

<Frame>
  <iframe />
</Frame>


# December 2, 2024
Source: https://docs.omni.co/demos/2024/20241202

Simpler dashboard URLs, tab descriptions, calc descriptions, table and vis view, topic files, and more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Better URLs with filters

*Nate Agrin · `Dashboards`*

A first look at our new dashboard URLs - now folks can easily work around URL encoding for simpler parameterization and control

<Frame>
  <iframe />
</Frame>

## Tab and dash tile descriptions

*Alisa Tatarinova · `Workbook` `Dashboards`*

New descriptions for workbook tabs and dashboard tiles - more context on everything

<Frame>
  <iframe />
</Frame>

## Calc descriptions

*Jamie Davidson · `Workbook` `Dashboards`*

Now descriptions can be added to calculations - full presentation control on calcs as well

<Frame>
  <iframe />
</Frame>

## Dimension hierarchical drilling

*Steven Talbot · `Workbook` `Dashboards`*

Rounding out our drilling controls with hierarchical drilling on dimensions to enable clean breakout of metrics in multiple ways

<Frame>
  <iframe />
</Frame>

## SQL calc launch

*Steven Talbot · `Sql` `Calcs`*

The launch of calcs on SQL - all the goodness of Excel on top of pure SQL result sets

<Frame>
  <iframe />
</Frame>

## Topic files and more

*Conrad Slimmer · `Modeling`*

An early look at new model organization - breaking topics into individual files for simpler nav and readability; plus lots of work on better model layering for included schemas

<Frame>
  <iframe />
</Frame>

## Vis and table *together*

*Jared Hardy · `Workbook`*

A new toggle to view the visualization and data at the same time.

<Frame>
  <iframe />
</Frame>

## More, better accessibility

*Jared Hardy · `Workbook` `Dashboards` `Administration`*

Jared put a bunch of love into accessibility throughout the app, to make nav easier for everyone

<Frame>
  <iframe />
</Frame>

## Better table bars

*Sarah Waterson · `Workbook` `Dashboards` `Visualization`*

Sarah added a bit of polish to our table visualizations to make sure they always tell the full story

<Frame>
  <iframe />
</Frame>

## Resize everything

*Jared Hardy · `Workbook` `Sql`*

We made resizing everything easier - field pickers, SQL blocks, vis configs - everything is draggable now.

<Frame>
  <iframe />
</Frame>

## Sorting subtotals

*Steven Talbot · `Workbook` `Dashboards`*

Now subtotaled tables sort just like everything else (at any grain)

<Frame>
  <iframe />
</Frame>

## Drafts migration tools

*Luke Bowerman · `Workbook` `Dashboards` `Administration`*

Some internal tooling to make sure the transition to drafts is smooth

<Frame>
  <iframe />
</Frame>


# December 6, 2024
Source: https://docs.omni.co/demos/2024/20241206

dbt Reader, Nearly-Alpha Spreadsheets, Inline IDE Auto-Correct, and Lots More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## dbt reader

*Buck Ryan · `Dbt` `Modeling`*

The full dbt repo is now visible inside Omni. No more jumping back and forth, just easy lookup of your entire dbt model from inside Omni, including opening reconciled dbt SQL to test live.

<Frame>
  <iframe />
</Frame>

## Nearly-alpha spreadsheets (and in schedules!)

*Arielle Strong · `Workbook` `Dashboards` `Visualization` `Calcs`*

Now spreadsheets also render through the scheduler, which means we're getting closer to opening it up for \[very early] testers. Still much work to do, but ping us if you want to be on the list for the very alpha program.

<Frame>
  <iframe />
</Frame>

## Inline IDE auto-correct

*Richard Czechowski · `Modeling`*

Bringing error metadata and smart correction inline to the IDE.

<Frame>
  <iframe />
</Frame>

## Subtotal sorting

*Steven Talbot · `Workbook` `Dashboards`*

Some nice custom sorting additions to subtotaling to order differentially inside hierarchies.

<Frame>
  <iframe />
</Frame>

## Model data in analytics

*Chris Merrick · `Administration` `Modeling`*

We're starting to bring model metadata into the Omni data model for sharing model metadata and usage via analytics

<Frame>
  <iframe />
</Frame>

## Better dashboard filter URLs with dates

*Nate Agrin · `Dashboards`*

Finishing off the work on better dashboard URLs to include dates.

<Frame>
  <iframe />
</Frame>

## Drafts polish

*Luke Bowerman · `Workbook` `Dashboards`*

More tidying up of the new edit workflow - should be launching next week or two.

<Frame>
  <iframe />
</Frame>

## Second-to-last in KPI

*Sarah Waterson · `Workbook` `Dashboards` `Visualization`*

A small tweak to KPI tiles that now let end users call the second-to-last row for easier building

<Frame>
  <iframe />
</Frame>

## Sunburst advanced vis

*Colin Zima · `Visualization` `Dashboards`*

New pattern for sunburst charts via Vega Lite

<Frame>
  <iframe />
</Frame>


# December 13, 2024
Source: https://docs.omni.co/demos/2024/20241213

Color Modeling Launch, More Excel Functions, Dynamic Column Modeling, Drafts Refinement and Lots of Polish

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Color modeling launch

*Rob Miller · `Visualization` `Modeling`*

The launch of stable colors in the data model. Now your dimensions can maintain consistent coloring throughout the app, or even just for a particular workbook. We're excited to also open up push down from the UI to close the loop and make modeling color point and click.

<Frame>
  <iframe />
</Frame>

## EOMONTH() and IFERROR()

*Colin Zima · `Calcs` `Workbook`*

More functions for the Excel library, always broadening the surface area.

<Frame>
  <iframe />
</Frame>

## SQL parameters

*Steven Talbot · `Modeling` `Sql` `Workbook`*

A new column parameter type for modeling injected SQL. Now flexible column pickers are simple to build

<Frame>
  <iframe />
</Frame>

## Draft modeling workflow

*Luke Bowerman · `Workbook` `Modeling` `Dashboards`*

Continuing to refine for the more complex drafts workflows - especially between branches and drafts. Want to make sure it all feels natural and elegant when editing content in Omni.

<Frame>
  <iframe />
</Frame>

## IDE UX polish

*Jared Hardy · `Modeling`*

Bunch of nice IDE polishing - resizable gutter, quick folding, and better dark mode.

<Frame>
  <iframe />
</Frame>

## More color palettes

*Sarah Waterson · `Workbook` `Visualization`*

A few more color palettes, and some gradients meant to couple nicely with our divergent palettes for more cohesive dashboards.

<Frame>
  <iframe />
</Frame>


# December 20, 2024
Source: https://docs.omni.co/demos/2024/20241220

Controls in Tiles, Topic-less AI, and Lots of Small Wins Throughout the App

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Multi-select controls and tile-specific controls

*Jamie Davidson · `Dashboards`*

A pair of huge new features for streamlining the dashboard experience:- Multi-select controls that allow for building a table from an array of columns that can be dynamically chosen (think pick N of the selected columns through a filter)

* Tile-specific controls that lift the column picking interaction from the top of the dashboard on to one specific tile in-line (still needs design, but huge interactivity win).

<Frame>
  <iframe />
</Frame>

## Topic-less AI

*Gustav Staprans · `Ai` `Workbook`*

We're making Blobby smarter - now rather than forcing selection Blobby can find the best topic to answer your question. Makes querying that much easier for end users.

<Frame>
  <iframe />
</Frame>

## More dimension colors (with `else`)

*Rob Miller · `Visualization` `Modeling`*

A new else field for coloring dimensions, giving more flexibility for color settings over highly fragmented dimensions. Also a bit of discussion of all the ways to format colors (RGB, Hex, CSS, etc)

<Frame>
  <iframe />
</Frame>

## Topic `display_order`

*Conrad Slimmer · `Modeling` `Workbook`*

New model control to set topic ordering in the workbook

<Frame>
  <iframe />
</Frame>

## Dutch number formats

*Steven Talbot · `Modeling`*

Couldn't tell you what a Dutch number format is, but now we have them!

<Frame>
  <iframe />
</Frame>

## New Vega config abstraction

*Nate Agrin · `Visualization`*

Some behind-the-scenes work to allow better composability as we create Vega specs for our visualizations. Outcome would be better feature development velocity for vis.

<Frame>
  <iframe />
</Frame>

## Field picker dimension measure faceting

*Luke Bowerman · `Workbook`*

Some new search controls for quickly finding dimensions or measures in the field picker (quick one flagged by a customer).

<Frame>
  <iframe />
</Frame>

## Timezones on dashboard runtime

*Sarah Waterson · `Dashboards`*

A quick tweak to add timezone to dashboard runtime metadata for easier undertsanding.

<Frame>
  <iframe />
</Frame>

## Better draft promotion

*Luke Bowerman · `Workbook` `Dashboards` `Modeling`*

Some helper text to show how promotion should work inside drafts

<Frame>
  <iframe />
</Frame>

## Embed event messaging docs

*Nate Agrin · `Embed`*

Bit more meat on our docs for the embed messaging framework. This opens up lots of UX extensibility for embedded developers for on-load events, on-click events, or a variety of other end user actions.

<Frame>
  <iframe />
</Frame>

## Region controls for Omni support

*Chris Merrick · `Administration`*

New admin toggles to only allow support coverage from different regions (North America or Europe or anywhere).  May be appropriate for different data protection postures.

<Frame>
  <iframe />
</Frame>


# 2024 Demos
Source: https://docs.omni.co/demos/2024/index

Browse all 2024 Omni product demo videos covering AI queries, dashboard themes, custom visualizations, embedding, and more.

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.
</Note>

* [December 20, 2024](/demos/2024/20241220): Controls in Tiles, Topic-less AI, and Lots of Small Wins Throughout the App
* [December 13, 2024](/demos/2024/20241213): Color Modeling Launch, More Excel Functions, Dynamic Column Modeling, Drafts Refinement and Lots of Polish
* [December 6, 2024](/demos/2024/20241206): dbt Reader, Nearly-Alpha Spreadsheets, Inline IDE Auto-Correct, and Lots More
* [December 2, 2024](/demos/2024/20241202): Simpler dashboard URLs, tab descriptions, calc descriptions, table and vis view, topic files, and more
* [November 22, 2024](/demos/2024/20241122): *Actual* Spreadsheets, Mapping Vis Colors in the Data Model, and Much More
* [November 15, 2024](/demos/2024/20241115): Flexible Totals (Including Dimensions and Calc), Calculations with Controls, Better SQL, and More
* [November 8, 2024](/demos/2024/20241108): AI Tuning, Lots of Visualization Improvements, Better Date Filtering, and Our First Customer Demo
* [November 1, 2024](/demos/2024/20241101): User Specific Timezones, AI Query Tuning, Versioning Dashboards, and Much More
* [October 25, 2024](/demos/2024/20241025): Vis Config Locking, More Smart Autocomplete, Model Speeds-Ups and Some Table Polish
* [October 18, 2024](/demos/2024/20241018): Smart IDE auto-complete, map regions, more dashboard CSS, embedded dashboard scheduling,
* [October 11, 2024](/demos/2024/20241011): New model controls for timeframes and filter value labels, more visualization configuration, and a nice demo of richer dashboard styling
* [October 4, 2024](/demos/2024/20241004): dbt SQL mode, schema refresh via git, and new content permissions
* [September 27, 2024](/demos/2024/20240927): Embedded saving and sharing, map regions, period-over-period measures, Snowflake native deployment, and much more
* [September 20, 2024](/demos/2024/20240920): Exploding pivots, embedded dashboard sharing, global color palettes, and much more
* [September 13, 2024](/demos/2024/20240913): Global color palettes, cross-tab spreadsheet references and 12 (?!) more
* [September 6, 2024](/demos/2024/20240906): Workbook Drafts Preview, SFTP Scheduling, Embedded Content Management, and More
* [August 30, 2024](/demos/2024/20240830): Drill queries, dashboard links, TEXT() promotion, and more
* [August 23, 2024](/demos/2024/20240823): Embed dashboard linking, send to Google Sheets, calculations on SQL, and 11 more!
* [August 16, 2024](/demos/2024/20240816): Unlimited downloads, even more custom visualizations in markdown, better advanced visualization UX, and more
* [August 9, 2024](/demos/2024/20240809): Sticky visualization settings, better auto-vis, unlimited downloads, and more
* [August 2, 2024](/demos/2024/20240802): Dashboard themes, dashboard vanity URLs, XLOOKUP portability, in\_query, single-use views in topics and much more!
* [July 26, 2024](/demos/2024/20240726): IDE redesigns, lots of filter work, and much more
* [July 19, 2024](/demos/2024/20240719): IDE error auto-fixing, refresh schema on schedule, KPI styling enhancements, improved SQL auto-complete and lots more
* [July 12, 2024](/demos/2024/20240712): Query API alpha, table enhancements, controls for controls and lots more!
* [July 8, 2024](/demos/2024/20240708): Content as code, Drill modals in workbook & dbt pushdown
* [June 28, 2024](/demos/2024/20240628): Alerts, Email Bursting (User Attributes in Schedules), AI Querying, & More
* [June 21, 2024](/demos/2024/20240621): Workbook UX (+ Tab Reordering), Vis Config Stickiness, Inline Images in Tables, & More
* [June 14, 2024](/demos/2024/20240614): AI Copilot + History, Environment Variables for dbt, Legend Controls & more
* [June 7, 2024](/demos/2024/20240607): Dynamic Tables - Links and Events, Default Row Level Access Controls, Snowflake Native App, & more
* [May 31, 2024](/demos/2024/20240531): Branch Mode + Git, Single-Tile Scheduling, Dynamic dbt Schema Improvements, & more
* [May 24, 2024](/demos/2024/20240524): Omni In-App Logging, Tab Rearranging and Styling, Single-Dashboard-Only User Permission, & more
* [May 17, 2024](/demos/2024/20240517): Filter by Query, Field Swappers on the Dashboard, New Permissions Reporting
* [May 10, 2024](/demos/2024/20240510): Table Styling, Excel Downloads With Formulas (Launched), Stickier Vis Config (Launched), & more
* [May 3, 2024](/demos/2024/20240503): XLOOKUP, Embedded Workbooks, Dynamic Fields / Select Fields From Filters, & more
* [April 26, 2024](/demos/2024/20240426): Compound Filters, Pull Requests + Model History Cleanup, Dynamic dbt Warehouses, & more
* [April 19, 2024](/demos/2024/20240419): Dynamic Fields (Parameters), Sudo / Permissions Testing (Launched), In-Database Aggregate Awareness, & More
* [April 12, 2024](/demos/2024/20240412): Incremental Model Promotion From the Workbook, Workbook Embedding, API + Schema Refresh Via API, & more
* [April 5, 2024](/demos/2024/20240405): Dynamic dbt Schema Swapping, 3-Argument SUMIF, Cell References in SUMIF AND COUNTIF, & more
* [March 29, 2024](/demos/2024/20240329): Text-to-Vis (Vega Lite GPT), Text-to-Query (GPT Workbooks), Admin User Impersonation (Sudo), & more
* [March 22, 2024](/demos/2024/20240322): Dashboard PDF & CSV Downloads, Embed Themes (Gradients and Custom Fonts), & more
* [March 15, 2024](/demos/2024/20240315): Looker migration, Tables (Row Height, Markdown), Conditional Formatting, & more
* [March 8, 2024](/demos/2024/20240308): ETL Freshness, Dynamic dbt schema switching, Period-Over-Period, & more
* [March 1, 2024](/demos/2024/20240301): SCIM user management, Design polish, Connection refresh error improvements (with dbt), Simpler permissions, & more
* [February 23, 2024](/demos/2024/20240223): Ridiculously fast embedded dashboards, Seamless dashboard refreshing, Bonus filter wiring & more
* [February 16, 2024](/demos/2024/20240216): Complete CSS control for embed dashboard styling, Git workflows in data modeling,Filtering iframes, & more
* [February 9, 2024](/demos/2024/20240209): Dashboard styling control designs, Content validator + Clickhouse, Spreadsheet calcs over pivots, & more
* [February 2, 2024](/demos/2024/20240202): Slack scheduling, usage analytics and more!
* [January 26, 2024](/demos/2024/20240126): Calculations date math & pivot progress, Filtered dashboard emailing, dbt, & more
* [January 19, 2024](/demos/2024/20240119): Field level permissions, Content validator, Access filters, Pivots & more
* [January 12, 2024](/demos/2024/20240112): Adding free text, Better filtering, New calcs, & more
* [January 5, 2024](/demos/2024/20240105): Calcs GPT, Caching controls, Content permissions, & more


# January 3, 2025
Source: https://docs.omni.co/demos/2025/20250103

Bunch of AI Improvements, More/Better Usage Data, Concurrency Improvements, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI conversation and AI query analysis

*Jamie Davidson · `Ai` `Workbook`*

Pair of new, early AI features: one for inviting new questions in a topic to get oriented on the data available; the second will summarize query results and point at follow-up analysis (we have some data processing pieces to solve there prior to release)

<Frame>
  <iframe />
</Frame>

## Better AI filters

*Gustav Staprans · `Ai` `Workbook`*

Some new tuning to AI query to improve filter construction using more structured LLM endpoints. Plus some improvements to make sure global AI query (outside of topics) is more scalable on larger models.

<Frame>
  <iframe />
</Frame>

## More usage analytics and new model analytics

*Arielle Strong · `Administration`*

We're exposing a bunch more topics for exploration of Omni usage data. Also an early look at model metadata - exposing field usage across the app, and workbook vs shared model for dashboards.

<Frame>
  <iframe />
</Frame>

## Load testing

*Nancy Chacko · `Administration`*

Some detail into recent load testing for high concurrency deployments, plus a bunch of the fixes we put in place to improve response time with high concurrency.

<Frame>
  <iframe />
</Frame>

## Branch menu organization

*Luke Bowerman · `Workbook` `Modeling`*

New folders for organization branches (just use "/"), plus alphabetical ordering.

<Frame>
  <iframe />
</Frame>

## Vis polish (pie and line weight)

*Rob Miller · `Visualization`*

Few small improvements to vis - bringing color controls to pie charts and some tuning for line weights in charts.

<Frame>
  <iframe />
</Frame>

## More time formats

*Sarah Waterson · `Visualization`*

Adding a new swath of internationally friendly time formats to vis.

<Frame>
  <iframe />
</Frame>

## Support admin UI

*Chris Merrick · `Administration`*

The launch of our admin tools for support location controls and full support lockout.

<Frame>
  <iframe />
</Frame>

## Topic-fields validation fix

*Conrad Slimmer · `Modeling`*

Putting the finishing touches on topic-scoped fields (ie fields that only live in single-topics). Now type inference will work as expected.

<Frame>
  <iframe />
</Frame>

## Multi-object user attributes in SQL

*Steven Talbot · `Modeling`*

We now support arrays in user attributes with multiple values in SQL calls using IN()

<Frame>
  <iframe />
</Frame>


# January 10, 2025
Source: https://docs.omni.co/demos/2025/20250110

Snowflake Cortex Columns, Sub-Folders (Early), Editing dbt Models, and Much More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Snowflake Cortex columns (AI columns)

*Colin Zima, Arielle Strong · `Modeling` `Workbook`*

We show how to take advantage of Snowflake Cortex to enrich data in Omni using modern LLMs. We show several examples of enriching marketing data, even layering interactive UI for selecting models or tuning prompts.

<Frame>
  <iframe />
</Frame>

## Sub-folders

*Luke Bowerman · `Content` `Workbook` `Dashboards` `Administration`*

An early look at nested folders.  Coming soon!

<Frame>
  <iframe />
</Frame>

## Editing dbt models

*Buck Ryan · `Dbt` `Workbook` `Modeling`*

Continuing to enrich our dbt workflows, now layering in direct model editing (via pull request) in the Omni UI. Also layering in file search for the dbt viewer.

<Frame>
  <iframe />
</Frame>

## Custom joins from the workbook

*Steven Talbot · `Modeling` `Workbook`*

New support for complex joins (inequality, multi-condition, etc) in the UI. Continuing to lift as much of the modeling experience as we can into the UI.

<Frame>
  <iframe />
</Frame>

## URL rebuild (don't move tiles on save)

*Luke Bowerman · `Workbook` `Dashboards`*

Putting the finishing touches on a URL rebuild for workbooks to stamp out the issue of dashboard tiles rearranging after workbook edits. This was a bigger lift than we expected, but excited to put it in the past.

<Frame>
  <iframe />
</Frame>

## Vertical reference lines

*Jamie Davidson · `Visualization`*

An early look at vertical reference lines on charts. Still work to do, but more actionable, clear charts coming soon.

<Frame>
  <iframe />
</Frame>

## Controls in scheduler

*Jamie Davidson · `Scheduler` `Dashboards`*

Now schedules can take advantage of dashboard controls for field swapping in delivered content.

<Frame>
  <iframe />
</Frame>

## Field color for measures in the model

*Rob Miller · `Modeling` `Visualization`*

Continuing the build out of color controls in the model - now supporting measures (especially useful with filtered measures)

<Frame>
  <iframe />
</Frame>

## Dashboard filter descriptions

*Jamie Davidson · `Dashboards` `Filtering`*

Filter settings on the dashboard now allow for tooltips to add more metadata to dashboard filters

<Frame>
  <iframe />
</Frame>

## Subtotals in pivots

*Steven Talbot · `Workbook`*

Bit of tuning to subtotals to allow subtotaling over pivots as well.

<Frame>
  <iframe />
</Frame>

## Model API

*Conrad Slimmer · `Api` `Modeling`*

Unveiling a new API for model building

<Frame>
  <iframe />
</Frame>

## More concurrency improvements

*Jonathan Swenson · `Performance` `Administration`*

Speed is a first class category of work for Omni. Continuing the focus on keeping the app speedy through high concurrency, and hammering out hotspots.

<Frame>
  <iframe />
</Frame>

## Trusted certificates for MSSQL

*Chris Merrick · `Administration`*

New toggle to trust certificates in MSSQL - supporting a default configuration for Microsoft customers

<Frame>
  <iframe />
</Frame>


# January 17, 2025
Source: https://docs.omni.co/demos/2025/20250117

Lots of API, Vis Series Coloring, AI Query Summary, Model Usage Analytics, and Lots of Polish and Pretty Vis

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## More API

*Corey Ruderman · `Api`*

Bunch of new APIs we're launching for content, plus some conversation about our prioritization for new APIs (TLDR; ask us if you need APIs).

<Frame>
  <iframe />
</Frame>

## Series coloring in UI

*Rob Miller · `Visualization`*

Lifting all of the color modeling work into the UI - now dimensional colors can be set explicitly in the UI (think completed = green, returned = red). Final step will be promotion to the model, for end-to-end color controls with all of the governance depth you could want for later.

<Frame>
  <iframe />
</Frame>

## AI query summarization visualization

*Jamie Davidson · `Visualization` `Ai`*

Early look at a new vis type that will summarize query results into a succinct text summary, with small hook for prompt tuning. This will launch with our new AI controls for data sharing.

<Frame>
  <iframe />
</Frame>

## Topic usage analytics

*Arielle Strong · `Administration` `Modeling`*

The first step towards getting the full picture of how all of the content in the systems (dashboards, workbooks, etc) is using topics, views, and fields in the data model. This will be the core building block for maintaining and improving the system as the database and data models evolve.

<Frame>
  <iframe />
</Frame>

## Ridiculously pretty KPI tiles

*Sarah Waterson · `Visualization` `Dashboards`*

Sarah shows off some beautiful new KPI tiles for displaying a series of metrics and orienting the current metric vis-a-vis a historical distribution. Gives a nice flavor for the possibilities with our KPI visualizations.

<Frame>
  <iframe />
</Frame>

## Templated custom vis

*Colin Zima · `Visualization`*

We rebuilt our custom visualization templates to more easily wire to diverse data tables (ie. only plug series in one place). This will underpin the work to then present front end controls on custom visualizations. (Plus a quick demo of our cross-filter vis)

<Frame>
  <iframe />
</Frame>

## Workbook grab bag

*Luke Bowerman · `Workbook` `Dashboards`*

A smorgasbord of odds and ends to make the experience better. Bit more work on nested folders and navigation, clearer filter icons in the workbook when views and groups are collapsed, new /analytics quick URL builder from any dashboard, and longer vanity URLs for dashboards to help a couple customers with longer dashboard names.

<Frame>
  <iframe />
</Frame>

## Spreadsheet styling

*Jared Hardy · `Visualization` `Spreadsheets`*

In anticipation of bringing some beta testers into the open spreadsheet experience, we're making sure styles feel aligned with the rest of the Omni app (colors, fonts, borders, etc).

<Frame>
  <iframe />
</Frame>

## More work on vis backend

*Nate Agrin · `Visualization`*

Some silent work in the background, but continuing to make it easier to build and support more visualization controls in the future

<Frame>
  <iframe />
</Frame>

## Better schema model handling with dynamic connections

*Conrad Slimmer · `Modeling` `Administration`*

Bit of refinement to the model and admin process with dynamic schemas.

<Frame>
  <iframe />
</Frame>

## Content validator faceting

*Steven Talbot · `Modeling` `Administration`*

New facet in the content validator to filter between public and private content.

<Frame>
  <iframe />
</Frame>


# January 24, 2025
Source: https://docs.omni.co/demos/2025/20250124

CSV Upload (Preview), AI Summary Tiles, Advanced Vis UI Builder, Embed URL Sharing, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## CSV upload preview

*Steven Talbot · `Workbook` `Modeling` `Dashboards`*

Bring any date you want into the workbook.  Now users can mash-up ad hoc data sets with the database - targets, custom enrichment, or even one-off data sets for dashboards. These new data sets operate like first class workbook queries - SQL access, Excel formulas, visualization, anything.  Rolling out over next few weeks.

<Frame>
  <iframe />
</Frame>

## AI summary tiles

*Gustav Staprans · `Dashboards` `Workbook`*

The launch of AI summary tiles to explain and analyze visualizations, including hooks for tuning prompts for specific use cases.

<Frame>
  <iframe />
</Frame>

## UI for advanced charts

*Jamie Davidson · `Visualization`*

Advanced Vega visualizations mean no cliff for building to completely custom use cases - now those visualizations can be wired to the UI for easy building and configuration (and later installation).

<Frame>
  <iframe />
</Frame>

## Embed URL sharing

*Nate Agrin · `Embed`*

A quick demo of how embed users can share dashboards + filters or explorations using new framework for URL sharing even in the iframe.

<Frame>
  <iframe />
</Frame>

## Omni for flat earthers

*Rob Miller · `Visualization` `Maps`*

Adding some new projections to our mapping tools for better full globe visualizations (or the non-believers)

<Frame>
  <iframe />
</Frame>

## Prettier table charts

*Sarah Waterson · `Visualization` `Tables`*

Always striving to get to 100% on polish in the visual experience. Bunch of polish on table charts to give flexibility on labeling and give designers the tools to make beautiful visualizations

<Frame>
  <iframe />
</Frame>

## Snowflake Cortex tools

*Peter Whitehead · `Dashboards` `Ai`*

More buildout of use cases with Snowflake Cortex - sentiment, summarization, and some more polished use cases with NBA data.

<Frame>
  <iframe />
</Frame>

## Dynamic image spreadsheet

*Jade Khiev · `Spreadsheets` `Workbook`*

A cute demo of a small spreadsheet template and the new functionality that opens up with a complete spreadsheet UX.

<Frame>
  <iframe />
</Frame>

## Fast user auth for embed

*Chris Merrick, Elliot Park · `Embed` `Administration` `Performance`*

We put a bunch of work into a new path for embed to massively speed up user authentication, even with lots of attributes, plus some conversation about the future.

<Frame>
  <iframe />
</Frame>

## Performance test suite

*Nancy Chacko · `Performance` `Administration`*

A new (internal for now) toolkit for performance testing with lots of metrics. Need great tools to make sure things stay fast end-to-end.

<Frame>
  <iframe />
</Frame>


# January 31, 2025
Source: https://docs.omni.co/demos/2025/20250131

Smart Labels, Editing Vis from the Dashboard, AI Chart Building, Cache Busting API, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Smart labels

*Nate Agrin · `Visualization`*

The thumbnail says it all - a new labeling algorithm that means no overlapping labels. Beautiful scatterplots, lines, bar charts right out of the box. Rolling out shortly.

<Frame>
  <iframe />
</Frame>

## Tiles don't move on edit

*Eli Cohen · `Dashboards`*

Probably our most persistent bug is now in the past. Lots of structural work to improve our URL structure and metadata storage to make sure tiles aren't moving or changing in unexpected ways.

<Frame>
  <iframe />
</Frame>

## Editing on dashboard - part one

*Gustav Staprans · `Dashboards`*

The first in a series of work to lift a bunch of the editing experience for visualization to the dashboard itself. Making sure builders have all the relevant tools in both the workbook and on the dashboard. Part one covers titles and descriptions, more to come.

<Frame>
  <iframe />
</Frame>

## AI chart builder

*Jamie Davidson · `Workbook` `Visualization`*

Some new work to build visualizations using natural language. These are all using the UI chart builder, so remain editable by end users. We hope to unify more of the AI interactions in the future, but continuing to press AI into all the different facets of the app.

<Frame>
  <iframe />
</Frame>

## Cache busting API

*Conrad Slimmer · `Administration` `Modeling`*

Now the cache is fully in your control - we have a new API to purge the cache. This means the cache can be tied to changes upstream - ETL cycles, dbt runs, or simply because you have new data.

<Frame>
  <iframe />
</Frame>

## Nested folders

*Meredith Dodge · `Content Management`*

More work on nested folders in the content management system, including some discussion of permission inheritance.

<Frame>
  <iframe />
</Frame>

## Dynamic embed sidebar

*Corey Ruderman · `Embed` `Api` `Administration`*

We show a nice workflow for deploying embedded dashboards - here we use the API to tie dashboards in a folder to the sidebar navigation in production.  This means deploying new dashboards to customers can be as easy as a prod folder in the Omni environment - easy build and deploy.

<Frame>
  <iframe />
</Frame>

## Transparent colors everywhere

*Sarah Waterson · `Visualization`*

Colors are great, but we're not stopping there - we've lifted transparency controls everywhere you find colors. Also available through 8-character hex codes. More tools, cleaner finished product.

<Frame>
  <iframe />
</Frame>

## Better embed auth

*Elliot Park · `Embed` `Administration`*

Continuing the work to speed up embed auth and make every embedded dashboard faster.

<Frame>
  <iframe />
</Frame>

## Drafts polish - read-only workbook and SQL saving

*Alisa Tatarinova · `Workbook`*

Pair of demos to smooth out the drafts experience - final touches on locked read-only field picker + now we'll make sure to save even un-run SQL on save.

<Frame>
  <iframe />
</Frame>

## Super clean gauge

*Sarah Waterson · `Visualization`*

A quick look at some new fancy gauge charts.

<Frame>
  <iframe />
</Frame>

## Themes with AI

*Arielle Strong · `Embed` `Dashboards`*

We show some workflows to build dashboard themes using AI. This means folks can feed in app styles to quickly build new embed themes in Omni.

<Frame>
  <iframe />
</Frame>


# February 6, 2025
Source: https://docs.omni.co/demos/2025/20250206

AI Filters, Dashboard Performance Reports, Clear Time Filters, Per-User Attributes Page, Our First Spreadsheet App, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI Filters

*Gustav Staprans, Steven Talbot · `Ai` `Filters`*

Filtering can be hard - not knowing which field to pick or how to express a complex time grain. Filter AI means filter is as easy as a text box. Work to do here still, but the potential is enormous for changing the way end users build and refine queries.

<Frame>
  <iframe />
</Frame>

## Commissions app

*Arielle Strong, Richard Czechowski, Kimberly DelSignore, Brian Frantz · `Spreadsheets` `Dashboards`*

This is the first app bringing together our new spreadsheet functionality alongside core BI use cases to build a real-time, permissioned commissions payment tool for sales ops. Now sellers can see all quoted sales alongside payment structure, with infinite flexibility to control payout structures or bonus via the breadth of a spreadsheet. No more importing and exporting and munging - now everything can be tied back to the sources of truth and update in real time.

<Frame>
  <iframe />
</Frame>

## Dashboard performance reports

*Nancy Chacko, Nate Agrin · `Administration` `Dashboards`*

Modern data teams operate like product teams, tools are delivered, but then need to be monitored and tuned, especially for performance. This is an early look at rich new tools for understanding performance (querying, data movement, rendering, etc) and finding hotspots to improve the end user experience.

<Frame>
  <iframe />
</Frame>

## Time filters that explain themselves

*Cathy Lennon, TJ Banghart · `Filters` `Workbook` `Dashboards`*

Time is hard. Everyone in BI has experienced it. Our new filter helper explains what time filters mean in plain language to make it easier.

<Frame>
  <iframe />
</Frame>

## User attributes page

*Chris Merrick, Rob Miller · `Administration`*

A new per-user page to easily expose all the user attributes for the given account. This makes cloning attributes simple and obviates understanding the full permission set for a given user (sorry IT issues mean no sound on this one).

<Frame>
  <iframe />
</Frame>

## Themes - now with chart palettes and dark mode control

*Luke Bowerman, Alisa Tatarinova*

We're still improving themes, now with control for dark/light mode explicitly, and themes that can be tied to visualization color palettes for complete cohesion and control of the visuals.

<Frame>
  <iframe />
</Frame>

## Docs AI

*James Ostergaard, Jiro Wiseman · `Docs` `Ai`*

We've taught Blobby how to work with docs. Now users can ask for help building queries or just generally using the application and Blobby can point to resources to get folks unblocked quickly.

<Frame>
  <iframe />
</Frame>

## Unlimited downloading

*Jonathan Swenson, Meredith Dodge · `Scheduling`*

More work on long-running queries to enable \~unlimited downloads via Omni.

<Frame>
  <iframe />
</Frame>

## New demos

*Elizabeth Schuler, Adrien Beaufils, Jess Gaines, Will Savage*

We show off a few of the new demo data sets and dashboards

<Frame>
  <iframe />
</Frame>

## AI on AWS Bedrock

*Chris Merrick · `Ai`*

We've begun porting some of the AI workflows to Bedrock in AWS (Claude for the curious). This means data never leaves the AWS envelope, reducing sub-processors and app surface area. This also means we can make the deeper AI functionalities available to anyone with more strict security postures (sorry IT issues mean no sound on this one).

<Frame>
  <iframe />
</Frame>

## Dash tiles swap to top or bottom

*Eli Cohen, Elliot Park*

New shortcuts for bulk dash layout changes - now tiles can zip to the top or bottom without the drag-rearrange challenges on longer dashboards.

<Frame>
  <iframe />
</Frame>

## Pretty markdown dash

*Sarah Waterson · `Dashboards` `Visualization`*

Sarah again shows off the possibilities for building pixel perfect, rich layouts in Omni using modern web techniques. Next step will be markdown templates to easily import these approaches.

<Frame>
  <iframe />
</Frame>

## New login page

*Jared Hardy · `Design`*

We prettied up the login page, making sure the app is staying as fresh as all the new code we're shipping.

<Frame>
  <iframe />
</Frame>

## Model import APIs

*Conrad Slimmer, Corey Ruderman · `Administration` `Modeling`*

New APIs for importing Omni models across environments or connections. Important tools for the most complex deployments.

<Frame>
  <iframe />
</Frame>

## Docs changelog in Omni

*Erin Cochran · `Docs`*

Some new tools (first internal, later external) to share out more detail on fresh code landing in product.

<Frame>
  <iframe />
</Frame>


# February 14, 2025
Source: https://docs.omni.co/demos/2025/20250214

CSV Upload Soft Launch, Instant Filters, More Color Work, Better Chart Labels, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## CSV upload soft launch

*Steven Talbot · `Workbook` `Dashboards`*

The soft launch (feature flag) of CSV upload, plus lots of conversation around lifecycle management. Note this will work in any supported dialects in Omni.

<Frame>
  <iframe />
</Frame>

## Fast filter via cache

*Steven Talbot · `Filtering` `Dashboards`*

Now filters can cache indefinitely (well 30 days), but enough that they should never load fresh on a dashboard unless that's explicitly desired.

<Frame>
  <iframe />
</Frame>

## Pie colors and else colors

*Rob Miller · `Visualizations`*

We extended modeled colors and front-end value controls to pie charts. We also brought the final modeled piece to the UI with else colors to highlight specific sections. The final touch will be promotion workflows.

<Frame>
  <iframe />
</Frame>

## Smart labels launch and force labels

*Nate Agrin · `Visualizations`*

Smart labels have launched, and we added a release valve to force labels as well, for complete control when it's desired alongside the collision-less experience.

<Frame>
  <iframe />
</Frame>

## Tabbed analytics and some perf

*Arielle Strong · `Analytics` `Administration`*

We've added to tabs to our Omni analytics dashboard for simpler navigation, better organization, and faster performance.

<Frame>
  <iframe />
</Frame>

## Dash perf tool

*Nate Agrin · `Dashboards` `Performance`*

Putting some of the final touches on the dashboard performance analysis tool - clarity on cache hits, data size, and load times across each tile of the dashboard. We want to give data teams a full product suite for managing performance.

<Frame>
  <iframe />
</Frame>

## Electron customer lookup app

*Arielle Strong · `Apps` `Embed`*

Quick demo of a desktop Omni app built for quick customer lookups. A great example of using embedded Omni + ChatGPT to build quick utilities. Hit us up if you want the code.

<Frame>
  <iframe />
</Frame>

## Compound XLOOKUP

*Cathy Lennon · `Spreadsheets` `Workbook`*

We've been doing some work to enable compound cross-tab references (ie XLOOKUP with concatenated keys). Just makes life a bit easier for the complex use cases.

<Frame>
  <iframe />
</Frame>

## Zapier to slides

*Anakarina McFadden · `Scheduler` `Export`*

Demo of a new workflow to connect Omni content into Google Slides seamlessly via Zapier

<Frame>
  <iframe />
</Frame>

## Drafts in branches

*Luke Bowerman · `Workbook`*

The final step in our drafts work - some in progress work on lifting drafts into branches so several folks can iterate on dashboards together, including model or dbt changes.

<Frame>
  <iframe />
</Frame>

## Workbook quick topics

*Luke Bowerman · `Workbook`*

An early demo of new work to make support an entirely model-less experience. We're building first class support for CSVs, tables, or even blank spreadsheets alongside the data model, pairing quick analysis to the deeper workflows and governance in the data model. More to come here.

<Frame>
  <iframe />
</Frame>


# February 21, 2025
Source: https://docs.omni.co/demos/2025/20250221

CSVs in the Data Warehouse (and Editable in a Spreadsheet!), Chart Color Promotion, and 13 More Demos

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## CSV upload into database (in any dialect)

*Steven Talbot · `Spreadsheets` `Workbook` `Csv`*

We brought CSV uploads from workbooks into the database. Now your workbook CSVs can live in the database alongside the rest of your data, in any dialect you are using (yes, all of them).

<Frame>
  <iframe />
</Frame>

## Spreadsheet input / editable CSVs

*Richard Czechowski · `Spreadsheet` `Csv`*

Now you can touch and feel your CSV uploads. We attached a full spreadsheet to the app for data input or tuning imported CSVs. Now data input is as easy as spreadsheeting.

<Frame>
  <iframe />
</Frame>

## Color promotion

*Rob Miller · `Visualization` `Workbook` `Modeling`*

The final step in our color work - now color mappings on specific visualizations can be pushed to an entire dashboard on the entire customer environment. Color controls up and down the app.

<Frame>
  <iframe />
</Frame>

## Content saving modal

*Meredith Dodge · `Content Management` `Workbook` `Dashboards`*

We polished up the content organization model with lots more metadata and navigation to make it easier to build and share dashboards and workbooks.

<Frame>
  <iframe />
</Frame>

## More beautiful markdown vis

*Sarah Waterson · `Visualization`*

Sarah shows off more of the potential with markdown visualizations.

<Frame>
  <iframe />
</Frame>

## Markdown tooling

*Richard Czechowski · `Visualization` `Workbook`*

We added some new functionality so that markdown builders can see the full Omni payload using , clarifying how to call anything in the result set.

<Frame>
  <iframe />
</Frame>

## Heatmaps

*Rob Miller · `Visualization`*

A bit of early work to open up heatmaps on our zoomable, pannable maps in Omni.

<Frame>
  <iframe />
</Frame>

## Bunch of design polish

*Jared Hardy · `Workbook` `Dashboards`*

Tons of improvements throughout the app - we removed the little blue spreadsheet box on tables unless you want it (great for screenshots), KPI alignment improvements, new controls for dashboard tile borders, and even a marketing website refresh.

<Frame>
  <iframe />
</Frame>

## Dashboard data summary

*Jamie Davidson · `Dashboards` `Ai`*

An early demo of our new dashboard summarization tools - now you can chat with AI about your dashboard and understand takeaways and next steps.

<Frame>
  <iframe />
</Frame>

## dbt IDE

*Buck Ryan · `dbt` `Modeling`*

We've done a ton of work to improve the dbt IDE - fast metadata refresh; easier navigation in dbt branches; and full menus for context and actions.

<Frame>
  <iframe />
</Frame>

## Dynamic slide builder

*Justin He · `Export` `Dashboards` `Workbook` `Apps`*

A new internal app for building slide decks using Salesforce data and a little bit of AI, piped to a clean Google slide deck.

<Frame>
  <iframe />
</Frame>

## Search on users page

*Rob Miller · `Administration`*

Making it that much faster to find the users you're looking for.

<Frame>
  <iframe />
</Frame>

## Support login controls

*Chris Merrick · `Administration`*

New controls to fine tune support access to customer environments.

<Frame>
  <iframe />
</Frame>

## Perf work

*Jonathan Swenson · `Performance`*

We're doing lots of work to make sure the app stays performant at extremely high concurrency.

<Frame>
  <iframe />
</Frame>

## Logs lookup tool

*James Ostergaard · `Apps` `Workbook` `Design Pattern`*

James shows off an internal app to quickly look up logs in AWS through intelligent deep links.

<Frame>
  <iframe />
</Frame>

## Snowflake Cortex plus upload dash

*Arielle Strong · `Design Pattern` `Apps`*

Arielle demos a dashboard bringing together lots of new product - an uploaded dataset of each Omnis walk-out song plus some Snowflake Cortex functions to tell folks about everyone's song choices.

<Frame>
  <iframe />
</Frame>


# February 28, 2025
Source: https://docs.omni.co/demos/2025/20250228

Lots of CSV Upload and Spreadsheets, Heatmaps, Color Promotion, and Lots More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Beautiful spreadsheet use cases

*Jade Khiev · `Spreadsheets` `Dashboards`*

Jade demos three use cases for the open spreadsheet UI. We're excited to see more of these use cases where folks had no other choice but to disconnect from the database. Now everything can wire up to live data and filters!

<Frame>
  <iframe />
</Frame>

## CSV upload to warehouse launch

*Steven Talbot · `Csv` `Spreadsheets` `Workbook`*

The launch of CSV pushdown to the warehouse. Works across every dialect Omni supports.

<Frame>
  <iframe />
</Frame>

## Input tables

*Richard Czechowski · `Spreadsheets` `Csv` `Workbook`*

The complement to CSV Uploads - now layering more data into an analysis is as easy as copy paste or a writing data to a spreadsheet. Lots of ongoing work here, but huge new use cases open up instantly.

<Frame>
  <iframe />
</Frame>

## More ways to start an analysis

*Luke Bowerman · `Workbook` `Csv` `Spreadsheets`*

We show off some in-progress work to streamline all the different approaches to analysis - curated datasets (topics), single-table, CSV input, blank spreadsheets, AI, or SQL. Every company has all of these use cases - let's make sure we can handle them in one place.

<Frame>
  <iframe />
</Frame>

## More vis editing on the dash

*Gustav Staprans · `Dashboards` `Visualization`*

We're still working on lifting the full visualization editing experience to the dashboard. No more bouncing back and forth to the workbook unless you want to.

<Frame>
  <iframe />
</Frame>

## Measure color promotion

*Rob Miller · `Visualization`*

The final step in our color work, now all of the promotion and workflow you have on dimensional coloring is available on measures as well. Easy to tune one-off, dashboard level, or across the entire Omni environment. Elegance in layers.

<Frame>
  <iframe />
</Frame>

## Heatmap launch

*Rob Miller · `Visualization` `Maps`*

Now you can complement region and point maps with our new heatmaps.

<Frame>
  <iframe />
</Frame>

## Time explainer for filters

*TJ Banghart · `Filtering` `Workbook` `Dashboards`*

We added a utility to understand how time filters compile, no more guesswork in the result set for inclusive/exclusive

<Frame>
  <iframe />
</Frame>

## Nested folder navigation improvements

*Jared Hardy, Meredith Dodge · `Content Management` `Dashboards`*

We tuned up the navigation experience to support deeply nested folders - just making it a bit easier to get to everything in a click or two.

<Frame>
  <iframe />
</Frame>

## Topic renaming

*Conrad Slimmer · `Modeling`*

Now topics are rename-able from the Omni IDE with relabeling or copy-paste.

<Frame>
  <iframe />
</Frame>

## Better content validator loading

*Steven Talbot · `Modeling`*

We improved the content validator load experience and made sure it doesn't time out even with the most complex models.

<Frame>
  <iframe />
</Frame>

## Wildcards in access filters

*Steven Talbot · `Modeling`*

Little fresh code to allow wildcard matching in access filters for more flexible data management.

<Frame>
  <iframe />
</Frame>

## Beta features visibility

*Arielle Strong · `Analytics` `Administration`*

We added a new tab to our analytics dashboard to understand all the fresh product you can opt in to (thanks to our new input tables). As always, let us know if anything looks interesting to try.

<Frame>
  <iframe />
</Frame>

## New website launch

*Jared Hardy · `Website`*

We dolled up the website and tried to make it a little easier to understand who we are and all the use cases we can support.

<Frame>
  <iframe />
</Frame>


# March 7, 2025
Source: https://docs.omni.co/demos/2025/20250307

Docs AI, Editing Visualizations Directly on the Dashboard, Unlimited Schedules and Downloads, dbt Environment Clean-up and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Docs AI

*James Ostergaard · `Ai` `Docs`*

The launch of docs helpers in our AI experience.  Now you can ask blobby about not just data questions or how to interpret the data, but also how to model, visualize, or configure Omni (with deeplinks too).

<Frame>
  <iframe />
</Frame>

## Edit vis from dashboards

*Rob Miller, Gustav Staprans · `Dashboards` `Visualization`*

We're getting close to full vis config controls directly from the dashboard. No more jumping back and forth to the workbook unless you really want to.

<Frame>
  <iframe />
</Frame>

## Unlimited scheduling and downloads

*Corey Ruderman · `Scheduling` `Export`*

Sometime folks need all the data and they need it in email. Sadly most mail providers don't allow that, but now you can schedule unlimited datasets with a call back to download data of any size via Omni.

<Frame>
  <iframe />
</Frame>

## dbt environment cleanup

*Buck Ryan · `Dbt`*

Some new tooling to make sure Omni metadata stays in sync with your dbt repo. More clarity for understand how Omni sees your dbt environments.

<Frame>
  <iframe />
</Frame>

## Super tabs for dashboards

*Cade Austin · `Dashboards`*

A new demo of richer interaction for a tabbed dashboard experience. This is still a custom markdown object, but we'll look to build into our native experience as well.

<Frame>
  <iframe />
</Frame>

## New workbook launch page

*Luke Bowerman, Alisa Tatarinova, Eli Cohen · `Workbook`*

We're making it simpler for users to orient in a blank workbook - clear pointers to curated data sets, but also offering more options around other tables in the warehouse or CSV when the use cases may be different.

<Frame>
  <iframe />
</Frame>

## Colors in table conditional formatting

*Alisa Tatarinova · `Table` `Visualization`*

All the beautiful work to improve color management and simplify interaction is now available for conditional formatting in the data table as well.

<Frame>
  <iframe />
</Frame>

## XMR charts

*Sarah Waterson · `Visualization` `Dashboards`*

A new example of XMR charts in Omni, popularized for process control use cases.

<Frame>
  <iframe />
</Frame>

## Bulk color modeling

*Conrad Slimmer · `Modeling`*

We've heard from customers that you love color modeling, but lots of data sets have columns that need duplicated metadata (say event schemas with a table per event type). Here we show off how to model color once but propagate the metadata to many fields - single place to maintain and push changes.

<Frame>
  <iframe />
</Frame>

## Content creation API v1

*Jamie Davidson · `Api`*

We show off a new API for moving content between environments that will also be a building block towards fully automated content creation.

<Frame>
  <iframe />
</Frame>

## Faster content validation

*Steven Talbot · `Modeling`*

We sped up content validation on large models - always striving to make cleanup easier.

<Frame>
  <iframe />
</Frame>


# March 14, 2025
Source: https://docs.omni.co/demos/2025/20250314

Guest Vis Demo, Editing Vis from the Dashboard, CSV Upload Edit Workflows, a Slack Emoji App, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Custom viz guest demo (ranking, boxplot, ribbon)

*`Visualization`*

A guest demo from our friends at Ramp networks demo three new custom visualizations, and have also shared out code for others. - More on [Github](https://github.com/klawecki/omni_viz_examples)

* More on [Medium](https://medium.com/@k.lawecki/custom-viz-examples-in-omni-e3d80cdaf8b0)

<Frame>
  <iframe />
</Frame>

## Edit vis from dashboard near launch

*Gustav Staprans, Rob Miller · `Dashboards` `Visualization`*

A doubleheader demo of the edit-vis-from-dashboard experience. Couple weeks out from launch, but can see almost all of the visualization controls live on the dashboard - KPIs, color controls (including promotion!), and of course vanilla vis config. Not sure on beta status here but can ping us for an earlier look maybe.

<Frame>
  <iframe />
</Frame>

## CSV upload UX + column types

*Richard Czechowski · `Csv` `Workbook`*

We demo the new spreadsheet-centric UX for CSV upload - trivial to edit and refine the upload, now including type controls to override our type guessing.

<Frame>
  <iframe />
</Frame>

## CSV upload security

*Steven Talbot · `Csv` `Workbook` `Sql` `Modeling`*

A quick demo explaining our CSV upload security model - where developers can move CSVs across workbooks, but they are default locked into the security of the given workbook.

<Frame>
  <iframe />
</Frame>

## Slack emoji reaction usage app

*James Ostergaard · `App`*

We love emojis at Omni (3000+ and counting). James built a quick new app for showing some rich stats on reactions in Slack (user, day, emoji). A ridiculous amount of fun for us, we're thinking about how to build a small tool for others too.

<Frame>
  <iframe />
</Frame>

## Dynamic connection environments improvements

*Conrad Slimmer · `Modeling` `Administration`*

Bunch of fresh code for some of our most complex environments, smoothing the experience for connection environments plus the interaction with git and user attributes. Making sure even the most complex setups can feel great.

<Frame>
  <iframe />
</Frame>

## Workbook launch page with AI

*Luke Bowerman · `Workbook`*

We're continuing to tune up the new workbook page to make all the different types of analysis fast and easy. Currently an internal beta, but rolling out soon.

<Frame>
  <iframe />
</Frame>

## Easier markdown field references

*Richard Czechowski · `Visualization`*

We made it a little simpler to find field references in markdown (format, drill, etc), so faster and easier custom tile building.

<Frame>
  <iframe />
</Frame>

## New performance monitoring (internal only)

*Nancy Chacko · `Performance`*

Bunch of new \[internal] tools for us to understand and improve performance at granular levels. We'll externalize some of these, but ultimately just want to make sure the app stays fast.

<Frame>
  <iframe />
</Frame>


# March 21, 2025
Source: https://docs.omni.co/demos/2025/20250321

New Filter Controls, Dataset Builders, Lots of Custom Vis, and Plenty More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Multi field picker and field on off toggle

*Arielle Strong, Jamie Davidson · `Dashboards` `Workbook`*

We added some new controls. Now series can be toggled on and off vs requiring a field swap. Additionally now tables can be built dynamically by selecting one or many columns.

<Frame>
  <iframe />
</Frame>

## Dataset builder UX for workbooks

*Alisa Tatarinova, Luke Bowerman · `Workbook`*

Continuing the work to improve two-step analytics workflows focused on create dataset then analyze dataset. The new dataset workflow will allow special workbook tabs that build datasets for use across the workbook and more focused controls for building data. More to do here, but great progress.

<Frame>
  <iframe />
</Frame>

## Row and multi column conditional formatting

*Jamie Davidson · `Tables` `Visualization`*

An early look at some richer controls for full row conditional formatting or basing conditional formats on an independent column.

<Frame>
  <iframe />
</Frame>

## Kanban vis

*Arielle Strong · `Visualization`*

Arielle shows off a new custom visualization for Kanban board data, with responsive columnized cards.

<Frame>
  <iframe />
</Frame>

## Zoomable chart UX

*Colin Zima · `Visualization`*

Another new custom vis for zoomable charts for more interactive vis experiences.

<Frame>
  <iframe />
</Frame>

## Metric tree vis

*Sarah Waterson · `Visualization`*

A new visualization framework for building metrics trees in Markdown. This is a bit custom, but a nice addition for some tactical use cases with metric trees.

<Frame>
  <iframe />
</Frame>

## Better labels with transposed table

*Nate Agrin · `Visualization`*

We polished up the labeling on transposed tables that get passed to our visualization layer.

<Frame>
  <iframe />
</Frame>

## Lazy load for faster render

*Nate Agrin · `Dashboards` `Performance`*

We'll now load tiles below the fold after the top of the dashboard, reducing browser load (especially valuable on mobile and less resourced machines). The net is faster dashboards for everyone.

<Frame>
  <iframe />
</Frame>

## Dashboard perf tool launch

*Nate Agrin · `Dashboards` `Performance`*

Our dashboard performance tuning tool is now generally available to everyone. Plus a bit of new UX around sorting for quicker tuning.

<Frame>
  <iframe />
</Frame>

## Table rename resolver

*Buck Ryan · `Modeling` `Administration` `Dbt`*

We built a new UX for remapping renamed tables and ensure all of the content and referencing works seamlessly in Omni. Want to build the best tools out there for managing a fluid data warehouse schema.

<Frame>
  <iframe />
</Frame>

## Content validator query deeplinks

*Mariel Freyre · `Dashboards` `Administration` `Modeling`*

Welcome to Mariel, shipping some code first week! We've added some deep links to the content validator, to jump right to the broken content for faster fixing.

<Frame>
  <iframe />
</Frame>

## Templated SQL improvements

*Steven Talbot · `Workbook` `Sql`*

Bit of tuning to the templated experience to make it work better with filter injection variables.

<Frame>
  <iframe />
</Frame>

## Improve cache hits for column ordering

*TJ Banghart · `Workbook` `Dashboards` `Performance`*

Little fresh code to make sure column reordering takes advantage of the browser cache and keeps a little load off the database.

<Frame>
  <iframe />
</Frame>

## Omni in Snowflake Marketplace

*Chris Merrick · `Snowflake`*

More a PSA than anything, but now Omni can be procured through the Snowflake marketplace.

<Frame>
  <iframe />
</Frame>


# March 28, 2025
Source: https://docs.omni.co/demos/2025/20250328

AI Progress Everywhere (Field Context, AI API, Training Docs), New DB Throttling Controls, Content in Branches, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Field AI context (with helpers to auto-build!)

*Jamie Davidson · `Ai` `Modeling`*

A huge step forward in enriching Omni models for AI. We now have field specific AI context, and helpers for value generation. The net is huge step forwards in AI quality across any use case. Additionally, we added workflow to add query examples to the model AI context for ground truth examples.

<Frame>
  <iframe />
</Frame>

## AI API demo (via Streamlit AI app)

*Arielle Strong · `Ai` `Apps` `Api`*

Arielle shows the potential of the AI API for building custom natural language apps. Shoot us a note if you want the app code.

<Frame>
  <iframe />
</Frame>

## Modeling for AI docs

*Jade Khiev · `Ai` `Docs` `Modeling`*

We bulked up our docs for training Blobby. Will continue adding here, but lots of lessons to share on improving the model to invite better quality for AI use cases.

<Frame>
  <iframe />
</Frame>

## Model AI context in KPI

*Nate Agrin · `Ai`*

We're now passing the model AI context to more places in the app, meaning vis-specific context can be more tactical.

<Frame>
  <iframe />
</Frame>

## Query throttling tools

*Jonathan Swenson · `Administration`*

A full UI for managing database load. We've layered in new tools for per-database and per-user throttling, making sure no one person can overwhelm the database.

<Frame>
  <iframe />
</Frame>

## Content editing branches

*Eli Cohen, Meredith Dodge · `Dashboards` `Modeling`*

Lots of work bringing the full content editing experience to branches - now content edits can be synced end to end with dbt changes and the data model for fully robust edits to your most important dashboards.

<Frame>
  <iframe />
</Frame>

## Schema refresh debugger

*Conrad Slimmer · `Administration` `Modeling`*

We added more metadata for schema refreshes to understand where time is spent or any associated errors.

<Frame>
  <iframe />
</Frame>

## dbt model metadata debugger improvements

*Buck Ryan · `dbt` `Modeling` `Administration`*

A follow up to our demo from last week. A bit more debug info on the dbt metadata Omni has access to.

<Frame>
  <iframe />
</Frame>

## Query performance logs

*`Administration` `Performance`*

We're piping detailed query performance data back the logs - now performance can be traced from dashboards to individual queries, with full timing metadata up and down.

<Frame>
  <iframe />
</Frame>

## Edit vis from dash beta

*Gustav Staprans · `Dashboards` `Visualization`*

We're opening the beta for editing visualizations directly from the dashboard as we put the finishing touches on the full experience. Now fast edits like KPI layouts, dashboard widths, or really anything vis related.

<Frame>
  <iframe />
</Frame>

## Date fill for compound filters

*Steven Talbot · `Workbook` `Visualization`*

We extended date fill to more complex filter options, including compound filters (ie relative to fixed date periods).

<Frame>
  <iframe />
</Frame>

## Card detail vis

*Arielle Strong · `Visualization`*

A beautiful new card visualization for displaying logos alongside a checklist UI.

<Frame>
  <iframe />
</Frame>

## Word clouds (ie. data concert posters)

*Sarah Waterson · `Visualization`*

A few new visualizations for presenting word cloud style data

<Frame>
  <iframe />
</Frame>

## Nulls handler for vis

*Nate Agrin · `Visualization`*

Some new affordance in the visualization for null data, giving more optionality into displaying sparse data.

<Frame>
  <iframe />
</Frame>


# April 4, 2025
Source: https://docs.omni.co/demos/2025/20250404

Filter on Calcs, AI Retry, AI Evals, Query View UX, Google Sheets Export, and Much More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Filter on calcs

*Cathy Lennon · `Calcs` `Visualization`*

You can now filter with calculations post-query! This opens up a huge number of new use cases, filtering rows for visualization (ie trimming off partial moving averages), removing some rows (say hiding rows based on an IF calc), or even just simpler tables with calcs over a larger data set.

<Frame>
  <iframe />
</Frame>

## AI on Bedrock and AI retry

*Steven Talbot · `Ai`*

We're moving blobby into AWS Bedrock (powered by Claude), to reduce the surface are of where customer metadata is used and simplify subprocessor requirements. We also added new functionality to continue retrying query construction following errors, improving recall.

<Frame>
  <iframe />
</Frame>

## AI eval tool

*Arielle Strong · `Ai`*

We added new functionality to the AI web app to side-by-side test different model contexts. This can be used to improve and adjust the data model to optimize query results for natural language use cases. Supports either ad hoc query or a golden test set.

<Frame>
  <iframe />
</Frame>

## Datasets and query views

*Luke Bowerman · `Workbook` `Sql`*

Continuing down the path of making view building in the workbook clearer and faster. Now query views (SQL or UI) get a dedicated build and edit experience.

<Frame>
  <iframe />
</Frame>

## Dash editing at size and dash mobile editor

*Sarah Waterson · `Dashboards`*

We improved the dashboard editing experience to exact match the size in production. This means all the visualization tuning will exact match the final product. Additionally, we added a UI toggle to optimize the independent mobile layout (ie won't affect the desktop layout).

<Frame>
  <iframe />
</Frame>

## Google Sheets export

*Russell Garner · `Export`*

We've heard lots of demand for data directly into Google Sheets without Zapier. Now using Google Cloud Run functions, we have secure data transfer into Sheets.

<Frame>
  <iframe />
</Frame>

## Conditional formatting relaunch

*Sarah Waterson, Jamie Davidson · `Visualization` `Tables`*

We're launching the new UX for conditional formatting with a first class UX on the table options, including full-row highlighting.

<Frame>
  <iframe />
</Frame>

## Dash performance data launch

*`Performance` `Administration`*

We're launching all the new performance data for query runtimes into production. Lots of granularity on query performance to action better experience for end users.

<Frame>
  <iframe />
</Frame>

## Embedded navigation control

*Elliot Park · `Embed`*

Several customers have requested the flexibility to build their own app nav. Now folks can DIY application navigation outside the dashboard iframe for even more custom experiences.

<Frame>
  <iframe />
</Frame>

## Always where filters plus better caching

*TJ Banghart · `Modeling` `Caching`*

We added always\_where\_filter (a forced, hidden topic filter) alongside sql\_always\_where. Also some additional work to improve cache hit rates.

<Frame>
  <iframe />
</Frame>

## More branched content work

*Meredith Dodge · `Dashboards` `Content Management`*

Continuing work on branches for content for the most mature content lifecycle out there.

<Frame>
  <iframe />
</Frame>

## Lots more API

*Corey Ruderman · `Api`*

Continuing to make the whole app API addressable - here with connection environment building (also landed but not demoed delete folder, import content, moving content, get queries from dashboard).

<Frame>
  <iframe />
</Frame>

## Model portability with Git (git follower)

*Conrad Slimmer · `Administration` `Modeling`*

With git follower mode, models can be deployed cross-environment for multi-instance deployment or dev-staging-prod workflows.

<Frame>
  <iframe />
</Frame>

## Multi instance model portability

*Chris Merrick · `Administration` `Modeling`*

A new admin console for moving data models between environments - best for multi-region deployments or dev-prod workflows.

<Frame>
  <iframe />
</Frame>

## Docs nav rework

*Erin Cochran · `Docs`*

We're doing some reorg on the docs to make it easier and faster to find what you need. Feedback appreciated on how we can organize for the best experience.

<Frame>
  <iframe />
</Frame>


# April 11, 2025
Source: https://docs.omni.co/demos/2025/20250411

Dynamic Model Layers, Embed Nav Builder, Better AI Retry, and More Analytics

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dynamic model layers

*Conrad Slimmer · `Modeling`*

We're adding more layers to the data model for the most complex use cases. Soon user-specific or group-specific models will be layered into the data model. This opens up utilities like localization, departmental models, per-user models, and all sorts of interesting extension points to the app. These will be able to be tied to user attributes for dynamic model layers as well.

<Frame>
  <iframe />
</Frame>

## Embed nav builder

*Nate Agrin · `Embed`*

The finishing touches on DIY embed navigation - enabling more control and curation over the embed UX. Additionally we've enable navigation without rebuilding the iframe for huge improvements in speed and quality of user experience.

<Frame>
  <iframe />
</Frame>

## AI retry and better AI filters

*Steven Talbot · `Ai` `Workbook`*

Continuing work to make sure AI always returns results for natural language queries. Plus lots of work to improve recall on time filters.

<Frame>
  <iframe />
</Frame>

## User attributes in AI context

*Richard Czechowski · `Workbook` `Ai`*

Now user attributes can be called when adding AI context, for more elegant use cases like data summary with better user context.

<Frame>
  <iframe />
</Frame>

## More analytics (permissions and query performance)

*Arielle Strong · `Analytics`*

We've tuned up the in app analytics experience with a simpler model for user permissions (think way easier to use) and lots of new data on cache hit rates and performance to tune and optimize dashboard loads.

<Frame>
  <iframe />
</Frame>

## Better code testing (internal)

*TJ Banghart · `Internal`*

We're improving our test coverage for data filters to make sure we can keep building quickly while minimizing negative customer impact or regressions.

<Frame>
  <iframe />
</Frame>


# April 18, 2025
Source: https://docs.omni.co/demos/2025/20250418

Lots of Mini Apps, Better IDE Search, Multi-tab Spreadsheets, Topic and View Visual Editor, More AI and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Multi-tab spreadsheets

*Richard Czechowski · `Spreadsheets` `Workbook`*

Now spreadsheets can call data from many tabs at once. This offers the flexibility to run a bunch of queries and then manipulate the results into any spreadsheet layout that makes sense. Little more polish, but will be in beta soon.

<Frame>
  <iframe />
</Frame>

## IDE search improvements

*Mariel Freyre · `Modeling`*

We're making it 10x faster to find what you are looking for in the data model. Faceting for fields, topics, views; better search; and a simple UX. Launching soon.

<Frame>
  <iframe />
</Frame>

## Multi model AI and calcs with AI

*Steven Talbot · `Ai` `Workbook`*

Our AI is getting smarter - now with options to push simple queries to small, fast models or more complex queries to reasoning models. We're also teaching Blobby to build calculations using the Excel syntax for even more complex query construction.

<Frame>
  <iframe />
</Frame>

## Topic and view editor

*Luke Bowerman · `Workbook`*

We're overhauling the front end experience for views and topics to make everything UI controllable, more clear, and faster to work with.    Here we show off the new experience landing soon.

<Frame>
  <iframe />
</Frame>

## Topic sample queries

*Luke Bowerman · `Workbook`*

It can sometimes be tricky to immediately understand the types of queries possible. Sample queries offer a way to curate out examples to enable better end user self-service.  Also a little bonus feature with line breaks in tab descriptions.

<Frame>
  <iframe />
</Frame>

## Calendar vis library

*Sarah Waterson · `Visualization`*

We added a bunch of options for calendar visualization to the library - including timeline style (a la Github) or classic calendar view.

<Frame>
  <iframe />
</Frame>

## Legend selection and deselection

*Nate Agrin · `Visualization`*

Now legend selection and de-selection is available for stacked bar chart, using both color faceting or multi-series stacking.

<Frame>
  <iframe />
</Frame>

## Omni model browser mini app

*Corey Ruderman, Arielle Strong · `Apps` `Api`*

Another mini app on top of the API - this time for visually browsing the table model (think ERD for joins, fields, etc).

<Frame>
  <iframe />
</Frame>

## Model migration mini app

*Liam McCarthy · `Api` `Apps`*

A quick mini app for migrating data models between Omni environments. Another example of simple workflow on top of the API - especially relevant for dev, staging, prod style deployments.

<Frame>
  <iframe />
</Frame>

## Model and content seeding mini app

*Jack Sweeney · `Apps` `Api`*

Another example of what's possible with the Omni API. Here we have a mini app for installing a database connection, data model, and dashboards in a few clicks.

<Frame>
  <iframe />
</Frame>

## Bulk user management mini app

*Russell Garner · `Apps` `Api`*

We show off another mini app for managing users and groups inside Omni. Another example of the possibilities using the API for bulk user tuning.

<Frame>
  <iframe />
</Frame>


# April 25, 2025
Source: https://docs.omni.co/demos/2025/20250425

AI Mode + More AI, dbt Description Push Down, IDE Search, Table Styling and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI Mode

*Gustav Staprans · `Ai` `Workbook`*

We've been working on a new UI to simplify the natural language experience. Query history, charting, and fast linking to the workbook.

<Frame>
  <iframe />
</Frame>

## Subtotals in AI and context responses

*Steven Talbot · `Ai` `Workbook`*

We're making Blobby smarter - now turn on subtotals or column totals via natural language. The AI can also now interpret past queries for better conversation.

<Frame>
  <iframe />
</Frame>

## dbt description push down

*Buck Ryan · `dbt` `Modeling`*

Now pushing down Omni descriptions to dbt is a couple clicks. The goal has always been putting data modeling logic where it makes sense. Now metadata from Omni can be lifted into dbt for use elsewhere.

<Frame>
  <iframe />
</Frame>

## IDE Search

*Mariel Freyre · `Modeling`*

More work on the IDE search to allow explicit view or field search - get you where you want quicker.

<Frame>
  <iframe />
</Frame>

## Table styling

*Jamie Davidson · `Workbook` `Dashboards`*

We added styling controls to tables - italic, bold, sizing across results, headers, and totals.

<Frame>
  <iframe />
</Frame>

## AI example (redacted internal data)

*Colin Zima · `Ai`*

Just a quick demo of how we are using AI internally. No results, but gives a nice flavor for what is achievable even on top of complex Salesforce data.

<Frame>
  <iframe />
</Frame>

## Omni CLI

*Nate Agrin · `Api`*

First look at the potential Omni command line interface for querying in the terminal.

<Frame>
  <iframe />
</Frame>

## Internal debug tool (better bug filing)

*James Ostergaard · `Internal`*

Demo of a new internal tool to file higher fidelity bugs and get problems solved quicker.

<Frame>
  <iframe />
</Frame>

## Security document structuring (via Snowflake)

*Chris Merrick · `App` `Analytics` `Internal`*

An great internal workflow for parsing documents in Snowflake and speeding up security contract review.

<Frame>
  <iframe />
</Frame>

## Dash controls tune up

*Sarah Waterson · `Dashboards`*

Little bit of polish and clean up on the control configurator for dashboards.

<Frame>
  <iframe />
</Frame>


# May 2, 2025
Source: https://docs.omni.co/demos/2025/20250502

More AI (Ai Mode Launch, New Slackbot), Custom Embed Nav, More API, and Handful of New Custom Vis

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI in Slack v0

*Peter Whitehead · `Slack` `Ai` `Api`*

Now that AI can do some incredible things, it makes sense to put Blobby in more places. Here's an early cut of the Slack experience.

<Frame>
  <iframe />
</Frame>

## AI mode launch plus training query builder

*Jamie Davidson · `Ai` `Workbook`*

Lots more work on AI - putting the finishing touches on launching AI mode to everyone (now with nice linking to workbook pages). Plus making it simple to train inside a topic with example queries and nice suggestions for descriptive text to improve recall.

<Frame>
  <iframe />
</Frame>

## Embed custom navigation launch

*Elliot Park · `Embed`*

Showing off how nice the embed navigation can experience for more custom use cases plus some discussion of custom filters outside the iframe.

<Frame>
  <iframe />
</Frame>

## User specific model layer (for localization)

*Conrad Slimmer · `Modeling` `Administration`*

More work on user-specific models, showing how this will work to localize data models. This will have many applications for more complex permissions and layering of models.

<Frame>
  <iframe />
</Frame>

## More APIs

*Corey Ruderman · `Api`*

We're still working on exposing as much of the internal API as possible. More demos of branch management and modeling.

<Frame>
  <iframe />
</Frame>

## Custom primary keys for nested data

*Conrad Slimmer · `Modeling`*

When unnesting data, you may need more complex tooling to ensure correct aggregation. This is that complex tooling.

<Frame>
  <iframe />
</Frame>

## Snowflake key pair auth

*Chris Merrick · `Administration`*

As Snowflake encourages movement to key-pair auth for db connections, we're making sure folks have the tools they need.

<Frame>
  <iframe />
</Frame>

## BYO vis mini app

*James Ostergaard · `Apps` `Visualization`*

Another great vibe code example of what you can build on top of the API. This allows for visualizing Omni data across 12 different visualization libraries.

<Frame>
  <iframe />
</Frame>

## Subtotal table vis

*Sarah Waterson · `Visualization` `Tables`*

A new cut on subtotal visualization for a bit more visual polish.

<Frame>
  <iframe />
</Frame>

## Spider / radar chart

*Colin Zima · `Visualization`*

Another custom vis for the library, the spider / radar chart.

<Frame>
  <iframe />
</Frame>

## Omnis vis

*Colin Zima · `Visualization`*

We made a fun visualization showing business growth alongside the team. A great example of the interactive vis you can build.[Details on building are available here](https://community.omni.co/t/fun-company-progress-chart-with-zooming-panning/321).

<Frame>
  <iframe />
</Frame>


# May 9, 2025
Source: https://docs.omni.co/demos/2025/20250509

Blobby Mobile, An AI Demo on Our Actual Data, Front End Topic Building, API Mini Apps, Scheduler APIs, and Much More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby mobile (plus web beautification)

*Jared Hardy · `Ai` `Mobile` `Workbook`*

We're bringing a first class AI experience to mobile. So many of the amazing AI use cases are tactical lookups or quick one-off questions. Now they have a first class experience for your phone.

<Frame>
  <iframe />
</Frame>

## Real fake AI demo

*Colin Zima · `Ai` `Use Case`*

We anonymized our Salesforce data so we could show you all how we actually use AI internally (spoiler - it's actually good). A great example of *actual* self service with all of the governance of an enterprise BI tool.

<Frame>
  <iframe />
</Frame>

## Front end topic builder

*Alisa Tatarinova · `Workbook`*

We're lifting more and more configuration into the front end. Soon you'll be able to build topics fully from the UI.

<Frame>
  <iframe />
</Frame>

## Front end query views (plus some topics)

*Luke Bowerman · `Workbook`*

Continuing work to manage query views from the UI, making it easier to manage and adjust.

<Frame>
  <iframe />
</Frame>

## Auto vis on-off

*Rob Miller · `Visualization`*

Now you can control whether we guess at new visualizations. Helpful when you want to tune queries and make sure visualizations remain static.

<Frame>
  <iframe />
</Frame>

## Multi measure chart labels

*Nate Agrin · `Visualization`*

More vis work to bring flexible labeling to multi-measure charts.

<Frame>
  <iframe />
</Frame>

## Future date filter UI

*Steven Talbot · `Workbook` `Filtering`*

It wasn't easy enough to filter over future dates like starting two quarters out for two quarters. Now it's a couple clicks.

<Frame>
  <iframe />
</Frame>

## XLOOKUP in AI query

*Steven Talbot · `Ai`*

Blobby is getting smarter. Now AI query can use XLOOKUP to merge queries together like time-series on independent dates.

<Frame>
  <iframe />
</Frame>

## Scheduler APIs

*Corey Ruderman · `Api`*

Now you can build schedules via API, great for bursting and embedded use cases.

<Frame>
  <iframe />
</Frame>

## API mini app

*Arielle Strong · `Api` `Mini App`*

Another preview of functionality we'd like to add to the core app. This is an API runner for all sorts of bulk application controls like user or content management.

<Frame>
  <iframe />
</Frame>

## Another API mini app

*Cade Austin · `Api` `Mini App`*

Another vibe coded app for taking advantage of the Omni API. Let us know if you'd like the code.

<Frame>
  <iframe />
</Frame>

## Figma API mini app

*Jared Hardy · `Api` `Mini App` `Design`*

More vibe coding, this time for getting Omni content and queries into the Figma UI for high-fidelity design work. So many options on top of the Omni API.

<Frame>
  <iframe />
</Frame>

## TypeScript SDK for API

*Nate Agrin · `Api` `Sdk` `Mini App`*

Another mini app example, this time a Typescript SDK on top of the Omni API.

<Frame>
  <iframe />
</Frame>

## Sentry debugger optional

*Nancy Chacko · `Support` `Performance` `Administration`*

We've added new user-controlled tooling to the app so that users can flip on robust logging to allow us to debug stickier application issues. Just more to keep the app running better for everyone.

<Frame>
  <iframe />
</Frame>

## dbt pushdown with sources

*Buck Ryan · `Dbt` `Modeling`*

We'll now use source to mix table references with jinja references when we push queries back into dbt models.

<Frame>
  <iframe />
</Frame>


# May 16, 2025
Source: https://docs.omni.co/demos/2025/20250516

Embedded AI, Tiny Grid Dashboard Launch, More AI (Chart Config, Field Descriptions), Or Access Grants, Complex Date Filters, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Embeddable AI

*Gustav Staprans, Arielle Strong · `Ai` `Embed` `Workbook`*

The full AI experience is now embeddable, including complete whitelabel options to style and name your AI. Everything Omni + AI + your app.

<Frame>
  <iframe />
</Frame>

## Tiny grid for dashboards (plus markdown tile copies retain style)

*Eli Cohen · `Dashboards`*

We shrank the dashboard grid, for finer grain layout control. Plus now when you copy dashboard text and markdown tiles they'll retain full style (shape, background, etc).

<Frame>
  <iframe />
</Frame>

## Charts in AI chat app

*Jamie Davidson · `Ai` `Visualization`*

We're continuing to build out the AI-only experience, layering in charting controls as you chat to query.

<Frame>
  <iframe />
</Frame>

## AI suggested labels and descriptions

*Jamie Davidson · `Ai` `Workbook` `Modeling`*

We've added some quicker helpers to instantly name and describe your fields in Omni - better metadata for AI to use plus ease of use for end users.

<Frame>
  <iframe />
</Frame>

## Live changelog in app

*Erin Cochran · `Docs`*

Our embedded analytics are getting better, this time with our internal changelog, so you can see everything we're shipping on your time.

<Frame>
  <iframe />
</Frame>

## OR in access grants

*Conrad Slimmer · `Modeling` `Permissions` `Administration`*

We're bulking up access grants for more complex use cases. Now you can structure more complex permissions logic using or between attributes for layered AND / OR grants.

<Frame>
  <iframe />
</Frame>

## Fixed to relative date filters (plus topical AI limits)

*Steven Talbot · `Workbook` `Filtering`*

Now you can mix and match between fixed (2025-01-01) and relative (3 days ago, 1 month from now) in the filter UX. All AI friendly as well, for any time filter you can imagine.

<Frame>
  <iframe />
</Frame>

## Better table drill UX

*Sarah Waterson · `Visualization` `Dashboards` `Workbook` `Tables`*

We took some time to polish the click and hover experience on tables to make drilling and linking simpler and prettier in Omni - plus some conversation on follow ups.

<Frame>
  <iframe />
</Frame>

## Better user management

*Trey Shugart · `Administration`*

We added search boxes and pagination all over the user management pages for faster admin nav.

<Frame>
  <iframe />
</Frame>

## Bonus video - teaching Blobby the best BI tool

*Steven Talbot · `Ai` `Fun`*

We put in some new bumpers to keep Blobby on topic, but made sure it knows the best BI tool on the market :)

<Frame>
  <iframe />
</Frame>


# May 23, 2025
Source: https://docs.omni.co/demos/2025/20250523

AI Field Creation, AI MCP v0, Streaming AI Results, Level of Detail Calculation, Lots of Dashboard Improvements, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Omni AI field creation

*Steven Talbot · `Ai` `Workbook` `Modeling`*

Blobby is getting smarter again. Now you can build fields directly from the AI query (of course inside the permission envelope of the core app). This means on-the-fly aggregates, derivative dimensions, etc are as easy as telling the AI what you want.

<Frame>
  <iframe />
</Frame>

## Omni MCP v0

*Arielle Strong · `Ai` `Api` `Mini App`*

We're bringing Blobby wherever you want to take him. Here's a quick demo of Omni in Goose ([https://github.com/block/goose](https://github.com/block/goose)) alongside generic AI functions. Now data is accessible from whatever chat services make sense in your org.

<Frame>
  <iframe />
</Frame>

## Level of detail fields

*TJ Banghart · `Modeling` `Workbook`*

We're beefing up the querying engine to open up level of detail calculations in Omni. Escape or force grouping independent of the rest of the query. Great for dynamic percent of totals, comparison to unfiltered data, or other complex calculations. Let us know what you want to see here.

<Frame>
  <iframe />
</Frame>

## Streaming AI queries

*Steven Talbot · `Ai` `Workbook`*

Now Blobby will tell you what it's doing while it does it, improving performance and the general experience.

<Frame>
  <iframe />
</Frame>

## Easier dash sizing controls

*Jared Hardy · `Dashboards`*

We tuned up the dashboard layout experience to make sizing tiles more delightful.

<Frame>
  <iframe />
</Frame>

## Force unfurl filter list on dashboards

*Luke Bowerman · `Dashboards`*

We added some new config to force exposing long filter lists beyond the default single line.

<Frame>
  <iframe />
</Frame>

## Aggregation in the vis

*Rob Miller · `Visualization` `Workbook`*

Sometimes data isn't quite at the right grain for a great visualization, so we added tooling to aggregate directly from the visualization.

<Frame>
  <iframe />
</Frame>

## Color mapping over huge lists

*Rob Miller · `Visualization` `Workbook`*

We've improved the front-end for the long tail of color mapping over huge lists.

<Frame>
  <iframe />
</Frame>

## Per user embed dashboard nav

*Jack Sweeney · `Embed` `Mini App` `Api`*

A nice mini app to show custom per-use navigation for an embedded experience.

<Frame>
  <iframe />
</Frame>

## Translate Omni model to Snowflake semantic model

*Jamie Davidson · `Api` `Modeling` `Mini App`*

Now all the data modeling you do in Omni can also be lifted to the new Snowflake Semantic layer for use in Cortex AI.

<Frame>
  <iframe />
</Frame>

## Faster user group management

*Trey Shugart · `Administration`*

We tuned up the group page to improve performing by 100x on long user lists.

<Frame>
  <iframe />
</Frame>


# May 30, 2025
Source: https://docs.omni.co/demos/2025/20250530

dbt Tests in AI Context, Blobby Chrome Extension, Workbook Quick Starts, Embed Folder Naming, Performance Work, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## dbt Tests in AI Context

*Buck Ryan · `dbt` `Modeling` `Ai`*

dbt tests can now populate AI field context (all\_fields), improving NLQ performance without touching Omni. This will stay in sync as your tests evolve as well.

<Frame>
  <iframe />
</Frame>

## Blobby in new browser tab

*Arielle Strong · `Ai` `Mini App`*

A quick chrome extension to launch new tabs into the chat experience. Making your whole database available in a click.

<Frame>
  <iframe />
</Frame>

## Workbook AI visualization

*Jamie Davidson · `Ai` `Workbook`*

We brought the /chat visualization experience to the workbook.    Now blobby can build (and soon tune) vis.

<Frame>
  <iframe />
</Frame>

## AI customization preview

*Sarah Waterson · `Ai`*

Last week we launched customization so you can make Blobby yours. Now you can see what that looks like inline.

<Frame>
  <iframe />
</Frame>

## Workbook quick starts

*Luke Bowerman · `Workbook`*

We added shortcuts to deep link to all of the different analytical approaches in the workbook (topics, all views and fields, CSV upload, SQL). Making it a little faster to get where you're going.

<Frame>
  <iframe />
</Frame>

## Embed group and folder name customization

*Elliot Park · `Embed` `Administration`*

Now embedded customers can customize folder names and group names beyond the default entity name.

<Frame>
  <iframe />
</Frame>

## More performance improvements

*Nancy Chacko · `Performance`*

A bunch of new work to improve general app performance, plus some conversation and how we discovered and monitor the outcome.

<Frame>
  <iframe />
</Frame>

## Logo scrollable chart example

*Colin Zima · `Visualization`*

We created an open version of the scrollable logo chart as a reference for folks building.

<Frame>
  <iframe />
</Frame>

## Billing and security contacts in app

*Chris Merrick · `Administration`*

Rather than having to ping us about billing contact or security contact updates, now they can be managed in app.

<Frame>
  <iframe />
</Frame>

## Internal docs Slackbot

*James Ostergaard · `Internal` `Docs`*

We have lots of great conversations on Slack supporting customers. Now we can draw on all that experience answering questions via a customer internal-facing Slackbot.

<Frame>
  <iframe />
</Frame>


# June 6, 2025
Source: https://docs.omni.co/demos/2025/20250606

Omni MCP 1.0, Spreadsheets Getting Closer to Release, New Model Debug Modes, Markdown Vis AI, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Omni MCP 1.0

*Gustav Staprans · `Ai`*

Our first version of Omni's MCP service in the wild via Claude desktop. Now you can bring governed data AI anywhere you want. Apologies for some hiccups with screen share early in the video, but some visuals at the end.

<Frame>
  <iframe />
</Frame>

## Multi tab spreadsheets

*Richard Czechowski · `Spreadsheets` `Dashboards`*

We're still working on getting full spreadsheet UI into public GA. The approach is shifting from single-tab visualization to being able to draw from multiple tabs, for any use case you can imagine. Soon.

<Frame>
  <iframe />
</Frame>

## Model debug mode

*Conrad Slimmer · `Modeling`*

A new model mode to expose every implicit argument on anything in the data model. This makes the entire model construction explicit for simpler debugging in complex situations.

<Frame>
  <iframe />
</Frame>

## Model schema viewer

*Conrad Slimmer · `Modeling`*

We wanted to make it simpler to understand the raw schema in isolation, so soon the schema model will be viewable independently.

<Frame>
  <iframe />
</Frame>

## Markdown AI vis generation

*Jamie Davidson · `Ai` `Visualization`*

An early look at building markdown visualizations with AI. Plenty more work to do, but plan to allow completely custom visualization via markdown through this approach.

<Frame>
  <iframe />
</Frame>

## Billing in app

*Chris Merrick · `Administration`*

We're adding contracts and invoicing into Omni for easier coordination and understanding of payment status.

<Frame>
  <iframe />
</Frame>

## Document search mini app (internal)

*Chris Merrick · `Mini App` `Internal`*

We demo an internal mini app for searching and parsing documents in Omni via Snowflake Cortex. This use case is for contract lookup, but could be extended to any document based analysis.  Let us know if you'd like to see the code here.

<Frame>
  <iframe />
</Frame>

## Release notes AI search (internal)

*Jiro Wiseman · `Mini App` `Internal`*

A for-now internal facing release notes app to understand all of the fresh code in Omni and get plain english understanding of who and what it impacts.

<Frame>
  <iframe />
</Frame>


# June 13, 2025
Source: https://docs.omni.co/demos/2025/20250613

Omni MCP Getting Close, AI Summary Vis, Trellis Charts, Faster Workbooks, Custom Blobby, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Omni MCP

*Gustav Staprans · `Ai`*

Another demo of Omni living in Claude desktop, including dashboard building, bringing web data, and other post processing on top of Omni data.

<Frame>
  <iframe />
</Frame>

## AI summary vis improvements + scheduling

*Steven Talbot · `Workbook` `Dashboards` `Ai`*

A bunch of improvements to AI summary visualizations, including now making them accessible in the scheduler for emailed PDFs and Slack.

<Frame>
  <iframe />
</Frame>

## Trellis charts

*Rob Miller · `Visualization`*

Now that our new vis pipeline is landing, we're accelerating new features. Probably our most popular feature request is now in the works to facet charts by another dimension.

<Frame>
  <iframe />
</Frame>

## Custom Blobby workflow

*Jade Khiev · `Ai` `Administration`*

A nice workflow for making Blobby your own, using our AI customization experience plus some LLM image gen.

<Frame>
  <iframe />
</Frame>

## Workbook first load perf improvements

*Meredith Dodge · `Workbook`*

A few pieces of work to improve workbook first loads, reducing time to interactivity for the largest data models.

<Frame>
  <iframe />
</Frame>

## Curating color palettes

*Rob Miller · `Visualization` `Administration`*

Now admins can tune the palettes available to end users can cull out the long tail if needed.

<Frame>
  <iframe />
</Frame>

## New vis pipeline update

*Nate Agrin · `Visualization`*

A deep dive into our new visualization pipeline, and the progress to deliver it across every type of vis in Omni - eventually opening up higher feature velocity, better performance, and a more stable customer experience.

<Frame>
  <iframe />
</Frame>

## Income statement in Omni

*Jake Cochrane · `Mini App` `Spreadsheets`*

Heavily redacted (sorry), but we wanted to show off a special internal use case taking advantage of the new full spreadsheet UI. This type of experience can only be unlocked with the mix of *full* spreadsheeting with all the other great analytics tools in Omni.

<Frame>
  <iframe />
</Frame>


# June 20, 2025
Source: https://docs.omni.co/demos/2025/20250620

EAV Modeling, AI with Subqueries, Paginated PDFs, Trellis Soon, MCP Soon, and Lots More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## EAV modeling

*Russell Garner · `Modeling` `Workbook`*

A deep dive into all the special work we put into EAV modeling. Between some API workflows for dynamic field creation and per-customer model extensions, Omni now has a best-in-class approach to one of the most complex database structures. And of course this now unlocks all of the AI workflows on-top of these complex structures too.

<Frame>
  <iframe />
</Frame>

## Blobby learns subqueries

*Steven Talbot · `Ai` `Workbook`*

Blobby has a new superpower. Now when folks want multi-stage queries Blobby can create filter-by-query UX on the fly (think 'show me spend growth of user spend for customers that made a first purchase in 2020').

<Frame>
  <iframe />
</Frame>

## Paginated PDFs

*Corey Ruderman · `Scheduler` `Pdf` `Dashboards`*

Lots of work to make sure scheduled dashboards look great. Now dashboards will intelligently chunk into paginated PDFs for the paper lovers out there.

<Frame>
  <iframe />
</Frame>

## Trellis almost launch

*Rob Miller · `Visualization` `Workbook` `Dashboards`*

We've got resizing working smoothly on trellis charts. Few more finishing touches and these should be in customer hands.

<Frame>
  <iframe />
</Frame>

## Content validator smarter in branches

*Mariel Freyre · `Modeling` `Administration` `Dashboards`*

The content validator is getting smarter. Now we'll clearly differentiate branch-specific drafts for better triage of model impact.

<Frame>
  <iframe />
</Frame>

## MCP server in app

*Gustav Staprans · `Ai` `Mcp` `Administration`*

We're working on lifting the Omni MCP server into the Omni deployment. This and auth are the final steps to getting Omni MCP in customers' hands.

<Frame>
  <iframe />
</Frame>

## Connection AI context

*Jamie Davidson · `Ai` `Modeling`*

AI context everywhere. This time you can add connection/model ai\_context for routing Blobby inside multi-connection deployments.

<Frame>
  <iframe />
</Frame>

## Groups from the data table

*Jamie Davidson · `Workbook`*

A quicker way to group fields in the data table directly from the context menu.

<Frame>
  <iframe />
</Frame>

## Content permissions history

*Trey Shugart · `Administration` `Dashboards`*

We're now logging all of the permissions changes at the content level. Will add to the analytics available to admins soon.

<Frame>
  <iframe />
</Frame>

## Faster dashboards via context menu improvement

*Trey Shugart · `Dashboards`*

We sped up dashboards by optimizing the content menu a bit. Will be especially efficacious on the largest dashboards.

<Frame>
  <iframe />
</Frame>

## Demo videos analytics

*Chris Merrick · `Internal` `Use Case`*

In our most meta demo of all time, we start taking a look at our demo video data. Will get this loaded into analytics for folks who want to more easily browser the archives with some structure.

<Frame>
  <iframe />
</Frame>


# June 27, 2025
Source: https://docs.omni.co/demos/2025/20250627

Automated Data Modeling from AI Sessions, Instant Dashboard Filters, Unlimited Paginated Data Tables, Unfurled Tables in Schedules, and 15 More!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Automated modeling from AI sessions

*Steven Talbot · `Ai` `Modeling`*

A first look at adding new model context based on an AI session. This means when you need to introduce new fields or context in a given AI session, Omni can suggest changes to make Blobby smarter for future users and use cases.

<Frame>
  <iframe />
</Frame>

## In memory cubes (behind flag)

*TJ Banghart · `Modeling` `Workbook` `Dashboards`*

Sometimes you want the filter experience to be faster than the back and forth to the warehouse. Now you can create extracts do slice and dice instantly. Lots of work to come here to tune the experience - feature flagged right now.

<Frame>
  <iframe />
</Frame>

## No row limit tables (table pagination)

*Steven Talbot · `Workbook` `Dashboards`*

In rare cases, folks want to scroll through more than 50k rows in the browser. Now these massive lists can be paginated, including pivots and row totals.

<Frame>
  <iframe />
</Frame>

## Paginated PDF long table unfurl

*Corey Ruderman · `Dashboards` `Scheduler`*

Sometime you need hundreds of tabular rows in your scheduled reports. Now Omni will unfurl long tables in the renderer, allowing users to export hundreds or thousands of rows into documents.  Note this will not shrink to fit for wide tables, anything to handle tables wide than the maximum would be follow on work.

<Frame>
  <iframe />
</Frame>

## Custom stack sort

*Nate Agrin · `Workbook` `Dashboards` `Visualization`*

Now stack order can be set independently from the table, for use cases like stacking based on size on a segment-by-segment basis.

<Frame>
  <iframe />
</Frame>

## Visual field curation in topics

*Alisa Tatarinova · `Modeling` `Workbook`*

Now builders can visually curate the fields available via the front end. Simple workflows for controlling the exact experience for end users.

<Frame>
  <iframe />
</Frame>

## Inline vis summary

*Jamie Davidson · `Ai` `Visualization`*

Early look at a new layer to add a quick summarization for visualizations alongside the vis itself.

<Frame>
  <iframe />
</Frame>

## MCP launch feature flagged

*Gustav Staprans · `Ai` `Mcp`*

Blobby can now move between topics, and the MCP service is available behind a feature flag.

<Frame>
  <iframe />
</Frame>

## MCP dashboard migration

*Gustav Staprans · `Ai` `Mcp` `Dashboards`*

A quick demo of migrating a legacy dashboard via MCP - simply paste in a picture of a dashboard and Omni + Claude (via MCP) builds a replica on top of the Omni data model, styled to match the existing dashboard. Plan to bring this to the native product over time as well.

<Frame>
  <iframe />
</Frame>

## Better group management

*Meredith Dodge · `Adminstration`*

We improved the workflow for building groups in Omni to make sure it's more ergonomic to build long lists in our modals.

<Frame>
  <iframe />
</Frame>

## More better content validation in branches

*Mariel Freyre · `Modeling` `Administration`*

More work to streamline content and model edits in branches for non-downtime dashboarding as models evolve.

<Frame>
  <iframe />
</Frame>

## Sales forecasting in Omni

*Kimberly DelSignore · `Spreadsheets` `Mini App` `Internal`*

Another heavily redacted (sorry) use case of Omni internally using the new spreadsheets. This is a sales ops use case where we're lifting our sales forecasting process from Google Sheets into Omni alongside our live data. Reach out if you need more detail on this one.

<Frame>
  <iframe />
</Frame>

## MCP server example analysis

*Jack Sweeney · `Mcp` `Use Case` `Demo`*

A quick example of doing data analysis via the Omni MCP server. Some nice back and forth between the warehouse and analytical interpretation.

<Frame>
  <iframe />
</Frame>

## Multi measure small multiples

*Nate Agrin · `Visualization`*

Now faceted charts / trellis / small multiples allow for stacked and multi-measure charts.

<Frame>
  <iframe />
</Frame>

## Microsoft Entra auth

*Chris Merrick · `Administration`*

There's a new option for automated authentication in Omni.

<Frame>
  <iframe />
</Frame>

## Paginated dashboard in the hub

*Meredith Dodge · `Content Management`*

We tuned up navigation for dashboards and layering in pagination for long lists.

<Frame>
  <iframe />
</Frame>

## AI query then summarize

*Steven Talbot · `Ai`*

Now Blobby is smart enough to run queries prior to summarization for questions where Blobby doesn't already have the answer.

<Frame>
  <iframe />
</Frame>

## Table model migrator improvements

*Steven Talbot · `Modeling`*

We improvement the table migrator in the model to allow for no-downtime migration of logic for name-changed or deleted views.

<Frame>
  <iframe />
</Frame>

## ignore\_from\_extended

*Steven Talbot · `Modeling`*

A new argument for tuning the ignore behavior with extensions and templated models.

<Frame>
  <iframe />
</Frame>


# July 3, 2025
Source: https://docs.omni.co/demos/2025/20250703

Fill Gaps in Any Date Series, More AI Auto-Modeling, More Model Permissions, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Fill gaps in any date series

*Cathy Lennon · `Workbook`*

Now any time-series can dynamically fill missing dates between the min and max in the data set.

<Frame>
  <iframe />
</Frame>

## More automated modeling from AI

*Steven Talbot · `Modeling` `Ai`*

Our auto-modeler from AI sessions is getting smarter. UI has been tuned up and precision also much better.

<Frame>
  <iframe />
</Frame>

## Automated topic descriptions from usage

*Jamie Davidson · `Ai` `Modeling`*

More AI context from using Omni. This time, we're opening up topic descriptions to guide use cases on different data sets based on real usage.

<Frame>
  <iframe />
</Frame>

## Topic restriction for AI query

*Steven Talbot · `Ai` `Modeling`*

We added a new model argument for curating the data sets allowed for AI query.

<Frame>
  <iframe />
</Frame>

## Internal AI query discussion (how to AI model)

*Colin Zima · `Ai` `Use Case` `Internal`*

Some discussion about how we've implemented AI context for internal usage and tuning process.

<Frame>
  <iframe />
</Frame>

## Model level permissions

*Conrad Slimmer · `Administration` `Permissions`*

Adding a new permissions layer to control model extensions, allowing more complex use cases with team or group models.

<Frame>
  <iframe />
</Frame>

## Bunch of dbt improvements

*Buck Ryan · `Dbt` `Administration`*

Bunch of improvements to the dbt experience - better metadata syncing / dbt health and more flexible SSH key management.

<Frame>
  <iframe />
</Frame>

## Streaming pivot export

*Jonathan Swenson · `Export` `Downloads`*

We made it so pivots now also stream for exports, meaning no limit even for pivoted queries for downloads.

<Frame>
  <iframe />
</Frame>

## Chart type swapper pattern

*Colin Zima · `Use Case` `Modeling Pattern` `Workbook` `Dashboards` `Visualization`*

A quick modeling pattern for dynamically swapping the chart type with a filter.

<Frame>
  <iframe />
</Frame>

## LookML to Omni converter API app

*Justin He · `Mini App` `Modeling`*

Another vibe coded app on top of the Omni API - this one for converting LookML to Omni's data model.

<Frame>
  <iframe />
</Frame>

## Better invite flow

*Sarah Waterson · `Administration`*

Little bit of tuning the invite flow to allow better bulk user invitations.

<Frame>
  <iframe />
</Frame>


# July 11, 2025
Source: https://docs.omni.co/demos/2025/20250711

DB OAuth Passthrough (soon), Lots of Spreadsheets, Unlimited Excel Downloads, More Better Vis, Embed Error Eventing, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## DB OAuth passthrough (soon)

*Steven Talbot · `Administration`*

Getting close to the launch of OAuth passthrough from the database in Omni. This would allow Omni to absorb any per-user permissioning from the database.

<Frame>
  <iframe />
</Frame>

## Multi-tab spreadsheet import / export

*Richard Czechowski · `Spreadsheets` `Workbook`*

Now you can bring your spreadsheets to Omni. We're not talking CSVs, we're talking real spreadsheets, formulas and all. We'll even intelligently map to live workbook tabs for easy import/export workflows with live data.

<Frame>
  <iframe />
</Frame>

## Unlimited 1M Excel downloads

*Jonathan Swenson · `Export` `Spreadsheets` `Workbook`*

We removed the row limit on Excel downloads - formulas, formats, and all. Now the Excel 1M row limit is your only constraint.

<Frame>
  <iframe />
</Frame>

## Tabbed spreadsheets on dashboards

*Richard Czechowski · `Spreadsheets` `Workbook` `Dashboards`*

Sometimes you actually just want a full spreadsheet on your dashboard tabs and all. Now you can.

<Frame>
  <iframe />
</Frame>

## Spreadsheet beta vis converter

*Richard Czechowski · `Spreadsheets` `Workbook`*

For folks in the spreadsheet beta, we've built a converter from the single-tab experience into our new multi-tab spreadsheets.

<Frame>
  <iframe />
</Frame>

## Dashboard error event framework

*Nate Agrin · `Embed` `Dashboards` `Administration`*

When Omni is the core product, like in many embedded use cases, developers need clear tooling to understand and address errors in queries proactively. We've built a new framework to alert on any problems with queries in deployed apps.

<Frame>
  <iframe />
</Frame>

## dbt environment improvements

*Buck Ryan · `Dbt` `Administration`*

We overhauled the dbt configuration workflow enabling more flexibility and clearer mapping to all the complexity you may have in your dbt setup.

<Frame>
  <iframe />
</Frame>

## Buncha trellis improvements

*Rob Miller · `Visualization` `Workbook` `Dashboards`*

Final touches on trellis charts - label controls, independent axes, and some tuned up config.

<Frame>
  <iframe />
</Frame>

## Advanced mode for heatmaps and boxplots

*Nate Agrin · `Visualization` `Workbook`*

Now heatmaps and boxplots are unlockable in Vega Lite for any long tail customization.

<Frame>
  <iframe />
</Frame>

## Single flat map

*Rob Miller · `Visualization`*

Quickie, but added a control to turn on and off infinite map scroll on flat maps can have infinite scroll or a single-globe flat view.

<Frame>
  <iframe />
</Frame>

## Pie label tuneup

*Nate Agrin · `Visualization`*

Few improvements to the pie label experience.

<Frame>
  <iframe />
</Frame>

## Ampersand KPI fix

*Richard Czechowski · `Visualization`*

Turns out using HTML in our KPI tiles isn't friendly with every character. Now ampersands and other HTML work the way they should in text boxes.

<Frame>
  <iframe />
</Frame>

## Buncha AI chat improvements

*Gustav Staprans · `Ai` `Workbook`*

Another big batch of improvements for the AI chat experience. Now you can ask Blobby about all the data available for AI query and get an overview of one or all of the topics. Second, we enabled Blobby to jump dynamically between topics in a session, no more topic selecting required. Finally, we improved the drill down experience for faster follow up in the workbook.

<Frame>
  <iframe />
</Frame>

## Better Omni MCP query calls

*Gustav Staprans · `Ai` `Mcp`*

Little bit of tune up to our MCP to better structure query calls.

<Frame>
  <iframe />
</Frame>

## AI how-to docs and add chart from dash

*Arielle Strong · `Ai` `Dashboards`*

A tune up to the experience adding new charts to a dashboard. We also added a no-nonsense doc on how to make AI queries work great: [https://community.omni.co/t/improving-ai-answer-quality-a-practical-guide/356](https://community.omni.co/t/improving-ai-answer-quality-a-practical-guide/356)

<Frame>
  <iframe />
</Frame>


# July 18, 2025
Source: https://docs.omni.co/demos/2025/20250718

Agent Blobby, Dashboard AI, Embedded AI Guest Demo, Topic Builder UI, Global Cache Busting Button, Plus Lots of Vis

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Multi query Blobby (AI agent v0)

*Steven Talbot · `Ai`*

Agent Blobby is coming. We're taking the training wheels off AI and allowing multi-query sessions when appropriate. This opens up chain of thought and requery analysis. Plenty more to do here, but more open experiences are coming.

<Frame>
  <iframe />
</Frame>

## Dashboard AI

*Gustav Staprans · `Ai` `Dashboards`*

Blobby is coming to the dashboard. We're working on passing dashboard context to the AI experience for more tactical use cases, or just to do analysis in line with the dashboard. Some commentary on future improvements as well.

<Frame>
  <iframe />
</Frame>

## Hawkfry guest demo - embedded AI app

*`Guest Demo` `Embed` `Dashboards` `Ai`*

Excited to share a guest demo from Jamie Fry at Hawkfry. We take a look at a complete embedded AI-for-data experience - including some classic BI and lots of AI interpretation and query.

<Frame>
  <iframe />
</Frame>

## Topic builder UI

*Alisa Tatarinova · `Workbook` `Modeling`*

The UI builder for topics has significantly more surface area now - field controls, modeling, and curation all from the front-end. IDE still there when you need it, but making sure we lift the entire experience to the UI as well.

<Frame>
  <iframe />
</Frame>

## Bunch of vis improvements

*Nate Agrin · `Visualization`*

A big grab bag of vis improvements: 1) Work on multi-measure charts in the new vis framework to extend the controls 2) Independent axis stack controls 3) Improved markdown vis references for dates 4) Better empty tooltip hover experience

<Frame>
  <iframe />
</Frame>

## New dashboard designer (early look)

*Luke Bowerman · `Dashboards`*

We're starting our work on making dashboards orders of magnitude more flexible. Here's a first look at some layout controls and the code behind it. More down the path of applicationizing the dashboard experience.

<Frame>
  <iframe />
</Frame>

## Trellis chart improvements

*Rob Miller · `Visualization`*

Bunch of improvements to the trellis experiences in GA.

<Frame>
  <iframe />
</Frame>

## Map size and color

*Rob Miller · `Visualization` `Maps`*

Little tune up to the map experience adding color picker and some sizing controls.

<Frame>
  <iframe />
</Frame>

## Cache busting button

*Conrad Slimmer · `Modeling` `Administration` `Dashboards` `Workbook`*

Sometimes you just want to purge the cache globally - soon you can directly from the IDE menu.

<Frame>
  <iframe />
</Frame>

## Content validator UX improvements

*Mariel Freyre · `Modeling`*

More improvements for content validator to allow for direct field search and picking.

<Frame>
  <iframe />
</Frame>

## Model field sets

*Jamie Davidson · `Modeling`*

Field sets in the model offer a new way to curate the experience for drill down and field management inside topics.

<Frame>
  <iframe />
</Frame>

## Faster app build (internal only)

*Kalen Petersen · `Internal` `Eng Productivity`*

Quick demo of some work to improve internal tools to make our engineering team more productive.

<Frame>
  <iframe />
</Frame>


# July 25, 2025
Source: https://docs.omni.co/demos/2025/20250725

A big pile of your most requested features this week!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Native Google Sheets export

*Corey Ruderman · `Export` `Google Sheets`*

Your most requested feature is near. We're building native connection to Google Sheets, including per user auth and fine grain controls for overwrite vs addition. Week or two out!

<Frame>
  <iframe />
</Frame>

## Legend click for series inclusion / exclusion

*Rob Miller · `Visualization`*

Our second most requested feature is close. We're now allowing the exclusion or isolation of series via legend clicks - drill in place directly from the visualization.

<Frame>
  <iframe />
</Frame>

## Dashboard containers and tabs (early preview)

*Luke Bowerman · `Dashboards`*

Slowly getting closer to nesting filters in dashboard sections (think tabs and tiles). Plus getting closer on native dashboard tabs.

<Frame>
  <iframe />
</Frame>

## Omni query metadata in the DB logs

*Kalen Petersen · `Administration` `Performance`*

Another hugely requested feature to pass Omni metadata into the database logs for simpler usage debugging and cost attribution. All available via our logs, but now in the DB query logs as well.

<Frame>
  <iframe />
</Frame>

## Snowflake semantic view builder mini app

*Peter Whitehead · `Mini App` `Modeling` `Snowflake`*

Peter demos our mini app for building Snowflake Semantic Views from your Omni data model. Want to make sure you can bring your business logic wherever it needs to go.

<Frame>
  <iframe />
</Frame>

## Longer caching plus extracts (!)

*TJ Banghart · `Dashboards` `Workbook` `Modeling`*

The cache now has a max age of 30 days. Normally this may not make sense, but if you watch this video you'll see the instant-query experience after enabling extracts over a SQL query. Think write one \[often slow] query, cache, and requery pseudo-instantly.

<Frame>
  <iframe />
</Frame>

## New dash builder UX

*Trey Shugart · `Dashboards`*

More work on opening up native dashboard tabs. We're streamlining the dashboard build to get it ready for multiple-tabs.

<Frame>
  <iframe />
</Frame>

## Dynamic email body text

*Corey Ruderman · `Export` `Scheduling`*

We added mustache controls to the email body, allowing dynamic text based on query results for the most polished emails.

<Frame>
  <iframe />
</Frame>

## Bust cache in drill modal

*TJ Banghart · `Dashboards` `Workbook`*

Now fresh results are a click away in the drill modal.

<Frame>
  <iframe />
</Frame>

## Level of detail with dimensionalize

*TJ Banghart · `Modeling` `Workbook`*

We're still beefing up level of detail calculations for window function analyses using dimensionalization alongside LoD (think compare to min/max/average among other use cases).

<Frame>
  <iframe />
</Frame>

## Fancy cohort tables

*Sarah Waterson · `Visualization`*

Another new markdown visualization for building beautiful cohort tables (think retention rates + cohort sizes).

<Frame>
  <iframe />
</Frame>

## Multi measure vis work

*Nate Agrin · `Visualization`*

Nate continues to toil deep in the Vega mines to bring multi-measure charts to parity with color faceted charts. Soon series will configure independently more easily with all the functionality you expect.

<Frame>
  <iframe />
</Frame>

## Period over period KPI improvements

*Steven Talbot · `Workbook` `Visualization`*

We made sure period-over-periods in KPIs function a bit better with comparison period swapping.

<Frame>
  <iframe />
</Frame>

## Session handling improvements

*Chris Merrick · `Administration`*

This should be mostly silent for end users, but begins the underpinnings that all for IDP initiated log-in for folks using SAML.

<Frame>
  <iframe />
</Frame>

## Better integration test framework (internal)

*Nancy Chacko · `Internal`*

We walk through some new internal tooling to handle cross-browser integration testing.

<Frame>
  <iframe />
</Frame>

## Omni developer training program

*Becca Bruggman · `Training` `Internal`*

We walk through some new docs for developer training.

<Frame>
  <iframe />
</Frame>


# August 1, 2025
Source: https://docs.omni.co/demos/2025/20250801

dbt Exposures, New Embed Demo, Guest Learning Microsite, Dashboard Summarization, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## dbt exposures

*Buck Ryan · `dbt` `Modeling`*

We're bring more Omni metadata back to dbt with exposures. Soon you will be able to understand all of the downstream impacts of your dbt changing in Omni.

<Frame>
  <iframe />
</Frame>

## New embed demo

*Justin He · `Embed` `Use Case`*

Justin shows off a brand new embedded demo full of NFL stats. A taste of what is achievable embedding Omni and curating the user experience.

<Frame>
  <iframe />
</Frame>

## Learning Omni microsite (guest demo!)

*`Guest Demo` `Docs`*

A guest demo from our friends at Wayflyer of a micro-site built to learn Omni using a mix of docs and our Youtube demos!Check it out at [learnomni.org](http://learnomni.org/)

<Frame>
  <iframe />
</Frame>

## Dashboard summarization AI

*Gustav Staprans · `Ai` `Dashboards`*

Continuing our work on AI dashboard summaries to pull out important insights and potential follow up areas. Plus a little UI work to make it more readible.

<Frame>
  <iframe />
</Frame>

## User scoped API keys

*Corey Ruderman · `Api`*

Close to the launch of user-scoped API keys. Now all of the external API use cases can be scoped to a specific account for more tactical API needs.

<Frame>
  <iframe />
</Frame>

## Progress chart

*Sarah Waterson · `Visualization`*

Another beautiful new Markdown chart showing progress in a metric with nice gradients for clarity (let us know if there is a real name for this chart type).

<Frame>
  <iframe />
</Frame>

## Visualization series type controls

*Rob Miller · `Visualization`*

You'll soon be able to toggle between temporal, nominal, and ordinal data types on charts for more granular handling of data sets when it needs to be just right.

<Frame>
  <iframe />
</Frame>

## Schedule to Omni groups

*Eli Cohen · `Scheduler`*

Now you can schedule to Omni user groups alongside email addresses.

<Frame>
  <iframe />
</Frame>

## Content validator dashboard search

*Mariel Freyre · `Modeling` `Administration`*

We added support for finding specific pieces of content (dashboards or workbooks) in the content validator. Best for tactical change management.

<Frame>
  <iframe />
</Frame>

## Modeler permission

*Conrad Slimmer · `Modeling` `Administration`*

We're launched model permissions beneath connection permissions, and also layered in a new modeler/developer user distinct from the connection admin.

<Frame>
  <iframe />
</Frame>

## Dynamic model extensions with Mustache

*Conrad Slimmer*

We're making model extensions smarter. Now you can call user attributes with mustache to create more complex model layers for the most complex data modeling challenges.

<Frame>
  <iframe />
</Frame>

## Snowflake semantic views

*Peter Whitehead · `Snowflake` `Modeling`*

An end to end demo of both querying and building Snowflake Semantic Views via Omni.

<Frame>
  <iframe />
</Frame>

## OpenID Connect

*Chris Merrick · `Administration`*

<Frame>
  <iframe />
</Frame>


# August 8, 2025
Source: https://docs.omni.co/demos/2025/20250808

Blobby Builds a Dashboard, More AI Everywhere, Snowflake Semantic Layer Sync, Top N + Other, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby builds a dashboard

*Steven Talbot · `Ai` `Workbook` `Dashboards`*

This week Blobby got unleashed. Continuing on the build out of Agent Blobby, we have a demo of AI doing a little bit of everything - building a plan, multi-query execution, some data modeling, and even building a dashboard. This is all locked up behind the agent launch (TBD), but huge progress in the scope of automated analysis.

<Frame>
  <iframe />
</Frame>

## Top N and other bin

*Jamie Davidson · `Workbook` `Visualization`*

We built a quick accelerator to bucket results into Top N + Other. This will also work across pivots or multiple series because it's backed by a mini data model. No more 200 slice pie charts.

<Frame>
  <iframe />
</Frame>

## Snowflake semantic layer sync

*Jamie Davidson · `Dbt` `Modeling`*

Now you can sync all the work in your Snowflake Semantic Layer into Omni seamlessly.

<Frame>
  <iframe />
</Frame>

## Dashboard smart summary

*Jamie Davidson · `Ai` `Dashboards`*

More infusing AI into everything in the app - this time adding dashboard summary text above the visualization powered by the visualization results themselves. Also opens up longer form hover-over descriptions of the tiles as well.

<Frame>
  <iframe />
</Frame>

## Smart KPI summary

*Jamie Davidson · `Ai` `Workbook` `Visualization`*

We added more AI to our KPI vis as well with an intelligent summary snippet to pair alongside metrics, changes, sparklines, etc.

<Frame>
  <iframe />
</Frame>

## Multi measure chart stacking update

*Nate Agrin · `Visualization`*

Huge progress unifying multi-measure and color faceted charts with stacking, labeling, and faceting. The new visualization pipeline will both improve the quality for existing vis, but also open up lots of really nice improvements around the edges of mixing all of these complex chart types together.

<Frame>
  <iframe />
</Frame>

## More dashboard 2.0 progress

*Luke Bowerman · `Dashboards`*

Luke gives another demo on the continuing progress around dashboard containers, tabs, and more filters around. Raw UI, but get to see the bones of all the future flexibility coming to the dashboard layer.

<Frame>
  <iframe />
</Frame>

## Fancy Markdown gallery

*Erin Cochran · `Visualization` `Docs`*

We dolled up the markdown gallery for faster, better, easier discovery of all the unique advanced visualizations you can build in Omni.

<Frame>
  <iframe />
</Frame>

## Super duper fast dbt sync

*Buck Ryan · `Dbt`*

We made everything surrounding the dbt workflow faster, plus a few metrics to prove it.

<Frame>
  <iframe />
</Frame>

## Login and home glow up

*Jared Hardy · `Design` `Content Management`*

Want to make sure the app always feels fresh, so we're polishing up the log-in page and the homepage landing experience. This all builds out the groundwork for more extensive full-app styling controls for folks that want to hijack our CSS and make it feel like theirs.

<Frame>
  <iframe />
</Frame>

## Primary / foreign key join inference

*Conrad Slimmer · `Modeling`*

We made our join inference a little smarter by reading the DB metadata to build a more comprehensive join library.

<Frame>
  <iframe />
</Frame>


# August 15, 2025
Source: https://docs.omni.co/demos/2025/20250815

Blobby Learns Filtered Measures, Bunch of API (Including A+ Docs), New SQL Mode, Databricks Metrics Views, and Tons of Quality of Life Work

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Filtered measures in AI

*Steven Talbot · `Ai` `In development`*

Blobby keeps getting smarter and will now build filtered measures for quick comparisons between user grouplets.

<Frame>
  <iframe />
</Frame>

## Offloaded schemas

*Steven Talbot · `Modeling` `Administration`*

We're making the model for efficient with giant schemas - new offloaded schemas allow Omni to query and use enormous schemas while reducing the model weight when using the core app. Hopefully just a silent change that makes Omni even faster for the most complex deployments.

<Frame>
  <iframe />
</Frame>

## Bunch of API

*Corey Ruderman · `Api` `Docs` `In development`*

New, dynamic API docs (full interactivity and responsive testing!), plus a bunch of new API work

<Frame>
  <iframe />
</Frame>

## New better SQL mode

*Mariel Freyre · `Sql` `Workbook` `In development`*

Better organization for SQL mode, table exploration, and some UX helpers for making SQL better in Omni

<Frame>
  <iframe />
</Frame>

## Databricks metrics view

*Jamie Davidson · `Databricks` `Modeling` `In development`*

Sync your Databricks Metrics Views into Omni, bringing all of your Databricks context into Omni into a tightly scoped for building on top of DWH metrics

<Frame>
  <iframe />
</Frame>

## Omni GPT (internal)

*James Ostergaard · `Internal` `Docs` `Ai`*

Quick demo of our internal tool for search Omni Docs, Slack, Fathom video recording

<Frame>
  <iframe />
</Frame>

## Demo analytics

*Erin Cochran · `Docs` `Internal`*

Internal for now, but some nice analytics on all of our demos for better searchibility and discovery.

<Frame>
  <iframe />
</Frame>

## Copy button validation

*Cade Austin · `Dashboard` `Workbook`*

Little quality of life change to validate button clicks for copying of debug outputs and tab copies.

<Frame>
  <iframe />
</Frame>

## Playwright end-to-end testing

*Nancy Chacko · `Internal` `Eng Productivity`*

Internal demo showing some new tooling to improve our testing and deployment

<Frame>
  <iframe />
</Frame>

## Bunch of calc / KPI / spreadsheet improvements

*Richard Czechowski · `Workbook` `Visualization`*

Bunch of quality of life work - consistent colors in formula field references, decimal places in KPIs, fast tab builder with references rather than hardcoded for spreadsheet tabs

<Frame>
  <iframe />
</Frame>

## Model specific embed roles

*Conrad Slimmer · `Modeling`*

We've extended all of the model permissioning to embed users, for more complex use cases

<Frame>
  <iframe />
</Frame>

## Departmental extension models

*Conrad Slimmer · `Modeling`*

Starting to lay the groundwork for new modeling mode to encourage / allow-for departmental model building rather than entirely ephemeral analysis.

<Frame>
  <iframe />
</Frame>

## Trash sorting

*Meredith Dodge · `Content Management`*

Quick tune up to sort the trash by archive date

<Frame>
  <iframe />
</Frame>

## Global user search

*Meredith Dodge · `Administration`*

Now user search hits all of the different user types at once

<Frame>
  <iframe />
</Frame>

## Sharing from the content page

*Meredith Dodge · `Content Management` `In development`*

Another quick quality of life improve to bring the share modal into the content foldering system rather than loading the dashboard every time

<Frame>
  <iframe />
</Frame>

## OIDC launch

*Chris Merrick · `Administration`*

We have launched OIDC support, and also offer a quick way to name the login button so it's easier for users.

<Frame>
  <iframe />
</Frame>


# August 22, 2025
Source: https://docs.omni.co/demos/2025/20250822

Dynamic Dashboard Spreadsheets, Spreadsheet Drill, Google Sheets Export, and lots of Blobby (Dashboard AI, Smart Filters, and Dash Search)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dynamic dashboard spreadsheets

*Richard Czechowski, Arielle Strong · `Spreadsheets` `Dashboards`*

Spreadsheets in Omni just got a new super power. Now you can unlock specific cells at the dashboard level for completely dynamic spreadsheet workflows - simulation, editing, override. We do a quick simulation demo for growth rates and financial assumptions, but huge possibilities now for all your dashboard users.

<Frame>
  <iframe />
</Frame>

## Spreadsheet drill (soon)

*Richard Czechowski · `Spreadsheets` `Dashboards` `Workbook`*

More super powers for your spreadsheets. Now cells with pre-existing Omni drills can bring that depth into the spreadsheet UI.

<Frame>
  <iframe />
</Frame>

## Google Sheets export (near launch)

*Eli Cohen · `Export` `Scheduling` `Google Sheets`*

A final demo of the native Google Sheets export functionality, including all the care we took to make sure you have all the controls you need for a diversity of use cases (append, replace, etc)

<Frame>
  <iframe />
</Frame>

## Blobby learns to query from the dashboard

*Gustav Staprans · `Ai` `Dashboards`*

An end-to-end demo of using AI to go deeper from the context of the dashboard.

<Frame>
  <iframe />
</Frame>

## Blobby learns to check filter values

*Steven Talbot · `Ai` `Workbook` `Dashboards` `Filtering`*

Sometimes users don't know the exact format of a filter value - it is USA, US, or United States.  Now it doesn't matter.  Agent Blobby will check for valid filter inputs to make sure users find what they need.

<Frame>
  <iframe />
</Frame>

## Blobby learns to search for content

*Gustav Staprans · `Ai` `Content Management` `Dashboards`*

Soon Blobby will be able to query or navigate to pre-existing content in Omni like dashboards.

<Frame>
  <iframe />
</Frame>

## More dashboard cubing work

*TJ Banghart · `Dashboards` `Modeling` `Performance`*

We're still working on making dashboards faster. Here we show a quick demo of building topic-specific cubes to enable instant dashboard results on smaller data sets, without sacrificing access to the full data set beneath.

<Frame>
  <iframe />
</Frame>

## Quick move tab to front or back

*Jared Hardy · `Workbook`*

Little bit of quality of life work to enable easier tab organization inside your workbooks.

<Frame>
  <iframe />
</Frame>

## Bunch of naming and nav cleanup

*Luke Bowerman · `Workbook` `Content Management` `Design`*

We did an audit across the product to make navigation and naming more clear.

<Frame>
  <iframe />
</Frame>

## New git docs

*Erin Cochran · `Docs`*

We shipped a bunch of new docs about git config and management.

<Frame>
  <iframe />
</Frame>


# August 29, 2025
Source: https://docs.omni.co/demos/2025/20250829

AI Session Saving, IDE Folders, New SQL Experience, and Lots More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI session saving / state

*Steven Talbot · `Ai` `In development`*

We're doing the legwork to make all of your AI sessions stateful - quickly share an AI session with a coworker, or return to a previous analysis with all of the context.

<Frame>
  <iframe />
</Frame>

## Passing dashboard queries into AI context

*Gustav Staprans · `Ai` `Workbook`*

We're experimenting with bringing all of the queries from your existing dashboards into AI context to improve quality and relevance.

<Frame>
  <iframe />
</Frame>

## IDE folders (soon)

*Jamie Davidson · `Modeling` `In development`*

A first look at some new tooling for managing complex development environments.

<Frame>
  <iframe />
</Frame>

## Schema filtering with wildcards

*Conrad Slimmer · `Modeling` `Administration`*

Some new tools for curating the data model and improving performance.

<Frame>
  <iframe />
</Frame>

## New SQL UX launch

*Mariel Freyre · `Sql` `Workbook` `In development`*

A final demo of the new SQL experience.

<Frame>
  <iframe />
</Frame>

## Nominal map colors

*Rob Miller · `Visualization` `Maps`*

Now maps can color across both categoricals and scaled ranges.

<Frame>
  <iframe />
</Frame>

## Top N and other launch

*Jamie Davidson · `Workbook`*

Finishing touches on the quick grouping experience in the UI

<Frame>
  <iframe />
</Frame>

## Dashboard AI subtitle refinement

*Jamie Davidson · `Dashboards`*

We opened up some custom prompting and did a bit of work on managing long subtitles.

<Frame>
  <iframe />
</Frame>

## Thermometer vis

*Sarah Waterson · `Visualization`*

A new markdown vis for goal setting.

<Frame>
  <iframe />
</Frame>

## Vis gallery in docs

*Erin Cochran · `Docs` `Visualization` `In development`*

We completely overhauled the experience for navigating custom Vega Lite visualizations and markdown visualizations, so you can explore everything visually.

<Frame>
  <iframe />
</Frame>

## IDP initiated login (soon)

*Chris Merrick · `Administration` `In development`*

A first look at logging in to Omni directly from your IDP provider.

<Frame>
  <iframe />
</Frame>

## More dev tooling (internal)

*Nancy Chacko · `Internal`*

A quick demo of some new developer tooling featuring Playwright.

<Frame>
  <iframe />
</Frame>

## Front end dev tooling with Storybook (internal)

*Meredith Dodge · `Internal`*

* New internal tools to speed up and improve quality for our front-end development experience.

<Frame>
  <iframe />
</Frame>

## Faster front end builds (internal)

*Trey Shugart · `Internal`*

More work on front-end build times so we can build you more things faster.

<Frame>
  <iframe />
</Frame>


# September 5, 2025
Source: https://docs.omni.co/demos/2025/20250905

Custom Permissions, YAML Editor Guest Demo, Independent Chart Stacking Controls, and More Quality of Life

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Custom permissions first look

*Conrad Slimmer · `Administration`*

A first look at the complete flexibility of fine grain permission controls. Soon you'll be able to define nearly every application experience into custom permission sets.

<Frame>
  <iframe />
</Frame>

## YAML editor (guest demo)

*`Modeling` `Guest Demo`*

Another guest demo from our friends at Ramp. This is a full UX for editing and managing the data model.

<Frame>
  <iframe />
</Frame>

## Multi measure dual stacking

*Nate Agrin · `Visualization`*

Getting close to the finish line for our backend overhaul of the vis framework, putting the finishing touches on the multi-measure experience, including independent stacking controls while maintaining the legend click experience.

<Frame>
  <iframe />
</Frame>

## Spreadsheet quality of life

*Richard Czechowski · `Spreadsheets`*

A grab bag of improvements to the spreadsheet experience - easier dashboard layouts, quickly add rows, and more graceful erroring.

<Frame>
  <iframe />
</Frame>

## Dynamic text on dashboard helpers

*Richard Czechowski · `Dashboards`*

We brought the field / filter selector to the dashboard experience for quickly mapping dynamic text to markdown tiles.

<Frame>
  <iframe />
</Frame>

## Race visualization

*Sarah Waterson · `Visualization`*

Always adding to our long tail visualization library - this one a progress / race visualization for the competitive folks.

<Frame>
  <iframe />
</Frame>

## Scheduler error details

*Corey Ruderman · `Scheduler` `Administration`*

Rather than wait on our team for log detail when schedules fail, we're lifting the debug experience to the app for simpler administration.

<Frame>
  <iframe />
</Frame>

## Content validation for non admins (bulk dashboard editing)

*Steven Talbot · `Administration` `Modeling` `Dashboards`*

We overhauled the content management experience to allow non-admins to make bulk edits to the content system when required.

<Frame>
  <iframe />
</Frame>

## Dashboard AI UX polish

*Sarah Waterson, Gustav Staprans · `Dashboards` `Ai`*

Lots of UX polish for the soon-to-release dashboard AI experience.

<Frame>
  <iframe />
</Frame>

## Exploration nested navigation management

*Luke Bowerman · `Content Management` `Ux`*

We improved navigation for multi-model deployments.

<Frame>
  <iframe />
</Frame>

## Dashboard settings tidy up

*Meredith Dodge · `Dashboards`*

Bit of housekeeping for the dashboard editing experience - more groundwork for the appy dashboard experience coming soon.

<Frame>
  <iframe />
</Frame>


# September 12, 2025
Source: https://docs.omni.co/demos/2025/20250912

A New User Attribute Debugger UI, MCP Oauth, Vis Reaggregation Alpha, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## User attribute debugger UI

*Conrad Slimmer · `Administration` `Modeling` `Dashboards`*

Validating a complex system of per-user variables can be challenging, so we're building a front end experience to control user attributes for quick debugging and faster modeling even in the most complex deployments.

<Frame>
  <iframe />
</Frame>

## Smart vis re-aggregation

*Jamie Davidson · `Visualization` `Workbook`*

An early experiment to allow visualization to re-aggregate data. Would make vis more clear and make it simpler to iterate over big, wide tables. Lots of explore here would love thoughts.

<Frame>
  <iframe />
</Frame>

## MCP OAuth v0

*Gustav Staprans · `Ai` `Mcp` `Administration`*

A first demo of per-user Oauth combined with the MCP experience.

<Frame>
  <iframe />
</Frame>

## Compound access grant logic

*Conrad Slimmer · `Modeling` `Administration`*

Now you can combine AND/OR (well really | and &) in your access grants.

<Frame>
  <iframe />
</Frame>

## Topic UI join builder

*Alisa Tatarinova · `Workbook`*

Continuing to lift more complex modeling into the UI - now layering in join building to the topic building experience.

<Frame>
  <iframe />
</Frame>

## Snowflake connection config improvements

*Jonathan Swenson · `Administration`*

We're adding support for more complex Snowflake proxies and also simplifying the keypair config experience.

<Frame>
  <iframe />
</Frame>

## Small multiple label controls

*Rob Miller · `Visualization`*

A sprinkle of additional config for the small multiples chart labels.

<Frame>
  <iframe />
</Frame>

## Improving dbt description pushdown

*Buck Ryan · `dbt`*

Bit of tuning the dbt promotion workflow to improve reliability and quality of pushing down metadata.

<Frame>
  <iframe />
</Frame>

## Map size clamping

*Rob Miller · `Visualization`*

We tuned up maps to better highlight the difference between values.

<Frame>
  <iframe />
</Frame>

## Performance profiler (internal tooling)

*Kalen Petersen · `Internal Tools` `Engineering Productivity`*

Another internal tools demo for the curious about how we understand performance bottlenecks.

<Frame>
  <iframe />
</Frame>

## Engineering test improvements (internal tooling)

*Kalen Petersen · `Internal Tools` `Engineering Productivity`*

Another internal tools example from improving engineering testing coverage.

<Frame>
  <iframe />
</Frame>


# September 19, 2025
Source: https://docs.omni.co/demos/2025/20250919

dbt Semantic Layer, MCP OAuth, Model Blame, AI Session URLs, Huge Performance Wins for Vis, and 11 More!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## dbt Semantic Layer

*Buck Ryan · `dbt` `Modeling`*

Our first demo of building the Omni data model with your dbt semantic layer.  Lots more work to do here bringing different field types into Omni, but much progress on syncing models between systems.

<Frame>
  <iframe />
</Frame>

## AI session history

*Steven Talbot · `Ai`*

We're launching sticky, shareable sessions for AI - allowing users to return to previous analyses or share the outputs with coworkers.

<Frame>
  <iframe />
</Frame>

## Vega re-aggregation alpha

*Nate Agrin · `Visualization` `Performance`*

We're continuing to experiment with ways to make giant data sets visualize quickly and intuitively.  Still more to figure out here, but progress on these new workflows.

<Frame>
  <iframe />
</Frame>

## Model blame history

*Cathy Lennon · `Modeling` `Administration`*

Rather than hunting through your git provider, we're bringing blame to the model to understand the most recent changes to fields, views, topics, and relationships.

<Frame>
  <iframe />
</Frame>

## Dashboard filters anywhere

*Luke Bowerman · `Dashboards`*

We're getting close to some huge new functionality on dashboards.  Here we demo new dashboard containers, allowing sticky filters, moving filters alongside tiles or groups of tiles, and new layout experiences.  Coming soon (end of Sept)!

<Frame>
  <iframe />
</Frame>

## Massive vis, big performance wins

*Nate Agrin · `Visualization` `Dashboards`*

We're continuing to toil away on the most complex, largest visualizations.  Here, some work to optimize tooltips in edit mode (ie hide them), and new work to pause rendering for dashboard arrangement - the combo massively speeds up the browser for visualizations with thousands or tens of thousands of data points.

<Frame>
  <iframe />
</Frame>

## Easy column renaming

*Sarah Waterson · `Workbook`*

A little tune up to make editing column headers easier via right click.

<Frame>
  <iframe />
</Frame>

## Full app CSS control

*`Embed` `Administration`*

The first demo of fulling customizing styles in Omni (think content system, even admin pages).

<Frame>
  <iframe />
</Frame>

## Fine grain auth controls

*Luke Bowerman · `Administration`*

A bit of new functionality to fine tune the login experience, including hiding Google Auth and magic links for the SAML folks.

<Frame>
  <iframe />
</Frame>

## Per user API tokens

*Corey Ruderman · `Api` `Administration`*

Now the API can be scoped and provisioned on a per-user basis for locking permissions to a given user rather than setting up global auth.

<Frame>
  <iframe />
</Frame>

## Git settings overhaul

*Jared Hardy · `Modeling` `Git`*

We massively overhauled the git setting page to make configuration and management simpler and more understandable.

<Frame>
  <iframe />
</Frame>

## Bulk branch management

*Meredith Dodge · `Modeling`*

Now developers can manage all of their Omni branches in one place, including fast cleanup of unused branches and lots of metadata to more easily understand what is outstanding.

<Frame>
  <iframe />
</Frame>

## MCP OAuth

*Gustav Staprans · `Ai` `Mcp` `Administration`*

User permissions can now be passed to the MCP server, allowing fine grain permissions on a per-user basis for DIY use cases outside Omni.

<Frame>
  <iframe />
</Frame>

## Mapping GeoJSON data directly from fields

*Rob Miller · `Visualization` `Maps`*

A new option for bringing map data into Omni.  We're now able to read from GeoJSON in the result set to dynamically map row by row.

<Frame>
  <iframe />
</Frame>

## Embed scroll jumping fix

*Nate Agrin · `Embed` `Dashboards`*

We improved the navigation experience for embedded iframes to smooth out the end user experience during resorting and drilling.

<Frame>
  <iframe />
</Frame>


# September 26, 2025
Source: https://docs.omni.co/demos/2025/20250926

Fast Rendering of Giant Visualizations, New Schema Model Navigation, Mapping Result GeoJSON, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Fast giant vis

*Nate Agrin · `Visualization` `Dashboards`*

Lots of hidden work to make rendering the largest data sets performant in Omni. Here we demo some early work to offload much of that work out of the browser. More work to do, but exciting progress.

<Frame>
  <iframe />
</Frame>

## Navigating huge schema models

*Mariel Freyre · `Workbook` `Sql`*

Another early preview of some adjustment to All Views and Fields to handle larger, more complex data sets. Any thoughts appreciated as we rebuild the experience.

<Frame>
  <iframe />
</Frame>

## Mapping GeoJSON in results launch

*Rob Miller · `Visualization` `Maps`*

You saw the preview last week, but launching the new dynamic row-by-row GeoJSON mapping for beautiful map vis with completely custom map objects.

<Frame>
  <iframe />
</Frame>

## Download direct from AI chat

*Steven Talbot · `Ai` `Export`*

Title says it all - now you can download query results directly from the chat experience.

<Frame>
  <iframe />
</Frame>

## MCP with links back to Omni

*Gustav Staprans · `Ai` `Mcp`*

Now MCP usage will link back to Omni for quick follow-ups. Additionally the per user API tokens will now naturally extend to the MCP experience.

<Frame>
  <iframe />
</Frame>

## Calc AI UX improvements

*Sarah Waterson · `Calcs` `Workbook`*

Little bit of UX love for long Calc AI use cases

<Frame>
  <iframe />
</Frame>


# October 3, 2025
Source: https://docs.omni.co/demos/2025/20251003

External Development IDE, Lots of Blobby, Moving Dashboard Filters, Localization, SQL Preamble, and 15 (!!!) More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Omni IDE native in Claude Code (external development IDE)

*Steven Talbot · `Ide` `Modeling`*

We're working on bringing the develop experience anywhere you are. Here we show some model building in a branch using Claude Code. Soon you'll be able to develop in Omni in whatever development environment you prefer.

<Frame>
  <iframe />
</Frame>

## Blobby learns planning checklists

*Gustav Staprans · `Ai`*

Now when Blobby builds query plans, you'll see a full breakdown of queries and Blobby will check-off tasks as they are completely. The goal is just better control and insight into the querying process for AI.

<Frame>
  <iframe />
</Frame>

## Blobby session sharing improvements

*Steven Talbot · `Ai`*

Now you can quickly re-run queries from AI sessions you share or return too. We also polished up the sidebar experience for finding any of your previous chats.

<Frame>
  <iframe />
</Frame>

## Blobby writes a 500 join query

*Colin Zima · `Ai`*

We hope you never do this, but sometimes it's fun to test the bounds of the app and Blobby. Here Blobby writes a 500 join query without sweating.

<Frame>
  <iframe />
</Frame>

## New dash almost launch (sections and moveable filters)

*Luke Bowerman · `Dashboards`*

We're nearing the launch of flexible dashboard filters, the first of many pieces of work to more completely customize the full dashboard experience.

<Frame>
  <iframe />
</Frame>

## Localization first look

*Arielle Strong, Trey Shugart · `Dashboards` `Administration` `Localization`*

First look at a fully localized Omni dashboard. More to do, but great progress.

<Frame>
  <iframe />
</Frame>

## SQL preamble

*Steven Talbot · `Modeling`*

You can now run arbitrary command in the database prior to queries. This opens up all sorts of custom workflows including UDFs or custom user variables.

<Frame>
  <iframe />
</Frame>

## Fast, performant giant vis

*Rob Miller · `Visualization` `Performance`*

We're getting close to rolling out an overhaul to our rendering experience for vis that massively improves performance on the largest queries.

<Frame>
  <iframe />
</Frame>

## Map region backgrounds

*Rob Miller · `Visualization` `Maps`*

We add custom background so your shapefiles can be more clear in empty zones if you'd prefer.

<Frame>
  <iframe />
</Frame>

## Range bound charts

*Sarah Waterson · `Visualization`*

Another new custom vis, this one for representing metrics inside a target band.

<Frame>
  <iframe />
</Frame>

## Bullet charts

*Colin Zima · `Visualization`*

We're adding new code for a pair of bullet visualization implementations - one in Vega that we demo here and another beautiful example with markdown.

<Frame>
  <iframe />
</Frame>

## Custom trendline colors

*Nate Agrin · `Visualization`*

Nearing the completion of our major vis refactor, but added a bit more functionality to customize trend lines.

<Frame>
  <iframe />
</Frame>

## Query performance analytics

*Jade Khiev · `Analytics` `Performance`*

We added a new dashboard to analytics with a full breakdown of query performance for much better understanding of end user experience and where to focus developer effort.

<Frame>
  <iframe />
</Frame>

## Sharing ephemeral spreadsheets via URL

*Arielle Strong, Richard Czechowski · `Spreadsheets` `Dashboards`*

Now when end users take advantage of dynamic spreadsheets on dashboards, they can be shared in their edited state.

<Frame>
  <iframe />
</Frame>

## Drill embed event

*Nate Agrin · `Embed` `Dashboards` `Api`*

We added a custom event for developers to capture drill events and build any customization desired.

<Frame>
  <iframe />
</Frame>

## More app CSS theming

*Elliot Park · `Embed` `Administration`*

Continuing the build out of custom theming across the entire app. Here we demo some custom sidebars.

<Frame>
  <iframe />
</Frame>

## Custom unnested JSON field naming and better schema refresh

*Conrad Slimmer · `Modeling`*

Pair of demos. First, some work to give more control over names for fields from nested JSON. Second, bit of tune up to the schema refresh to make it simpler.

<Frame>
  <iframe />
</Frame>

## Grab gab of new docs

*Erin Cochran · `Docs`*

We landed a bunch of new docs this week on everything from mustache to email user attributes to APIs to SCIM.

<Frame>
  <iframe />
</Frame>


# October 10, 2025
Source: https://docs.omni.co/demos/2025/20251010

Docs in the IDE, Cube Building, Lots of AI, External Model Dev Launch, dbt Metrics, Spreadsheet Export, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Docs in the IDE

*Steven Talbot · `Modeling` `Docs`*

A first look at in-line documentation in the IDE. No more digging for docs as you build, now you have the full model reference code base at your fingertips.

<Frame>
  <iframe />
</Frame>

## Cube builder + debugger

*TJ Banghart · `Development` `Workbook` `Performance`*

We added a UI builder for Cubes (aggregate awareness to build intermediate caching), plus layered in clear debugging for the inspector. This is all in service of faster dashboards and exploration for everyone.

<Frame>
  <iframe />
</Frame>

## Blobby learns multi modal inputs (ie files)

*Gustav Staprans · `Ai`*

Blobby has a new skill - now you can bring files into your AI analyses - including CSVs, PDFs, and images. This means Blobby can be used for "vanilla" analyses, alongside Omni queries. Also includes some discussion of future extension points.

<Frame>
  <iframe />
</Frame>

## AI summarization row limit massive increase

*Steven Talbot · `Ai`*

We massively increased the data available for summarization and analysis via AI. There are still limits for enormous data sets based on Claude token input limits, but now we're using all of it.

<Frame>
  <iframe />
</Frame>

## Blobby gets even better at checklists

*Gustav Staprans · `Ai`*

Continuing to iterate on deep research mode to make Blobby more disciplined around multi-query workflows and logical chains. Here we make sure each task is being completed and checked off.

<Frame>
  <iframe />
</Frame>

## Dashboard AI topic helper

*Gustav Staprans · `Ai` `Dashboards`*

We added some helper text for editors to understand the AI experience that will be available to dashboard AI users.

<Frame>
  <iframe />
</Frame>

## Omni external IDE launch (this week)

*Steven Talbot · `Npm` `Modeling`*

We're getting close to release our external IDE experience in NPM. Search for "Omni Client YAML Local Something Something" soon.

<Frame>
  <iframe />
</Frame>

## dbt Semantic Layer Metrics

*Buck Ryan · `dbt` `Modeling`*

We're still working on bringing your dbt semantic models into Omni. We've extended model building to metrics in your dbt models, plus bit of discussion on future work.

<Frame>
  <iframe />
</Frame>

## LOD field improvements

*TJ Banghart · `Workbook` `Modeling`*

Continuing to tune up the level-of-detail metrics building experience, including some new icons to make them clearer.

<Frame>
  <iframe />
</Frame>

## Exporting formatted spreadsheets

*Richard Czechowski · `Spreadsheets` `Exports` `Scheduler`*

Now your spreadsheets will export in all their formatted glory for both downloads and scheduling. We'll also bring dependency data tabs to make sure everything is working nicely.

<Frame>
  <iframe />
</Frame>

## Dynamic subtotals with controls

*Richard Czechowski · `Workbook` `Dashboards`*

We polished up the experience with subtotaled tables and controls to allow for dynamic grouping hierarchy and layouts.

<Frame>
  <iframe />
</Frame>

## Table resizing & IDE updates

*Jared Hardy · `Design` `Workbook` `Modeling`*

Bunch of polish to the table resizing experience, and bit of work on icons in the IDE as well

<Frame>
  <iframe />
</Frame>

## IDP initiated SAML launch

*Chris Merrick · `Administration`*

We'll be opening up IDP initiated SAML next week for customers, so enjoy one final demo.

<Frame>
  <iframe />
</Frame>

## Omni testing in Playwright

*Nancy Chacko · `Internal` `Engineering Productivity`*

We've improved our testing to allow for more, faster development for our team.

<Frame>
  <iframe />
</Frame>


# October 17, 2025
Source: https://docs.omni.co/demos/2025/20251017

AI Workflows, ERD Diagrams, CSS Previews, New Filter UX, and More Blobbies Than You Can Handle

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI Workflows

*Gustav Staprans · `Ai`*

A new skills system for Blobby. Now developers can build structured workflows (think input requirements, multi-step analysis) directly into Blobby. This means your most common workflows - lookups, cohort analysis, really anything can be tightly controlled and organized for end users. Excited to see what folks build here.

<Frame>
  <iframe />
</Frame>

## Claude Haiku 4 5 almost launch

*Steven Talbot · `Ai`*

A sort of demo of the new Haiku 4.5 experience - smarter, faster, cheaper - coming soon.

<Frame>
  <iframe />
</Frame>

## ERD Diagrams

*Richard Czechowski · `Modeling` `Workbook` `Coming Soon`*

We have a beautiful new dedicated UX for understanding your join structure in the data model.

<Frame>
  <iframe />
</Frame>

## CSS preview mode

*Elliot Park · `Embed` `Administration` `Design`*

We built a new experience to quickly understand the custom styling in light and dark mode to tighten up the experience quickly.

<Frame>
  <iframe />
</Frame>

## Filter duplication on dashboards

*Alisa Tatarinova · `Dashboards`*

More groundwork for our new dashboard experience. Now you can duplicate filters on the same field and apply differentially. This means tile-level filters will be easy and flexible.

<Frame>
  <iframe />
</Frame>

## Navigation improvements (workbook tab search)

*Jared Hardy · `Dashboards` `Workbook`*

Always tuning up quality of life. Here we have a pair of UX improvements to get what you want quicker and more easily, including a beautiful new tab search experience for workbooks.

<Frame>
  <iframe />
</Frame>

## Omni CLI improvements

*Steven Talbot · `Modeling`*

We tightened up the [CLI experience](https://www.npmjs.com/package/@omni-co/model-local-editor?activeTab=readme) for syncing with main, and now have folks using our package live. Take a look!

<Frame>
  <iframe />
</Frame>

## Faster Slack scheduling

*Corey Ruderman · `Scheduler` `Slack`*

Pulling metadata from the Slack API is pretty slow, so we reworked our experience to make sure that's not a blocker to building schedules.

<Frame>
  <iframe />
</Frame>

## Improving developer productivity (internal)

*Luke Bowerman · `Internal` `Developer Productivity`*

An internal facing demo of some improvements to our developer workflows.

<Frame>
  <iframe />
</Frame>

## Blobby designer studio

*Jared Hardy · `Ai` `Blobby` `Why Not`*

We built a web app so anyone can build their own Blobby. More for us than you, but have fun with it.

<Frame>
  <iframe />
</Frame>

## Blobby image repo

*Richard Czechowski · `Ai` `Blobby` `Why Not`*

We've gotten lots of questions about our ridiculous breadth of Blobby emojis in Slack, so landed a repo of Blobbies all kinds for the enjoyers out there.

<Frame>
  <iframe />
</Frame>


# October 24, 2025
Source: https://docs.omni.co/demos/2025/20251024

Tons of Dashboard Work, More AI, Better Conditional Formatting, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## More dashboard containers

*Luke Bowerman · `Dashboards`*

Another preview of all the work on dashboard building with our new containers system (ie floating filters and sections).

<Frame>
  <iframe />
</Frame>

## Workbook query linking

*Steven Talbot · `Dashboards` `Workbook`*

Soon you'll be able to duplicate, but lock linkage to queries in your workbook. This allows separate visualizations of the same data, with firm linking to the source query for better reusability and management.

<Frame>
  <iframe />
</Frame>

## Dashboard required filters preview

*Steven Talbot · `Dashboards`*

A first look at required filters for dashboards. Still a little UX polish here, but now you can build workflow into your dashboards better.

<Frame>
  <iframe />
</Frame>

## More extracts progress

*TJ Banghart · `Dashboards` `Performance` `Workbook`*

A bunch of work on building and managing extracts (plus take a look at the query speed underneath).

<Frame>
  <iframe />
</Frame>

## Easier query references on dash markdown

*Meredith Dodge · `Dashboards`*

We made it easier to call queries for fast dynamic dashboard text building.

<Frame>
  <iframe />
</Frame>

## Embed user dynamic scheduling with user attributes

*Nate Agrin · `Embed` `Dashboards` `Scheduler`*

Now when scheduling to embed user emails, you can utilize send as recipient for dynamic scheduled content to your existing embed users.

<Frame>
  <iframe />
</Frame>

## New embed vanity domain cookie controls

*Nate Agrin · `Embed` `Administration`*

Some new tools for managing authentication cookies in embed deployments with vanity domains.

<Frame>
  <iframe />
</Frame>

## AI file upload v2

*Gustav Staprans · `Ai`*

Now your uploaded files will be retained for the full session, or even multiple files (modulo context window), for deeper, more-complex analyses.

<Frame>
  <iframe />
</Frame>

## AI topic builder v1

*Gustav Staprans · `Ai` `Workbook`*

We're coming up with easier ways to build topics using AI.

<Frame>
  <iframe />
</Frame>

## AI topics organization

*Gustav Staprans · `Ai`*

We tidied up topic select in chat.

<Frame>
  <iframe />
</Frame>

## Better conditional formatting text

*Jared Hardy · `Visualization`*

We tuned up when to use white or black text with conditional formatting and cell highlighting to make sure the values pop.

<Frame>
  <iframe />
</Frame>

## Uptime vis and progress vis

*Sarah Waterson · `Visualization`*

More new markdown vis for showing charts like uptime levels or progress to goal with highlighting.

<Frame>
  <iframe />
</Frame>

## Cache only auto run

*Jonathan Swenson · `Performance` `Workbook`*

A new experience that allows being conservative with database load (ie hit the run button), but still allows for instant results from the cache. Great for cache debugging as well.

<Frame>
  <iframe />
</Frame>

## More work on scalable vis pipeline

*Nate Agrin · `Visualization`*

We're nearing the end of our project to make large visualizations more scalable and faster. The last piece was our smart label work.

<Frame>
  <iframe />
</Frame>


# October 31, 2025
Source: https://docs.omni.co/demos/2025/20251031

Tons of Dashboard Work (AI Summaries, Custom Errors, Localization, and More), More Cubes, and Getting Close on Custom Permissions

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Full dash summary tiles

*Gustav Staprans · `Ai` `Dashboards`*

We're building another AI layer in Omni for summarizing and analyzing the results of many queries on a dashboard. Just another way to make the query results more consumable for your end users.

<Frame>
  <iframe />
</Frame>

## Dashboard custom errors and empty messages

*Alisa Tatarinova · `Dashboards`*

Continuing the work to give you every control for creating amazing experiences on polished dashboards - now you can insert custom empty messages or error messages.

<Frame>
  <iframe />
</Frame>

## Dashboard localization beta

*Arielle Strong, Trey Shugart · `Dashboards` `Administration`*

Our dashboards are now available in more languages. We're beginning to role out Omni for embedded use cases in other languages. Plus some discussion of follow-on work around localization.

<Frame>
  <iframe />
</Frame>

## Dashboard Containers

*Luke Bowerman · `Dashboards`*

Another demo of the significant overhaul to dashboard construction, including some nice quality of life work around managing and deleting tiles.

<Frame>
  <iframe />
</Frame>

## Wire dash filters to calcs

*Steven Talbot · `Dashboards`*

Now you can map dashboard filters to calculations as well as dimensions and measures.

<Frame>
  <iframe />
</Frame>

## Fully cubed dash demo

*Jonathan Swenson · `Dashboards` `Performance`*

We're still working on enabling instant slice and dice for dashboard. Here we demo a dashboard fully served out of the cubing layer.

<Frame>
  <iframe />
</Frame>

## Custom permissions almost launch

*Conrad Slimmer · `Administration`*

We're getting close on new custom permissions. A demo of how we handle duplication and resolution between different permission groupings.

<Frame>
  <iframe />
</Frame>

## Pie charts rebuild

*Rob Miller · `Visualization`*

We're tried to torture Vega into allowing for great pie charts, unfortunately we haven't found a clear path. So we're testing eCharts for pies to open up much better user experiences. We'll explore this system for a variety of charts that can complement the Vega Lite core.

<Frame>
  <iframe />
</Frame>

## Nate grab bag

*Nate Agrin · `Embed` `Visualization`*

A trio of demos here: 1. turning off right click actions for embed. Just another way to tune the experience and deliver exactly what you want 2. better URL encoding for markdown values (now you can request the URL encoded markdown) and 3. multi-line selection and formatting in markdown

<Frame>
  <iframe />
</Frame>

## Subtitle on off error fix

*Gustav Staprans · `Dashboards`*

Quick fix to more elegantly handle AI summaries when the feature gets flipped off.

<Frame>
  <iframe />
</Frame>

## Golden AI examples

*Jamie Davidson · `Ai` `Workbook`*

Early work as some new UI for preparing and sharing golden AI queries

<Frame>
  <iframe />
</Frame>


# November 7, 2025
Source: https://docs.omni.co/demos/2025/20251107

Stacked Bar Sorting, Deep Research Launch, Topic Scoped Fields in the UI, Lots of Performance Work and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Stacked bar size sorting

*Nate Agrin · `Visualization`*

Our second most requested feature is done. Now that we've landed a bunch of the vis rework for stacked and grouped bars, we've opened up dynamic stack ordering for stacked charts.

<Frame>
  <iframe />
</Frame>

## Deep research near launch

*Gustav Staprans · `Ai`*

We're getting ready to open up deep research for everyone. This enables Blobby to build and check off multi-stage plans for deeper analysis on the same governed foundation.

<Frame>
  <iframe />
</Frame>

## Topic scoped field building in the UI

*TJ Banghart · `Workbook` `Modeling`*

Omni has always had the ability to build fields for re-use everywhere, or only inside a single-topic. Now we've wired that up to the UI for way better curation of complex data models. This also lays the ground work for moving fields from views into topics and back from topics into views. Making sure we have the best tools in the world for managing semantics.

<Frame>
  <iframe />
</Frame>

## All views and fields overhaul

*Mariel Freyre · `Workbook` `Sql` `Performance`*

We're getting close to release for a new experience meant to better handle massive schemas. Better search, handling for offloaded schemas (TLDR faster search because less metadata), and some UX tune-ups.

<Frame>
  <iframe />
</Frame>

## Buncha map tune-ups

*Rob Miller · `Visualization` `Maps`*

We improved color opacity and layering for maps to make sure they maintain readability while still looking great.

<Frame>
  <iframe />
</Frame>

## Conditional formatting final tune-up

*Jared Hardy · `Visualization` `Tables`*

Little bit of tune up to our work last week to improve conditional formatting readability. This takes it the last mile with text color intelligence across light and dark mode (after some customer feedback, thank you).

<Frame>
  <iframe />
</Frame>

## Way faster pivots

*Steven Talbot · `Performance`*

We did a bunch of work in the background to make pivots over large data sets with fill much faster.

<Frame>
  <iframe />
</Frame>

## Scheduler scale improvements (to support bursting)

*Jonathan Swenson · `Scheduler` `Performance`*

We're bulking up the scheduler to allow for significantly more scale in sharing reporting dynamically across many users in one shot (bursting).

<Frame>
  <iframe />
</Frame>

## Better content permission debugging

*Meredith Dodge · `Administration` `Dashboards`*

We made content permissions more clear when permissions are being inherited from parent folders.

<Frame>
  <iframe />
</Frame>

## Quick SQL UX tune up

*Jared Hardy · `Sql` `Workbook`*

We made dragging fields into the SQL editor way easier

<Frame>
  <iframe />
</Frame>


# November 14, 2025
Source: https://docs.omni.co/demos/2025/20251114

Dashboard View As, Dashboard Summary AI Getting Close, New Docs, Better Query Killing and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard view as

*Jordan Greissman · `Dashboards` `Embed`*

Now in a couple clicks you can view a dashboard as any user in the system. Fast debugging and embed configuration. Also our first demo from the Explo team!!

<Frame>
  <iframe />
</Frame>

## Dashboard summary AI (getting close)

*Gustav Staprans · `Dashboards` `Ai`*

Continuing work on dashboard AI summarization. We overhauled the UX to enable selectively including queries and making sure we aren't running extra queries either. All in service of intelligent summaries across a bunch of different queries, even through the scheduler.

<Frame>
  <iframe />
</Frame>

## New docs

*Erin Cochran · `Docs`*

The docs are getting a huge overhaul in service of better search and a simpler navigation experience. We're still a few weeks out, but will include AI Q\&A and a hugely improved search experience.

<Frame>
  <iframe />
</Frame>

## Better query killing

*Jonathan Swenson · `Performance` `Administration`*

We tuned up the heuristics for handling abandoned queries to make sure we keep the database load as light as possible and optimize performance.

<Frame>
  <iframe />
</Frame>

## In-app chat beta

*James Bueche · `Support` `Administration`*

While most customers have a great experience with our live Slack chat, we are also opening up in-app chat for folks that prefer the web native experience. Want to make sure anyone who needs real time support gets it.

<Frame>
  <iframe />
</Frame>

## Smarter in\_query

*Steven Talbot · `Performance` `Modeling`*

We tuned up in\_query to improve query optimization on non-dependent tables. Should be mostly silent but just much faster for complex dynamic queries.

<Frame>
  <iframe />
</Frame>

## Color palette builder UX

*Jared Hardy · `Ux` `Embed` `Administration`*

We tuned up the color palette building experience for customizing the full app - now with previews and a front-end for color picking. All about making the basics delightful.

<Frame>
  <iframe />
</Frame>

## More dashboard UX

*Meredith Dodge · `Dashboards`*

We're continuing the work to extend configuration in the dashboard experience.

<Frame>
  <iframe />
</Frame>

## dbt branch development in Omni

*Buck Ryan · `dbt` `Modeling`*

Now you can coordinate work in dbt branches alongside Omni branches seamlessly.

<Frame>
  <iframe />
</Frame>

## Employee info in chat AI

*Colin Zima · `Ai` `Use Cases`*

A quick internal demo of bring our employee data into Blobby's AI context. Incredible for quickly working with the context of the business over analytics (show me XYZ's team performance, etc).

<Frame>
  <iframe />
</Frame>

## Custom permissions launch

*Arielle Strong · `Administration`*

We rolling out the customization of fine-grained application controls for end users. Will be continuing to build out depth of control here across the app.

<Frame>
  <iframe />
</Frame>

## Turn chat session into dash

*Jamie Davidson · `Ai` `Dashboards`*

Some early working on turning AI threads into quick dashboards for sharing the analysis in different ways.

<Frame>
  <iframe />
</Frame>


# November 21, 2025
Source: https://docs.omni.co/demos/2025/20251121

Tons of New AI (Modeling, Visualization, User Attributes), Dynamic Top N, Pull Request Required Dashboards, Azure, and More!!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby Learns to Model

*Steven Talbot · `Ai` `Modeling`*

We're teaching Blobby to model. Now you can build topics on the fly in AI, add relationships, or just generally do whatever you need from a modeling standpoint. Amazing for getting started or just supplementing the current model.

<Frame>
  <iframe />
</Frame>

## Blobby learns mustache (and who you are)

*Gustav Staprans · `Ai`*

Blobby now knows *you* - great for lots of analyses (show me my pipeline, my customers, my usage, etc). This also means you can use mustache dynamically in AI context to pass user-specific information.

<Frame>
  <iframe />
</Frame>

## Blobby learns visualization

*Jamie Davidson · `Ai` `Visualization`*

We're teaching Blobby more skills. Soon Blobby will be able to edit the fullness of the visualization spec - add labels, change axes, chart types, colors - anything you can do in the UI. Bit more to do here, but no more UI for building unless you want it.

<Frame>
  <iframe />
</Frame>

## Snowflake fuzzy search (for AI)

*Chris Merrick · `Ai` `Snowflake`*

We're playing around with new techniques to improve the AI experience. Here we use Snowflake Cortex to build a fuzzy search index for easier topical lookups. This would open up more natural filtering behaviors for lots of use cases (like support tickets in the demo).

<Frame>
  <iframe />
</Frame>

## Dynamic groups (top N, etc)

*TJ Banghart · `Workbook`*

Now you can create completely dynamic groups even based on associated metrics (ie. top 10 by count + other).

<Frame>
  <iframe />
</Frame>

## Pull request required dashboard changes

*Mariel Freyre · `Dashboards` `Administration` `Coming Soon`*

For many use cases you want complete review on dashboard changes. Now you can enforce branch-based changes through git for specific dashboards.

<Frame>
  <iframe />
</Frame>

## Omni in Azure

*Brian Frantz · `Azure` `Administration` `Multi-cloud`*

Our first demo of running queries in Azure. More work to do but Omni is going multi-cloud.

<Frame>
  <iframe />
</Frame>

## Renderer in Azure

*Jonathan Swenson · `Azure` `Administration` `Scheduler` `Multi-cloud`*

More Azure progress, this time on the renderer.

<Frame>
  <iframe />
</Frame>

## More dashboard containers

*Luke Bowerman · `Dashboards`*

Continuing all the progress on dashboard containers, we go through an end-to-end example of a complex dashboard layout.

<Frame>
  <iframe />
</Frame>

## Workbook field building improvements

*TJ Banghart · `Workbook` `Modeling`*

Tuning up the experience vis-a-vis workbook models and topic scoped models to give you all the control you need.

<Frame>
  <iframe />
</Frame>

## Model ignore improvements in branches

*Conrad Slimmer · `Modeling`*

Spending a bit of time buffing out a rough edge around removing ignore in branches.

<Frame>
  <iframe />
</Frame>

## Solution engineering AI (internal)

*Liam McCarthy · `Internal`*

A demo of some new internal tooling to help solutions engineers understand how we talk about different topics in the field.

<Frame>
  <iframe />
</Frame>


# December 1, 2025
Source: https://docs.omni.co/demos/2025/20251201

Blobby Learns to Search Google Drive, Tons of AI (Vis, Calcs, IDE), More Dash Containers, ADBC, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby Learns to Search Google Drive

*Chris Merrick · `Ai`*

Blobby has been studying hard. Now you can connect Omni to Google Drive and search files outside Omni directly from Blobby. This lays the groundwork for bringing AI context from completely outside the system into an analysis, or even just asking quick questions from inside the AI window. Excited to see how folks use this one.

<Frame>
  <iframe />
</Frame>

## Blobby smart visualization almost launch

*Jamie Davidson · `Ai` `Visualization`*

Smart vis building from AI coming soon. A final demo of the query, interpret, visualize workflow for building better vis or hand tuning via AI.

<Frame>
  <iframe />
</Frame>

## Blobby learns XLOOKUP

*Steven Talbot · `Ai`*

Ever expanding Blobby's capability. Now you can chain together pairs of independent queries through lookups to bring time-series next to each other or other ad hoc use cases.

<Frame>
  <iframe />
</Frame>

## Blobby learns requery

*Steven Talbot · `Ai`*

Another new skill for Blobby. Now you can requery previous queries through intermediate query views. Useful for regrouped aggregates, or other types of more complex analyses. Still some work to do on engaging when to use all these new techniques.'

<Frame>
  <iframe />
</Frame>

## Claude Code project manager (internal)

*Steven Talbot · `Ai` `Internal`*

Steven shows off a new project management tool he built to manage Claude Code and keep the robots on task.

<Frame>
  <iframe />
</Frame>

## Model IDE smart autocomplete

*Richard Czechowski · `Ai` `Modeling`*

An early look at some work to layer intelligent auto-completion (think cursor) into the model development experience.

<Frame>
  <iframe />
</Frame>

## AI calculation functions

*Richard Czechowski · `Ai` `Calculations`*

This is a new idea to open up AI functions to our calculation language using the AI native functions in the data warehouse (think Snowflake Cortex or Databricks AI Functions or BigQuery AI functions). This opens up on-the-fly classification or summary, lots of great use cases, but bit more work to do to launch.

<Frame>
  <iframe />
</Frame>

## Vibe coding AI context

*Liam McCarthy · `Ai` `Use Cases` `Modeling`*

Demo of a new technique for developing AI context and getting better results from Blobby using Cursor.Docs here for more: [https://community.omni.co/t/using-omni-local-model-editor-to-vibe-code-ai-context/427](https://community.omni.co/t/using-omni-local-model-editor-to-vibe-code-ai-context/427)

<Frame>
  <iframe />
</Frame>

## Dashboard Tabs v0

*Luke Bowerman · `Dashboards`*

The containers work isn't just about single-page layout, it's laying the ground work for native tabbed dashboards. Luke previews a first look at the editor experience for tabs.

<Frame>
  <iframe />
</Frame>

## Dashboard container layout work

*Meredith Dodge · `Dashboards`*

Still chugging along on dashboard containers. Here's a first look at the new layout controls and experience for builders.

<Frame>
  <iframe />
</Frame>

## Export solo spreadsheet tabs

*Richard Czechowski · `Spreadsheets` `Export`*

Now you can export individual spreadsheet tabs from the dashboard, we'll take care of the query dependencies.

<Frame>
  <iframe />
</Frame>

## Azure downloads

*Jonathan Swenson · `Azure` `Export`*

Continuing the work on lifting Omni into Azure - a quick demo of downloads in the new stack.

<Frame>
  <iframe />
</Frame>

## ADBC

*Jonathan Swenson · `Performance`*

We're testing Arrow for connectivity to the data warehouse (rather than JDBC). The result is massive speed-ups over large result sets, and even some small ones over tiny datasets. Still exploring, but hopeful this can make Omni even faster for everyone.

<Frame>
  <iframe />
</Frame>

## All tables in workbooks to get started

*Richard Czechowski · `Workbook`*

Before models get built, finding what you need was too hard. We're making that set-up process easier to get started with Omni.

<Frame>
  <iframe />
</Frame>


# December 5, 2025
Source: https://docs.omni.co/demos/2025/20251205

Tabbed Dash Beta, Per User AI, Lots More AI, Ridiculously Performant Giant Vis, Pie Rebuild Almost Launch, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Tabbed dashboards v1 (ask us)

*Luke Bowerman · `Dashboards`*

Dashboard tabs and containers are getting close to GA. For the cutting edge folks, we're open to turning this on (there may be bumps). But enormous amount of new dashboard functionality coming soon. Here we demo filters above and below tabs, the tab building experience, and more. Ask us if you want to get in early (it is all or nothing though, so fair warning).

<Frame>
  <iframe />
</Frame>

## Per user AI permissions

*Trip Tate · `Ai` `Administration` `Dashboards`*

Now you can granularly control who has access to Blobby. This means everyone can start testing AI as conservatively as they want. Can't emphasize enough how transformative it has been for us internally. Go try it!

<Frame>
  <iframe />
</Frame>

## Claude Code Uses Omni

*Gustav Staprans · `Ai`*

We're playing around with workflows to automate anything you can imagine in app with AI. Here we have Claude Code change the AI icon by navigating the core UI. Lots to do here, but would love to hear about use cases folks are imagining.

<Frame>
  <iframe />
</Frame>

## Sharing AI sessions (with anyone who has permission)

*Steven Talbot · `Ai`*

We extended AI link sharing to everyone in the system with permissions. User attributes, data permissions, etc are all respected here, but now for users with similar permissions AI links can be easily passed around (safely!!).

<Frame>
  <iframe />
</Frame>

## AI in Azure

*Jonathan Swenson · `Ai` `Azure`*

Blobby lives in Microsoft. Continuing the build out of Omni's multi-cloud offering, now AI is up and running.

<Frame>
  <iframe />
</Frame>

## Deep research UX improvements

*Gustav Staprans · `Ai`*

We're tuning up the UX for deep research to give Blobby plenty of space to explore without burying the important outcomes.

<Frame>
  <iframe />
</Frame>

## Ludacris vis launch (huge perf win)

*Nate Agrin · `Visualization` `Performance`*

Our huge rebuild of the vis render experience is close. We're waiting on a core Firefox bug we discovered building this, but the outcome is enormous (think 50k, 100k, 500k point visualizations) now render and resize smoothly.

<Frame>
  <iframe />
</Frame>

## Pie rebuild almost launch (smart labels)

*Rob Miller · `Visualization`*

We're getting close on our pie chart rebuild. Big wins with smart labeling and more features coming.

<Frame>
  <iframe />
</Frame>

## Stacked measures, simple totals

*Nate Agrin · `Visualization`*

Getting close to the finale on merging stacked measures with color-by charts for config. Now simple totals are easy on stacked measure charts.

<Frame>
  <iframe />
</Frame>

## Level of detail fields with filter escaping

*TJ Banghart · `Workbook` `Modeling`*

Level of detail fields are a huge unlock for comparing to overall populations or sub-populations and now you can also take advantage of filter escaping or inclusion dynamically (think compare a row to the top 10 without filters, etc).

<Frame>
  <iframe />
</Frame>

## Scheduler error debugger

*Corey Ruderman · `Scheduler` `Export` `Administration`*

We're continuing to make it easier to DIY debugging scheduler hiccups like query errors or delivery blockages.

<Frame>
  <iframe />
</Frame>

## Clearing single select filters

*Steven Talbot · `Dashboards` `Claude`*

Claude wanted to get in on the demos. Here's a bit of work to clean up clearing single-select filters.

<Frame>
  <iframe />
</Frame>


# December 12, 2025
Source: https://docs.omni.co/demos/2025/20251212

Dashboard tabs, request access, filter layout, zoom, drag rebuild, complex filters, custom emojis, and 22 total demos.

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Tab UX designer

*Luke Bowerman · `Dashboards`*

A first look at the beautiful new tab designer experience. We don't just want to land tabs, we want to make them designable and pretty.

<Frame>
  <iframe />
</Frame>

## Make sure to save SQL and multi invite to dashboards

*Luke Bowerman · `Sql` `Content Management` `Administration`*

A pair of demos. First a quick warning when you try to save un-run SQL to make sure it's not dropped from that pending state. The second is a tweak to allow sharing dashboards quickly with a comma delimited list for faster bulk workflows.

<Frame>
  <iframe />
</Frame>

## Dashboard request access

*Trip Tate · `Dashboards` `Administration`*

No more dead dashboard pages, now users can explicit request access (with associated email) and documents have a pending requests page for management.

<Frame>
  <iframe />
</Frame>

## Dashboard resize / layout engine overhaul (early preview)

*Meredith Dodge · `Dashboards`*

We're completely rebuilding the drag and layout controls for dashboards to make it way better to work with. Here's an early look at all that work and what it unlocks for dashboard builders.

<Frame>
  <iframe />
</Frame>

## Dashboard layout undo (early preview)

*Luke Bowerman · `Dashboards`*

A first look at some future work to allow undo / redo on dashboard layout.

<Frame>
  <iframe />
</Frame>

## Dashboard tags UX improvement

*Luke Bowerman · `Content Management` `Ux`*

A quick tweak to make sure long lists of tags still look great.

<Frame>
  <iframe />
</Frame>

## New pie almost launch

*Rob Miller · `Visualization`*

Getting close to launching the new pie - now with percentage calculations, optional totals, and much better labeling.

<Frame>
  <iframe />
</Frame>

## Bulk query canceling

*Jonathan Swenson · `Administration`*

Now you can select some or all of the running queries in Omni for fast cancelation.

<Frame>
  <iframe />
</Frame>

## Scheduler in Azure

*Jonathan Swenson · `Administration` `Scheduler` `Azure`*

More progress on lifting the full app into Azure. Here we demo the scheduler experience.

<Frame>
  <iframe />
</Frame>

## Native field masking

*Conrad Slimmer · `Modeling` `Administration`*

You could already mask fields via custom SQL but we're building some native gestures to make it easier to build and manage.

<Frame>
  <iframe />
</Frame>

## Snowflake semantic view builder

*Peter Whitehead · `Snowflake` `Modeling`*

Now you can push your Omni model backwards into Snowflake Semantic Views for usage completely outside the Omni platform.

<Frame>
  <iframe />
</Frame>

## Feature flag UX fix (internal)

*Luke Bowerman · `Internal`*

A quick internal demo for finding and managing feature flags.

<Frame>
  <iframe />
</Frame>

## Dashboard zoom in / out

*Meredith Dodge · `Dashboards`*

The dashboard now supports % zoom for earlier layout control, resizing, and for view context more easily when using AI or building filters.

<Frame>
  <iframe />
</Frame>

## Pull request required for dashboard publish

*Mariel Freyre*

We tuned up the experience for branch-attached-drafts

<Frame>
  <iframe />
</Frame>

## Filter resizing and layout

*James Bueche · `Dashboards`*

Soon you'll have complete control over filter positions and sizing - this opens up a bunch of new, functional UX for dashboard builders.

<Frame>
  <iframe />
</Frame>

## Drag to organize dashboards

*Mariel Freyre · `Content Management`*

A nice UX improvement to allow dragging dashboards into folders in the content system.

<Frame>
  <iframe />
</Frame>

## UX polish grab bag

*Jared Hardy · `Workbook` `Sql` `Modeling`*

A four pack of UX improvements - making sure measure groups unfurl on search; better SQL auto-complete; code folding in the IDE; and better behavior on formatting / unformatting in the markdown editor.

<Frame>
  <iframe />
</Frame>

## New download APIs

*Corey Ruderman · `Api` `Export`*

We launched a handful of new APIs for kicking off and polling downloads for all the app builders out there.

<Frame>
  <iframe />
</Frame>

## Custom emojis

*Luke Bowerman · `Fun`*

We wanted to spice up the app a bit, so bringing custom Blobbys to the core app. This also starts putting in the groundwork for BYO emojis natively in Omni.

<Frame>
  <iframe />
</Frame>

## Styled bar chart table

*Sarah Waterson*

A quick new visualization for tabular bar charts with detail.

<Frame>
  <iframe />
</Frame>

## Compound / complex filters

*Steven Talbot · `Workbook`*

Now you can create complex filters that span across multi-fields. Also opens up these use cases nicely for AI + tuning.

<Frame>
  <iframe />
</Frame>

## Teaching Blobby to do better math

*Steven Talbot · `Ai`*

We all know LLMs can be prone to vibe-math (ahem, r's in strawberry). So we're building new tools to make sure when Blobby is doing math, it has the tools it needs to be precise.

<Frame>
  <iframe />
</Frame>


# December 19, 2025
Source: https://docs.omni.co/demos/2025/20251219

BYOLLM, AI Slash Commands, SQL Totals, Duration Fields, Tabs Beta, Query Snowflake Semantic Views, and So Much More (22 Videos!)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby Learns New LLMs (BYOLLM)

*Gustav Staprans · `Ai` `Administration`*

Blobby didn't want Claude to have all the fun. Soon we'll open up different LLM providers ChatGPT, Gemini, BYO. Will make sure there are admin controls here of course for folks that want it.

<Frame>
  <iframe />
</Frame>

## AI slash commands

*Jamie Davidson · `Ai`*

Blobby has all sorts of skills - agentic querying, visualization, summarization, field building, calculation. We wanted to provide power users a way to direct to these different tools explicitly.

<Frame>
  <iframe />
</Frame>

## Deep thinking UX improvements

*Gustav Staprans · `Ai`*

We tuned up with streaming chat experience to hide the less important while still showing the full train of thought when you need it.

<Frame>
  <iframe />
</Frame>

## Blobby voice app

*Will Savage · `Ai` `Use Case` `Vibe Coding`*

A quick DIY project to open up voice with Blobby. Early days, but helps open up the imagination for what's possible.

<Frame>
  <iframe />
</Frame>

## SQL totals

*Steven Talbot · `Sql` `Workbook`*

Bringing the front-end totals experience to SQL queries (think simple sum, count, average, etc down a column)

<Frame>
  <iframe />
</Frame>

## Duration fields

*TJ Banghart · `Workbook` `Modeling`*

It's now a couple click to build duration fields in the UI (of course with model pushdown when needed).

<Frame>
  <iframe />
</Frame>

## Range calc pushdown

*TJ Banghart · `Workbook` `Calcs` `Modeling`*

Now full range calculations - think SUM(B:B), AVERAGE(C:C), etc - can be pushed down using LOD fields. This makes comparison fields trivial to build in the UI but manage like robust data model when you need it.

<Frame>
  <iframe />
</Frame>

## Top N filter escaping

*TJ Banghart · `Workbook` `Modeling`*

Some new toggles with Top N to ignore / include filters for comparison to the population at large or not.

<Frame>
  <iframe />
</Frame>

## Tabs beta launch

*Luke Bowerman · `Dashboards`*

A nice end-to-end demo of the new tabs (pages) experience for dashboards. Beta out now, let us know if you want activated.

<Frame>
  <iframe />
</Frame>

## Cross-filtering very alpha

*Steven Talbot · `Dashboards`*

A first look at playing around with cross-filterable dashboards. We have some UX to consider around native filters vs cross-filters and what we want to allow. Would love feedback on whether these should be 'different' vs dovetailing into the native filter experience.

<Frame>
  <iframe />
</Frame>

## Bulk dashboard filter mapping

*Alisa Tatarinova · `Dashboards`*

Sometimes you just want to map a filter to 40 tiles at once. We're leaving in the in-line UX but now offering a bulk mapping experience alongside.

<Frame>
  <iframe />
</Frame>

## Field picker views in use

*Luke Bowerman · `Workbook`*

Now you can quickly toggle between the specific fields in use or the views in use - most helpful in gigantic topics or all views and fields.

<Frame>
  <iframe />
</Frame>

## Workbook tab organization

*Luke Bowerman · `Workbook`*

We made it simple to organize workbook tabs by type, name, etc (tell us anything else you want to see here).

<Frame>
  <iframe />
</Frame>

## New dashboard building UX designs

*Luke Bowerman, Jared Hardy · `Dashboards`*

Some new designs were building towards for complex multi-tab dashboards.

<Frame>
  <iframe />
</Frame>

## Easier topic groups

*Alisa Tatarinova · `Workbook` `Modeling`*

We built a front-end UX around organizing topics into groups with auto-complete, etc for a nicer experience.

<Frame>
  <iframe />
</Frame>

## Querying Snowflake semantic views directly

*Buck Ryan*

Now you can query Snowflake semantic views directly in Omni. This means we now have translators back and forth for more native experience, but also have rounded out querying them directly too.

<Frame>
  <iframe />
</Frame>

## Blobby avatars

*Alisa Tatarinova · `Fun`*

For the Blobby lovers out there, now you can build your own avatar using our custom Blobby builder.

<Frame>
  <iframe />
</Frame>

## Native Sankey charts

*Rob Miller · `Visualization`*

Continue to build out more native vis. Here we have an early look at Sankey charts.

<Frame>
  <iframe />
</Frame>

## Streaming queries page live view

*Jonathan Swenson · `Administration`*

Now the queries page will live update so you can actively track and manage database usage from Omni (for one minute - we don't want these pages polling forever).

<Frame>
  <iframe />
</Frame>

## dbt in Azure

*Jonathan Swenson · `Azure` `Dbt`*

The dbt integration is now up and running in Azure as well - more progress getting the full app available in Azure.

<Frame>
  <iframe />
</Frame>

## Smarter aggregate awareness table picking

*Steven Talbot · `Modeling`*

We're making the heuristics for choosing the right aggregate better to make sure queries get faster for end users.

<Frame>
  <iframe />
</Frame>

## New docs development (mostly internal)

*Erin Cochran · `Doc` `Internal`*

We're continuing to tune up the new docs experience

<Frame>
  <iframe />
</Frame>


# 2025 Demos
Source: https://docs.omni.co/demos/2025/index

Browse all 2025 Omni product demo videos covering AI agents, MCP, spreadsheets, custom permissions, dashboards, and more.

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.
</Note>

* [December 19, 2025](/demos/2025/20251219): BYOLLM, AI Slash Commands, SQL Totals, Duration Fields, Tabs Beta, Query Snowflake Semantic Views, and So Much More (22 Videos!)
* [December 12, 2025](/demos/2025/20251212): Dashboard tabs, request access, filter layout, zoom, drag rebuild, complex filters, custom emojis, and 22 total demos.
* [December 5, 2025](/demos/2025/20251205): Tabbed Dash Beta, Per User AI, Lots More AI, Ridiculously Performant Giant Vis, Pie Rebuild Almost Launch, and More
* [December 1, 2025](/demos/2025/20251201): Blobby Learns to Search Google Drive, Tons of AI (Vis, Calcs, IDE), More Dash Containers, ADBC, and More
* [November 21, 2025](/demos/2025/20251121): Tons of New AI (Modeling, Visualization, User Attributes), Dynamic Top N, Pull Request Required Dashboards, Azure, and More!!
* [November 14, 2025](/demos/2025/20251114): Dashboard View As, Dashboard Summary AI Getting Close, New Docs, Better Query Killing and More
* [November 7, 2025](/demos/2025/20251107): Stacked Bar Sorting, Deep Research Launch, Topic Scoped Fields in the UI, Lots of Performance Work and More
* [October 31, 2025](/demos/2025/20251031): Tons of Dashboard Work (AI Summaries, Custom Errors, Localization, and More), More Cubes, and Getting Close on Custom Permissions
* [October 24, 2025](/demos/2025/20251024): Tons of Dashboard Work, More AI, Better Conditional Formatting, and More
* [October 17, 2025](/demos/2025/20251017): AI Workflows, ERD Diagrams, CSS Previews, New Filter UX, and More Blobbies Than You Can Handle
* [October 10, 2025](/demos/2025/20251010): Docs in the IDE, Cube Building, Lots of AI, External Model Dev Launch, dbt Metrics, Spreadsheet Export, and More
* [October 3, 2025](/demos/2025/20251003): External Development IDE, Lots of Blobby, Moving Dashboard Filters, Localization, SQL Preamble, and 15 (!!!) More
* [September 26, 2025](/demos/2025/20250926): Fast Rendering of Giant Visualizations, New Schema Model Navigation, Mapping Result GeoJSON, and More
* [September 19, 2025](/demos/2025/20250919): dbt Semantic Layer, MCP OAuth, Model Blame, AI Session URLs, Huge Performance Wins for Vis, and 11 More!
* [September 12, 2025](/demos/2025/20250912): A New User Attribute Debugger UI, MCP Oauth, Vis Reaggregation Alpha, and More
* [September 5, 2025](/demos/2025/20250905): Custom Permissions, YAML Editor Guest Demo, Independent Chart Stacking Controls, and More Quality of Life
* [August 29, 2025](/demos/2025/20250829): AI Session Saving, IDE Folders, New SQL Experience, and Lots More
* [August 22, 2025](/demos/2025/20250822): Dynamic Dashboard Spreadsheets, Spreadsheet Drill, Google Sheets Export, and lots of Blobby (Dashboard AI, Smart Filters, and Dash Search)
* [August 15, 2025](/demos/2025/20250815): Blobby Learns Filtered Measures, Bunch of API (Including A+ Docs), New SQL Mode, Databricks Metrics Views, and Tons of Quality of Life Work
* [August 8, 2025](/demos/2025/20250808): Blobby Builds a Dashboard, More AI Everywhere, Snowflake Semantic Layer Sync, Top N + Other, and More
* [August 1, 2025](/demos/2025/20250801): dbt Exposures, New Embed Demo, Guest Learning Microsite, Dashboard Summarization, and More
* [July 25, 2025](/demos/2025/20250725): A big pile of your most requested features this week!
* [July 18, 2025](/demos/2025/20250718): Agent Blobby, Dashboard AI, Embedded AI Guest Demo, Topic Builder UI, Global Cache Busting Button, Plus Lots of Vis
* [July 11, 2025](/demos/2025/20250711): DB OAuth Passthrough (soon), Lots of Spreadsheets, Unlimited Excel Downloads, More Better Vis, Embed Error Eventing, and More
* [July 3, 2025](/demos/2025/20250703): Fill Gaps in Any Date Series, More AI Auto-Modeling, More Model Permissions, and More
* [June 27, 2025](/demos/2025/20250627): Automated Data Modeling from AI Sessions, Instant Dashboard Filters, Unlimited Paginated Data Tables, Unfurled Tables in Schedules, and 15 More!
* [June 20, 2025](/demos/2025/20250620): EAV Modeling, AI with Subqueries, Paginated PDFs, Trellis Soon, MCP Soon, and Lots More
* [June 13, 2025](/demos/2025/20250613): Omni MCP Getting Close, AI Summary Vis, Trellis Charts, Faster Workbooks, Custom Blobby, and More
* [June 6, 2025](/demos/2025/20250606): Omni MCP 1.0, Spreadsheets Getting Closer to Release, New Model Debug Modes, Markdown Vis AI, and More
* [May 30, 2025](/demos/2025/20250530): dbt Tests in AI Context, Blobby Chrome Extension, Workbook Quick Starts, Embed Folder Naming, Performance Work, and More
* [May 23, 2025](/demos/2025/20250523): AI Field Creation, AI MCP v0, Streaming AI Results, Level of Detail Calculation, Lots of Dashboard Improvements, and More
* [May 16, 2025](/demos/2025/20250516): Embedded AI, Tiny Grid Dashboard Launch, More AI (Chart Config, Field Descriptions), Or Access Grants, Complex Date Filters, and More
* [May 9, 2025](/demos/2025/20250509): Blobby Mobile, An AI Demo on Our Actual Data, Front End Topic Building, API Mini Apps, Scheduler APIs, and Much More
* [May 2, 2025](/demos/2025/20250502): More AI (Ai Mode Launch, New Slackbot), Custom Embed Nav, More API, and Handful of New Custom Vis
* [April 25, 2025](/demos/2025/20250425): AI Mode + More AI, dbt Description Push Down, IDE Search, Table Styling and More
* [April 18, 2025](/demos/2025/20250418): Lots of Mini Apps, Better IDE Search, Multi-tab Spreadsheets, Topic and View Visual Editor, More AI and More
* [April 11, 2025](/demos/2025/20250411): Dynamic Model Layers, Embed Nav Builder, Better AI Retry, and More Analytics
* [April 4, 2025](/demos/2025/20250404): Filter on Calcs, AI Retry, AI Evals, Query View UX, Google Sheets Export, and Much More
* [March 28, 2025](/demos/2025/20250328): AI Progress Everywhere (Field Context, AI API, Training Docs), New DB Throttling Controls, Content in Branches, and More
* [March 21, 2025](/demos/2025/20250321): New Filter Controls, Dataset Builders, Lots of Custom Vis, and Plenty More
* [March 14, 2025](/demos/2025/20250314): Guest Vis Demo, Editing Vis from the Dashboard, CSV Upload Edit Workflows, a Slack Emoji App, and More
* [March 7, 2025](/demos/2025/20250307): Docs AI, Editing Visualizations Directly on the Dashboard, Unlimited Schedules and Downloads, dbt Environment Clean-up and More
* [February 28, 2025](/demos/2025/20250228): Lots of CSV Upload and Spreadsheets, Heatmaps, Color Promotion, and Lots More
* [February 21, 2025](/demos/2025/20250221): CSVs in the Data Warehouse (and Editable in a Spreadsheet!), Chart Color Promotion, and 13 More Demos
* [February 14, 2025](/demos/2025/20250214): CSV Upload Soft Launch, Instant Filters, More Color Work, Better Chart Labels, and More
* [February 6, 2025](/demos/2025/20250206): AI Filters, Dashboard Performance Reports, Clear Time Filters, Per-User Attributes Page, Our First Spreadsheet App, and More
* [January 31, 2025](/demos/2025/20250131): Smart Labels, Editing Vis from the Dashboard, AI Chart Building, Cache Busting API, and More
* [January 24, 2025](/demos/2025/20250124): CSV Upload (Preview), AI Summary Tiles, Advanced Vis UI Builder, Embed URL Sharing, and More
* [January 17, 2025](/demos/2025/20250117): Lots of API, Vis Series Coloring, AI Query Summary, Model Usage Analytics, and Lots of Polish and Pretty Vis
* [January 10, 2025](/demos/2025/20250110): Snowflake Cortex Columns, Sub-Folders (Early), Editing dbt Models, and Much More
* [January 3, 2025](/demos/2025/20250103): Bunch of AI Improvements, More/Better Usage Data, Concurrency Improvements, and More


# January 2, 2026
Source: https://docs.omni.co/demos/2026/20260102

Slackbot v0, Field Picker Multi-Level Nesting, Tons of Perf, SQL Ai Field Suggestions, Google Drive in Blobby (25 Demos to Start 2026)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Slackbot v0

*Corey Ruderman · `Ai` `Slack`*

A first look at bringing Blobby to a native Slack app.

<Frame>
  <iframe />
</Frame>

## Field picker multi-level nesting

*Luke Bowerman · `Workbook` `Modeling`*

Now your field picker can nest as deeply as you like. For the organizers you can build custom group levels for navigating the field picker more easily.

<Frame>
  <iframe />
</Frame>

## Filter suggestion search improvement

*Steven Talbot · `Dashboards` `Workbook`*

We made filter suggestion better - prioritizing starts with, then spaces before search terms, and then any match.

<Frame>
  <iframe />
</Frame>

## Recent activity sidebar

*Trip Tate · `Ux` `Dashboards` `Workbook`*

A new UX to quickly navigate to any recent analyses or dashboards. Making it easier to find everything you've just been working on or looking at.

<Frame>
  <iframe />
</Frame>

## SQL AI model suggestions

*Trip Tate · `Sql` `Ai` `Modeling`*

A first look at some new AI powered UX to extract modelable fields from your SQL. Can get out of your way when you don't need it, but also quickly provide a workflow to make sure you aren't ever doing the same work twice.

<Frame>
  <iframe />
</Frame>

## Google Drive in Blobby

*Chris Merrick · `Ai` `Google Drive`*

Blobby keeps getting smarter. Now you can authenticate yourself into Google Drive and search internal documents for relevant questions inside Blobby.

<Frame>
  <iframe />
</Frame>

## Fixing linked tab deliveries

*Jonathan Swenson · `Dashboards` `Scheduler`*

Bit of work to tune up the scheduler for linked tabs (recently released ability to duplicate-and-link tabs).

<Frame>
  <iframe />
</Frame>

## Dashboard share emails

*Trip Tate · `Dashboards`*

Now users can get alerted when dashboards are shared.

<Frame>
  <iframe />
</Frame>

## Container layout alignment

*Meredith Dodge · `Dashboards`*

Work on new dashboard containers continues - bunch of work here around layout and organizing inside containers.

<Frame>
  <iframe />
</Frame>

## Preventing duplicate suggestion queries

*Jonathan Swenson · `Performance`*

Some work here to make sure query killing is effective with filter suggestions, which can fire off several queries as the user types.

<Frame>
  <iframe />
</Frame>

## Create branch from branch (branch forking)

*Steven Talbot · `Modeling`*

Now you can build a new branch from an existing branch to fork and test for more complex build outs.

<Frame>
  <iframe />
</Frame>

## Oracle dialect support

*TJ Banghart · `Administration` `Oracle`*

New support for Oracle data

<Frame>
  <iframe />
</Frame>

## Vis with order\_by\_field

*Nate Agrin · `Visualization`*

Now vis will properly account for order\_by\_fields, making sure months stay in order, tiers are respected, etc.

<Frame>
  <iframe />
</Frame>

## String vis data labels

*Nate Agrin · `Visualization`*

Some improvements to make sure labels with stringified fields work properly - opening nice custom labeling patterns with IF() and TEXT()

<Frame>
  <iframe />
</Frame>

## Smooth regression improvements

*Nate Agrin · `Visualization`*

Bit of work to make sure regressions label smoothly ;)

<Frame>
  <iframe />
</Frame>

## Safari vanity embed - skip logo screen

*Nate Agrin · `Embed` `Safari`*

When loading vanity domains in Safari you can now skip the logo spinner screen entirely.

<Frame>
  <iframe />
</Frame>

## Safari embed update to removes logo spinner

*Nate Agrin · `Embed` `Sahari`*

Subtle change to Safari embed to drop the Omni logo on cookie accept modal.

<Frame>
  <iframe />
</Frame>

## Faster folder & dashboard loading

*Trey Shugart · `Performance` `Content Management`*

Bit of silent work to make folder navigation and finding the dashboard you need faster.

<Frame>
  <iframe />
</Frame>

## Workbook PDF and PNG export

*Corey Ruderman · `Workbook`*

A quick add to bring the PDF and PNG export experience to workbooks from dashboards.

<Frame>
  <iframe />
</Frame>

## Eliminating double query planning

*Jonathan Swenson · `Performance`*

More behind the scenes perf work.

<Frame>
  <iframe />
</Frame>

## Troubleshooting Java container memory outages

*Jonathan Swenson · `Performance`*

Bunch of work to improve performance and app stability, and a deep dive on the investigation.

<Frame>
  <iframe />
</Frame>

## New guides in docs

*Erin Cochran · `Docs`*

We're adding a new guides section to docs for deep dives into full end-to-end workflows in Omni. Plus a quick look at how we write docs internally.

<Frame>
  <iframe />
</Frame>

## Internal - Claude Code tooling improvements

*Nate Agrin · `Internal` `Ai`*

We continue to improve internal AI development workflows to make sure we can ship more product.

<Frame>
  <iframe />
</Frame>

## Internal - Slackbot CLI

*Luke Bowerman · `Internal` `Engineering`*

Bit of new internal tooling to make sure we can track the development process better.

<Frame>
  <iframe />
</Frame>

## Internal - CLI improvements

*Luke Bowerman · `Internal` `Engineering`*

A discussion of some new internal improvements to CLI

<Frame>
  <iframe />
</Frame>


# January 9, 2026
Source: https://docs.omni.co/demos/2026/20260109

Tons of AI (BYO LLM, Model Debugger, KPI Vis, Cron), and 23 Other Demos (Lots of Quality of Life)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## BYO AI LLM

*Gustav Staprans · `Ai` `Coming Soon`*

Soon you'll be able to officially bring your own LLMs to Omni, starting with ChatGPT and Claude alongside our native Bedrock. More models to come.

<Frame>
  <iframe />
</Frame>

## AI - What did Blobby build debugger

*Jamie Davidson · `Ai`*

Now you can see exactly what Blobby did on each query - clearly showing calcs, new fields, etc without drilling to the workbook page.

<Frame>
  <iframe />
</Frame>

## AI KPI vis

*Jamie Davidson · `Ai` `Visualization`*

Now Blobby can build KPI visualizations alongside the cartesian plots and pie charts available today.

<Frame>
  <iframe />
</Frame>

## AI automated model suggestions

*Jamie Davidson · `Ai` `Modeling`*

Now Blobby will build a list of model suggestions in AI sessions as you go, so the model can be refined with improvements built through end-user sessions.

<Frame>
  <iframe />
</Frame>

## AI cron scheduling

*Corey Ruderman · `Ai` `Scheduler`*

More driving smart AI enablers into every action in the app. Now you can build custom scheduler timings using LLMs to build nuanced cron schedules.

<Frame>
  <iframe />
</Frame>

## AI Figma templates (internal)

*Jared Hardy · `Ai` `Internal`*

Some internal facing work to quickly spin up Figma mocks using the core app (plus a little AI of course).

<Frame>
  <iframe />
</Frame>

## Blobby learns to tell you about the data model

*Steven Talbot · `Ai` `Modeling`*

Blobby has a new skill - now you can ask about model concepts in the AI experience, asking about how fields are defined, what is in the model, etc.

<Frame>
  <iframe />
</Frame>

## Table copying to CSV or Markdown

*Nate Agrin · `Visualization` `Export`*

Few new quick features for grabbing data quickly out of data tables (tables, columns, rows).

<Frame>
  <iframe />
</Frame>

## Quality of life grab bag (themes, tab names)

*Luke Bowerman · `Workbook` `Dashboards`*

A few new pieces of work to clean up the tab renaming experience and theme swapping.

<Frame>
  <iframe />
</Frame>

## Single select dates on dashboard (alpha)

*Steven Talbot · `Dashboards`*

Some early work on tweaking the dashboard UX for filters - here limiting the date picker to just the calendar single-select.

<Frame>
  <iframe />
</Frame>

## Modeling improvements (dynamic schema inspector and topic naming)

*Steven Talbot · `Modeling` `Workbook`*

Couple changes to make sure topic building with custom names works better and be able to debug dynamic connections in the inspector.

<Frame>
  <iframe />
</Frame>

## PROPER() Function

*Steven Talbot · `Calcs` `Workbook`*

Added a new Excel function to enable text formatting with PROPER (ie. first-letter-capitalized)

<Frame>
  <iframe />
</Frame>

## Count yes, count no for booleans

*Steven Talbot · `Workbook`*

Couple new quick-fields for boolean dimensions - Count Yes and Count No.

<Frame>
  <iframe />
</Frame>

## More cross filtering alpha

*Steven Talbot · `Dashboards`*

Bit more work getting cross-filtering enabled for dashboards. Some design work to do here still.

<Frame>
  <iframe />
</Frame>

## Mixed series stacking

*Nate Agrin · `Visualization`*

The last piece of work underpinning our new vis pipeline - now you can build mixed stacked charts, including all the familiar UX around labels, series selection, etc.

<Frame>
  <iframe />
</Frame>

## Container dash styling work

*James Bueche · `Dashboards`*

More work to make sure container styling aligns well with the current dashboard experience.

<Frame>
  <iframe />
</Frame>

## Unlimited pivot downloads and exports

*Jonathan Swenson · `Export`*

Now you can kick out a billion pivoted rows if you really wanted to.

<Frame>
  <iframe />
</Frame>

## Export Delimiters

*Jonathan Swenson*

Now you can customize you table delimiters for exporting (ie tabs, line breaks).

<Frame>
  <iframe />
</Frame>

## Fantasy football styled super dash

*Max Smith · `Dashboards` `Use Cases`*

Max shows off a beautiful new styled dashboard for fantasy football analysis, using all the new bells and whistles.

<Frame>
  <iframe />
</Frame>

## Resize controls for cell viewer

* Mike Torosian · `Workbook`\*

Quick piece of work to allow resize on the cell viewer (UI for viewing a single cell as you navigate the table).

<Frame>
  <iframe />
</Frame>

## Go to definition from table

* Mike Torosian · `Modeling` `Workbook`\*

More quality of life work - here a quick link to the model for a given field from the table itself.

<Frame>
  <iframe />
</Frame>

## Dashboard cross model migrator tool

* Drea ✨ · `Dashboards` `Workflow` `Api`\*

A new dashboard migrator tool from our services team. This is for moving dashboards across model (ie. regional connections or staging / prod workflows).

<Frame>
  <iframe />
</Frame>

## Copy formats Excel paintbrush

*Jamie Davidson · `Workbook`*

Bringing one of your most requested features - now the paintbrush everyone loves in Excel is available in Omni. Copy value formats, orientation, or conditional formatting quickly across lots of columns.

<Frame>
  <iframe />
</Frame>


# January 16, 2026
Source: https://docs.omni.co/demos/2026/20260116

Lots More AI (Homepage AI, Multi-Vis), Sankey Launch, Multi-Fact Topics, Paginated Subtotals and Huge Bucket of QOL Work

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI on homepage

*Trip Tate · `Ai`*

We're making it easier to get to Blobby, plus some admin controls for folks who aren't quite ready.

<Frame>
  <iframe />
</Frame>

## Multi vis AI summary

*Gustav Staprans · `Ai`*

We tuned up the summary experience to even share grouplets of visualizations alongside summary text.

<Frame>
  <iframe />
</Frame>

## AI model inspector tool

*Steven Talbot · `Ai`*

More work on our Model Inspector tool for understanding the data model inside the AI experience. Plus a bonus internal demo of continuing to build out our Claude Code workflows.

<Frame>
  <iframe />
</Frame>

## Clearer tool calls for AI deep research

*Gustav Staprans · `Ai`*

We improved the UX to make tool calls (filter value checks, model calls, etc) more explicit in the UI, so users can understand everything Blobby is doing at query time.

<Frame>
  <iframe />
</Frame>

## Multi model MCP querying

*Gustav Staprans · `Ai`*

Now the MCP server can intelligently route queries between different models rather than locking to a single model.

<Frame>
  <iframe />
</Frame>

## Better chat debugger

*Joel Dodge · `Ai`*

Bit of work to see more detail on how fields are used in the AI experience from the chat UI.

<Frame>
  <iframe />
</Frame>

## Sankey Launch

*Rob Miller · `Visualization`*

Sankey charts are launching, now with color controls as well. Plus stick around to the end for a preview of the next set of vis work.

<Frame>
  <iframe />
</Frame>

## Request dash edit access

*Trip Tate · `Administration` `Dashboards`*

Building on our request access workflows - now viewers can request edit access for dashboard they want to tune as well.

<Frame>
  <iframe />
</Frame>

## OmniTopics (multi base view topics)

*TJ Banghart · `Modeling` `Workbook`*

A new multi-base-view topic in Omni. TJ gives a quick explainer of multi-fact entities and how you can now model them in Omni.

<Frame>
  <iframe />
</Frame>

## Filter only field fast view filters

*TJ Banghart · `Modeling`*

Now you can quickly point filter-only fields at the view itself for dynamically filtering a view with minimal modeling.

<Frame>
  <iframe />
</Frame>

## Oracle connector launch

*TJ Banghart · `Modeling` `Administration`*

The Oracle database connector is now in preview for folks.

<Frame>
  <iframe />
</Frame>

## Paginated subtotals

*Steven Talbot · `Workbook`*

Now you can page through infinite results inside the subtotal UX.

<Frame>
  <iframe />
</Frame>

## Dashboard position / layout debugger

*James Bueche · `Dashboards`*

We added some explicit position debugging UX with XY coordinates for precision tuning your dashboards.

<Frame>
  <iframe />
</Frame>

## Container padding controls

*Meredith Dodge · `Dashboards`*

Progress continues on new dashboards - now with more controls for layout and padding.

<Frame>
  <iframe />
</Frame>

## Workbook in use topics

*Luke Bowerman · `Workbook`*

Inside workbooks you can now quickly see topics in use across your other tabs for faster navigation.

<Frame>
  <iframe />
</Frame>

## View as UX improvements

*Luke Bowerman · `Dashboards` `Administration`*

Another customer-requested-this-week improvement so that when using view-as, there is additional email metadata for differentiating between different accounts or embed users.

<Frame>
  <iframe />
</Frame>

## Filter by user attribute UX improvements

*Steven Talbot · `Workbook` `Dashboards`*

Bit of quality of life work to pick from the list of user attributes rather than typing in the string exactly.

<Frame>
  <iframe />
</Frame>

## Recover favorite UX

*Luke Bowerman · `Content Management` `Ux`*

More quality of life work to quickly recover accidental unfavorites.

<Frame>
  <iframe />
</Frame>

## Better IDE state management

*Chris Swenson · `Modeling`*

Quality of life work in the IDE as well - here better state management navigating the IDE, like folding, edit/redo state, etc. Just making life more pleasant for developers.

<Frame>
  <iframe />
</Frame>

## AWS token renewal mini app (internal)

*Luke Bowerman · `Internal` `Developer Productivity`*

Our developers get some quality of life work as well - here a tool for renewing AWS tokens.

<Frame>
  <iframe />
</Frame>

## CI error debugging in Claude (internal)

*Gustav Staprans · `Internal` `Claude Code`*

Quick demo of some improvements to our internal tooling for Claude Code to workflow CI debugging.

<Frame>
  <iframe />
</Frame>

## Eng team weekly summary dash (internal AI use case example)

*Luke Bowerman · `Internal` `Use Cases`*

Luke shows off a quick workflow we built to stay up on engineering work weekly using dashboard summary to quickly understand recently shipped code.

<Frame>
  <iframe />
</Frame>


# January 23, 2026
Source: https://docs.omni.co/demos/2026/20260123

Selectable Table Cells, Dashboard Filter Buttons and Custom UX, Dashboard Tab Vanity URLs, and Plenty More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Table Cell Copying!!!

*Mariel Freyre · `Workbook` `Dashboards` `Tables`*

Now you get the full copy experience from our native data tables - highlight and copy cells trivially out of the front-end, including keyboard controls.

<Frame>
  <iframe />
</Frame>

## Dashboard filter UX controls

*Alisa Tatarinova · `Dashboards` `Filters`*

A first look at completely customizing the filter UX for dashboards - think buttons, selector lists, whatever you can imagine. Let us know what you'd like to see here.

<Frame>
  <iframe />
</Frame>

## Dashboard tab vanity URLs

*Luke Bowerman · `Dashboards`*

You could already permalink your dashboards with vanity URLs, now you can do the same with your tabs to make navigation feel amazing for your users.

<Frame>
  <iframe />
</Frame>

## Model AI teaser

*Chris Swenson · `Modeling` `Ai`*

Not quite a demo, but soon Blobby will be on call for helping modelers in the IDE.

<Frame>
  <iframe />
</Frame>

## Blobby learns parallelization

*Gustav Staprans · `Ai`*

Frequently your friendly neighborhood blob will need to run multiple queries to answer a question. Now Blobby can selectively parallelize querying to speed up the AI experience by orders of magnitude. More work to do here, but the side-by-side shows how massive the diff can be.

<Frame>
  <iframe />
</Frame>

## Recently used colors

*Mariel Freyre · `Visualization` `Workbook`*

Now when you select you favorite colors for charting or conditional formatting we'll remember and let you quickly reuse them elsewhere.

<Frame>
  <iframe />
</Frame>

## Copying conditional format rules

*Mariel Freyre · `Visualization` `Workbook`*

Now you can copy conditional formatting rules in a click for easy table building.

<Frame>
  <iframe />
</Frame>

## Bunch of dash container UX

*James Bueche, Jared Hardy, Meredith Dodge · `Dashboards`*

A grab bag of UX improvements for layout on containers.

<Frame>
  <iframe />
</Frame>

## Turning off document request access

*Trip Tate · `Dashboards` `Administration`*

A quick refinement for our new request-access workflow. Now for documents you don't want folks asking about, you can opt for a 404 page rather than the request workflow in document settings.

<Frame>
  <iframe />
</Frame>

## Dashboard sharing checks app permissions

*Trip Tate · `Dashboards` `Administration`*

Now when you try to share a dashboard we'll flag app permissions that mean a user cannot view the object (say no permissions to the data set requested). This makes it more clear if you need to use accessboost or talk to an admin about opening up data to others.

<Frame>
  <iframe />
</Frame>

## Safari login improvements

*Nate Agrin · `Safari` `Administration` `Performance`*

Making it simpler to authenticate for Safari users.

<Frame>
  <iframe />
</Frame>

## Requery improvements for weeks

*Jonathan Swenson · `Performance`*

Weeks were stubbornly avoiding the DuckDB requery cache for certain use cases that now work nicely.

<Frame>
  <iframe />
</Frame>

## Totals fix with unlimited downloads

*Jonathan Swenson · `Performance` `Export`*

Bunch of hidden work to improve downloads with totals.

<Frame>
  <iframe />
</Frame>

## Model extension and branches

*Conrad Slimmer · `Modeling`*

We're going deep on building out the modeling experience for model extensions (think personal, departmental mini data models) and branches.

<Frame>
  <iframe />
</Frame>

## Inspector deep link and groups fix

*Nate Agrin · `Dashboards` `Administration` `Content Management`*

A couple tune ups - first a quick link to the SQL from the dashboard (we may limit to developers), and a fix up to groups to make sure we don't error with emojis, et al.

<Frame>
  <iframe />
</Frame>

## Better embed URL builder

*Cade Austin · `Embed` `Administration`*

We tuned up the auto-complete and input experience for the embed URL builder to make getting started easier.

<Frame>
  <iframe />
</Frame>

## More Claude Code tooling (internal)

*Luke Bowerman · `Internal`*

Bit of our internal workflow for documenting code and making our team more productive using Claude Code.

<Frame>
  <iframe />
</Frame>

## More work on Claude Code workflows (internal)

*Chris Swenson · `Internal`*

Another bundle of work to improve our internal developer productivity.

<Frame>
  <iframe />
</Frame>

## Automated doc building (internal)

*Erin Cochran · `Docs` `internal`*

Peek behind the scenes at our workflow to make sure the amazing pace that you see from our engineering team makes it to the docs.

<Frame>
  <iframe />
</Frame>


# January 30, 2026
Source: https://docs.omni.co/demos/2026/20260130

Blobby Builds a Dashboard, Better AI Streaming, Funnel Vis, and Way More AI + Everything Else

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby learns to build your dashboard

*James Bueche · `Dashboards` `Ai`*

Blobby isn't only for querying. Now you can get some help building out your dashboards courtesy of a Blobby helper for building and arranging dashboards. Early days here, but would love thoughts on where this can help builders get more productive.

<Frame>
  <iframe />
</Frame>

## Huge improvement to AI streaming UX

*Gustav Staprans, Sarah Waterson · `Ai`*

We made some huge improvements to the UX and clarity of the AI streaming experience to make sure it both feels amazing and clearly shows you what it's working on.

<Frame>
  <iframe />
</Frame>

## Claude personal access token (OAuth) for MCP

*Jack Sweeney, Corey Ruderman · `Ai` `Mcp`*

Now when you use Blobby inside Claude MCP, we can make sure authentication and the UX is personalized to each user. This also opens up the Claude marketplace for Omni and Blobby.

<Frame>
  <iframe />
</Frame>

## Agentic query API

*Corey Ruderman · `Ai` `Api`*

Blobby is bringing the full suite of capabilities to the API. Now your API queries can progress through the same logical, multi-query experience as the UI. This will power the incoming Slackbot, or really whatever you can imagine.

<Frame>
  <iframe />
</Frame>

## AI summary / vis dash toggle

*Jamie Davidson · `Dashboards` `Ai`*

AI summary visualizations are fabulous - summarize and synthesize for the user. But sometimes you want to be able to dig in to the actuals too. Soon you'll be able to toggle between the results and the AI summarization (or visualizations).

<Frame>
  <iframe />
</Frame>

## Snowflake Cortex for AI LLM

*Gustav Staprans · `Ai` `Snowflake`*

Now instead of your favorite foundation LLM, you can also swap in Snowflake Cortex.

<Frame>
  <iframe />
</Frame>

## Funnel vis

*Rob Miller · `Visualization`*

More work on brand new visualizations.  This time a look at our work on funnels.  Tell us what you want to see in here (and next).

<Frame>
  <iframe />
</Frame>

## Blobby fill chart

*Rob Miller · `Visualization`*

Blobby wanted to get in on the vis game. A first look at fill charts Omni style.

<Frame>
  <iframe />
</Frame>

## More containers improvements

*Luke Bowerman · `Dashboards`*

A grab bag of UI/UX improvements to our new dashboards.    Keep the feedback coming, we're continuing to make sure the new experience is great.

<Frame>
  <iframe />
</Frame>

## Dashboard tile dragging improvements

*Meredith Dodge · `Dashboards`*

Making sure dragging tiles around (including in and out of containers) feels great.

<Frame>
  <iframe />
</Frame>

## Content validator autocomplete plus more UX

*Mariel Freyre · `Administration` `Modeling`*

After some feedback about making auto-complete and the content validator experience better, we spent a bit of time making sure clean up and admin feels great too.

<Frame>
  <iframe />
</Frame>

## Workbook model quick viewer

*Jamie Davidson · `Workbook`*

Soon you'll be able to see workbook model changes in a couple clicks.

<Frame>
  <iframe />
</Frame>

## Filter push down plus SQL perf testing

*TJ Banghart · `Modeling` `Performance`*

Some new modeling work to enable filter push down into joined views, plus a bunch of testing framework on our side to understanding ongoing model improvement work.

<Frame>
  <iframe />
</Frame>

## Side-by-side embedding and cookie management

*Nate Agrin · `Embed` `Dashboards`*

Much more flexibility for folks embedding side-by-side or swapping experiences for users - now you can have one user logged in to different experiences without full re-authentication.

<Frame>
  <iframe />
</Frame>

## Git with branches and extensions

*Conrad Slimmer · `Modeling` `Git`*

Bunch of work to enable great git work flows in the most complex deployments (like extension models), plus some conversation on future there.

<Frame>
  <iframe />
</Frame>

## Long running query stability and performance improvements

*Jonathan Swenson · `Performance` `Administration`*

Some mostly silent work to make long running queries work better, especially with weak internet.

<Frame>
  <iframe />
</Frame>

## Better connection setup and testing

*Jonathan Swenson · `Administration`*

Bit of work on our admin and setup.

<Frame>
  <iframe />
</Frame>

## Claude coordinator improvements task building

*Jonathan Swenson · `Internal`*

Another peek into work on our internal tooling to ship more, better, faster.

<Frame>
  <iframe />
</Frame>


# February 6, 2026
Source: https://docs.omni.co/demos/2026/20260206

34 Demos - A Peek into the Future of Omni (Hint, Lots of AI)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby learns to analyze hand drawn notes (annotations, in app chat, notifications, and more)

*Chris Swenson, Luke Bowerman · `The Future` `Ai` `Dashboards` `Workbook` `I can't describe this properly just watch`*

All I can say is you need to watch this one if you want to see the future. We have some of the basics with a new twist, like conversations and tagging for dashboards. But we also layer in hand-drawn annotation (think Microsoft paint) combined with the magic of Blobby. Circle an outlier and ask Blobby to go figure out why. Drill with a marker. Ask a question with a picture. This is a window into the future of analytics.

<Frame>
  <iframe />
</Frame>

## Python in Omni plus Blobby learns Python

*Gustav Staprans, Jonathan Swenson, Dan Spangenberger, TJ Banghart · `Ai` `Python` `Workbook`*

The goal with Omni has always been more of everything.    Python is more of something.    Here we give a demo of some work on bringing data science to the app, and, of course, making sure Blobby can take advantage.

<Frame>
  <iframe />
</Frame>

## Model demotion

*Conrad Slimmer · `Modeling`*

The monotonic model growth will be no more! Maybe the feature request we've talked about the most internally. Data models grow. Sometimes that is good, sometimes it was because you did a one-off thing you're never going to look at again (or maybe even look at, but don't need polluting everyone's headspace). Conrad worked on bringing all that metadata to the data model, and ultimately allow users to push data model from the shared model back into their dashboards!!

<Frame>
  <iframe />
</Frame>

## Super serious\[ly awesome] emoji AI feedback

*Mariel Freyre · `Ai` `Workbook`*

Feedback (and the follow up tuning) is a core part of building the AI experience. This demo reimagines the AI feedback with emojis to quickly let your developers know what is working and what isn't. And some fun baked in too.

<Frame>
  <iframe />
</Frame>

## Crossfiltering beta

*Steven Talbot, Rob Miller · `Dashboards`*

Coming soon! We've been putting work into the cross-filter UX so you can slice and dice to hearts content with charts instead of filters. Testing internally, let us know if you want an early look.

<Frame>
  <iframe />
</Frame>

## Blobby learns to spreadsheet

*Richard Czechowski · `Ai` `Spreadsheet`*

Step one was bringing a full dashboard into Omni. Step two is making it so AI can build those spreadsheets for you. Richard demos a few of those functions, including an instant invoice generation from a row of data, styling, or quick summary stats.

<Frame>
  <iframe />
</Frame>

## Blobby learns to build dashboards (plus the best loader you've ever seen)

*Alisa Tatarinova · `Ai` `Dashboards` `Blobby Bouncer`*

Alisa shows off a quick tool to let Blobby bring content between environments (plus an awesome loader). Stay until the end to see Blobby building a new dashboard tile on the fly. More AI everywhere.

<Frame>
  <iframe />
</Frame>

## Omni full app inside MCP

*Meredith Dodge, Joel Dodge · `Ai` `Mcp` `The future`*

Bit of a futuristic demo. Here we load the full app into the MCP experience, including backlinks to the core app.

<Frame>
  <iframe />
</Frame>

## Blobby learns to build a DB connection (AI get started)

*Nate Agrin · `Administration` `Ai`*

AI everywhere is the goal. Blobby takes on adding a new database connection in Omni, meaning you can set up a connection and get querying inside a minute in the AI chat.

<Frame>
  <iframe />
</Frame>

## Connection setup clean up

*Nate Agrin · `Administration`*

Bunch of fresh UX paint on the connection setup page. Better organization, more clear feedback, instant model, etc.

<Frame>
  <iframe />
</Frame>

## Blobby learns to debug your database connection

*Cathy Lennon · `Administration`*

A little AI makes everything better. Here Blobby helps figure out why the DB connection didn't go as plans, with little helpers and a Q\&A to get you unblocked quickly.

<Frame>
  <iframe />
</Frame>

## Embed web components

*Nate Agrin · `Embed`*

Adding a bit more delight to the developer experience for embed builders.

<Frame>
  <iframe />
</Frame>

## Omni CLI + Omni 1980 UI

*Nate Agrin · `Administration` `Modeling`*

Bunch of work on the CLI, including a nice new (?) UX.

<Frame>
  <iframe />
</Frame>

## Release FYI / understand Omni versions (mostly internal)

*Brian Frantz, Kyle Speer · `Administration` `Internal`*

We ship a lot of code (34 demos this week). It makes debugging which app version is live tricky for us internally. Our friendly neighborhood devops team built a full UI + Slack experience to make sure we can debug quickly.

<Frame>
  <iframe />
</Frame>

## Dashboard auto pretty plus new layout controls (keyboard, multi element)

*James Bueche · `Dashboards`*

First, we show off some new UX controls for dashboards - multi-element grabbing, keyboard controls, quick delete, etc. Then you see some new AI magic for instantly making a dashboard layout nicely. More to do here, but AI everywhere!

<Frame>
  <iframe />
</Frame>

## Omni employee directory (internal)

* Sam Pittman · `Internal`\*

Sam had some fun creating a new internal tool to find Omnis.

<Frame>
  <iframe />
</Frame>

## Blobby learns to surf the web

*Jamie Davidson · `Ai`*

Blobby can soon enrich results with live web queries, for deeper, multi-modal use cases (all fake names, etc).

<Frame>
  <iframe />
</Frame>

## Long running task notifications

*Trip Tate · `Ux` `Scheduler` `Ai`*

It's not fun to sit and stare at your monitor for long-running tasks (think queries then render or long AI sessions). Soon you'll be able to use notifications to return when the job is done.

<Frame>
  <iframe />
</Frame>

## letmeblobbythatforyou.com

*Chris Merrick, Trey Shugart · `Ai` `Fun`*

We built a quick microsite for when you need to help a friend understand their data better.

<Frame>
  <iframe />
</Frame>

## Blobby suggests dashboards instead

*Chris Merrick, Trey Shugart · `Ai` `Dashboards`*

Blobby has been a magical unlock for avoiding dashboard bloat. Just ask. But sometimes there was already a dashboard that answers your question perfectly. Soon Blobby can redirect you to those instead of reinventing the wheel.

<Frame>
  <iframe />
</Frame>

## AI Explo-to-Omni conversion tooling

*Gary Lin,  Andrew Chen · `Ai` `Administration` `Conversion`*

The former Explo team shows off a bunch of new tooling to bring dashboards and reports from Explo instantly into Omni, of course with lots of Clauding behind the scenes.

<Frame>
  <iframe />
</Frame>

## Blobby tasks (ie Blobby builds your slide deck)

*Arielle Strong · `Ai` `Slides` `Vibes`*

Surely you've done an analysis that you had to present in slides. Soon Blobby can build your decks or docs for you. Arielle shows off a few use cases for the new AI Tasks.

<Frame>
  <iframe />
</Frame>

## Blobby learns ETL

*Chris Merrick · `Ai` `Etl`*

If you're anything like us, on the last day of the quarter you're sitting on dashboards waiting for the new ETL to land. Soon Blobby will be able to reach into Fivetran for new data on command.

<Frame>
  <iframe />
</Frame>

## Automated documentation

*Nancy Chacko, Erin Cochran · `Docs` `Ai`*

We ship a lot of code. Sometimes docs are the bottleneck for customers taking advantage (including screenshots). The team has been working on offloading some of that work to Claude to make sure our docs can keep up with our builders.

<Frame>
  <iframe />
</Frame>

## Table text formatting (pills and icons)

*Sarah Waterson · `Visualization` `Tables` `Workbook` `Dashboards`*

We're prettying up the data table with pills and icons (backed with conditional formatting of course), so your data pops. And, like everything else, can take advantage of modeled colors for consistent table presentations anywhere you use dimensions.

<Frame>
  <iframe />
</Frame>

## Markdown columns

*Richard Czechowski · `Tables` `Visualization` `Dashboards`*

We're bringing all the flexibility of markdown to the data table. Grab values across the row for quick ultra-flexible data styling.

<Frame>
  <iframe />
</Frame>

## AI columns any dialect

*Richard Czechowski · `Ai` `Workbook` `Calcs`*

We already released AI functions in Snowflake, but soon you'll be able to take advantage of classifiers and other quick row-actions in any dialect using our calc layer.

<Frame>
  <iframe />
</Frame>

## Blobby learns to Slack

*Eli Cohen · `Ai` `Slack`*

The goal is buttons only when you want them. Here we quickly send a dashboard to Slack using Blobby.

<Frame>
  <iframe />
</Frame>

## Multi-step MCP Omni workflows (query, build dash, schedule)

*Corey Ruderman · `Ai` `Mcp` `The Future`*

An end-to-end demo of Blobby writing query, building dashboard with said query, and even building up a schedule on the result. Running the whole app from the MCP chat box.

<Frame>
  <iframe />
</Frame>

## Blobby voice mode

*Jared Hardy · `Ai` `Voice`*

We're seeing more and more Blobby usage on mobile, so Jared built a way to take advantage of voice for AI data exploration.

<Frame>
  <iframe />
</Frame>

## Dark mode vis config defaults

*Jared Hardy · `Visualization` `Administration`*

An early preview of enabling chart styles independently for dark mode.

<Frame>
  <iframe />
</Frame>

## Styling stub periods in charts

* Mike Torosian · `Visualization`\*

Is there anything worse than a time-series chart that tanks on the last data point because of a partial time period? Probably. But we fixed that anyways. Soon you can style your chart stubs to make sure your conclusions are that much more obvious.

<Frame>
  <iframe />
</Frame>

## Autohealing code tests

*Kalen Petersen · `Internal` `Engineering Productivity`*

Our dev team got some new goodies too. Here we show off an end-to-end framework for Claude to understand and refine tests that let us ship safer, better, faster.

<Frame>
  <iframe />
</Frame>

## Release summarization AI

*Jack Sweeney · `Internal` `Docs`*

Bit of new tooling to make sure the product team can see everything getting shipped and make sure you all know about it.

<Frame>
  <iframe />
</Frame>


# February 13, 2026
Source: https://docs.omni.co/demos/2026/20260213

Blobby Joins the Modeling Team, Omni Becomes Your MCP, AI in All Views and Fields, Visual Drilling, New Dashboard Search, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby joins the modeling team

*Chris Swenson · `Ai` `Modeling`*

Our more advanced modelers have been using Claude Code to unlock huge productivity in the CLI for modeling workflows. We wanted to make sure everyone has access to AI tools when building data models. Now Blobby will follow you around the IDE and can intervene to build model (in branches of course). Goal is extreme productivity and way less busywork (think formats on 100s of fields, automating descriptions, or even heavier SQL building - anything you can imagine). As always, this isn't a black box, and developers can review before accepting to make sure everything works as expected.

<Frame>
  <iframe />
</Frame>

## Omni is your MCP

*Gustav Staprans · `Ai` `Mcp` `Notion`*

We have lots of folks integrating Blobby into external MCP use cases. It means you can bring all of the Omni goodness to any AI workflow you can imagine. We also wanted to make it easier for folks to get going. Now you can use Omni as the central MCP - calling independent services alongside Blobby where we'll manage the connectivity. This will open up Salesforce updates, Notion, even custom internal tools inside Blobby. Very excited to see what folks do with this.

<Frame>
  <iframe />
</Frame>

## AI in all views and fields

*Steven Talbot · `Ai` `Workbook`*

We introduced a brand new toggle to unleash Blobby on the less-modeled All Views and Fields. This won't be for everyone, but opens up completely new, less-modeled use cases for more productivity with AI. Plan to open up SQL in the future as well to make sure we offer the full spectrum of experience.

<Frame>
  <iframe />
</Frame>

## Blobby learns to look for specific documents

*Chris Merrick · `Ai`*

Now you can flag explicit documents for Blobby to look-up when answering tactical questions (think product roadmap, pricing, or other internal knowledge base docs you may want AI to reference and/or query).

<Frame>
  <iframe />
</Frame>

## Better Slack chips (UX) in AI

*Gustav Staprans · `Ai` `Slack`*

Some small UX improvements to make sure the Slack responses from Blobby look great and are easy to read.

<Frame>
  <iframe />
</Frame>

## Better large file warnings for AI

*Gustav Staprans · `Ai`*

Another small AI tune-up. We have some current limits on file size with Blobby (very much plan to relax these and allow bigger and bigger files). Either way, wanted to make sure it was clear what we can support in terms of external files in the UI.

<Frame>
  <iframe />
</Frame>

## New dashboard search

*Eli Cohen · `Content Organization` `Search` `Dashboards`*

We've completely overhauled the dashboard search experience - now you can search for others' favorites, by tag, or other facets to quickly find what you need. Let us know what else you wish was available in the search index.

<Frame>
  <iframe />
</Frame>

## Workbook field lineage

*Jamie Davidson · `Workbook` `Modeling`*

We're working on some new UX to show the difference between centralized model objects and workbook-only objects. More to do here but want to make sure governance and ownership is always clear.

<Frame>
  <iframe />
</Frame>

## Formatted Excel downloads

*Jonathan Swenson · `Export` `Downloads` `Excel`*

Now Omni makes sure your downloads into Excel can preserve value formatting, etc when grabbing XLSX files.

<Frame>
  <iframe />
</Frame>

## Visual drilling

*Jamie Davidson · `Workbook` `Dashboards`*

Soon you'll be able to define visualizations alongside the explicit drill fields or drill queries for richer workflows.

<Frame>
  <iframe />
</Frame>

## Internal eng tooling

*Luke Bowerman · `Internal` `Engineering Productivity`*

Another look into how we're building internal tools and processes to make sure we can ship better, faster.

<Frame>
  <iframe />
</Frame>


# February 20, 2026
Source: https://docs.omni.co/demos/2026/20260220

Input Columns, Blobby Learns to Validate Work, AI Quickstarts, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Input columns

*Richard Czechowski · `Workbook` `Dashboards`*

A first look at the new UX for creating data from the workbook or dashboard. Now you can build columns that allow collecting data from end users. Opens up tons of read/write use cases for specific workflows.

<Frame>
  <iframe />
</Frame>

## AI query checking / validation

*Steven Talbot · `Ai`*

Blobby is great, but doesn't always get it right on the first try. We're building more intelligence into the AI experience by explicitly validating the results matched the user's intent correctly. More work to do here, but want to make sure Blobby can always get it right hands off.

<Frame>
  <iframe />
</Frame>

## Blobby quickstart mode

*Gustav Staprans · `Ai` `Workbook`*

The biggest blocker to more Blobby is often getting started. Here we show off building a data model and AI context from scratch entirely in the UI. More work to do here, but want to make getting started with a new data set or table completely AI-able.

<Frame>
  <iframe />
</Frame>

## AI workflows examples

*James Ostergaard · `Ai` `Use Cases`*

Workflows have been in GA for a bit, but we wanted to show off some internal use cases that are creating huge efficiencies for us. We'll get these in the docs for folks that want to crib or extend.

<Frame>
  <iframe />
</Frame>

## Google Calendar in Blobby

*Gustav Staprans · `Ai` `Mcp` `Google Calendar`*

More Blobby MCP - this time bringing Google calendar into the AI experience.

<Frame>
  <iframe />
</Frame>

## Dashboard templates

*Luke Bowerman · `Dashboards`*

With the near term GA of containers (the new dashboard experience), we wanted to make it easy to build beautiful dashboards even with the additional belles and whistles. Templates make common dashboard patterns easier to build and control.

<Frame>
  <iframe />
</Frame>

## Color palette selector improvements

*Luke Bowerman · `Workbook` `Visualization`*

More refinement to the color picker experience.

<Frame>
  <iframe />
</Frame>

## Funnel vis launch

*Rob Miller · `Visualization`*

The new funnel vis is moving to GA.

<Frame>
  <iframe />
</Frame>

## Pie chart label config

*Dan Mosora*

We love to see a first-week demo. Here picking up a much-requested feature for configuring pie chart labels more flexibly (like percentages alongside values).

<Frame>
  <iframe />
</Frame>

## Per user week start and fiscal offset

*Conrad Slimmer · `Embed` `Modeling`*

More complex embed setups often have customers with different fiscal calendars and business weeks. Now you can serve that complexity dynamically using user attributes.

<Frame>
  <iframe />
</Frame>

## IDE UX improvements search and sidebar

* Mike Torosian · `Modeling` `Ux`\*

Bunch of tune up for the IDE experience - improved file search UX and some tune up to the sidebar search as well.

<Frame>
  <iframe />
</Frame>

## Using Omni's CLI to add AI context from external sources

*Kylee Schroth · `Modeling` `Workflows` `Cli` `Ai`*

An end-to-end demo of building data model + AI context via Cursor and Omni CLI. This means folks can bring help docs from external sources like Notion to instant build context into Omni.

<Frame>
  <iframe />
</Frame>

## Automated Github tickets from Slack threads (internal)

*Jade Khiev · `Internal` `Use Cases` `Ai`*

Another internal productivity workflow we wanted to share. This allows us to take Slack threads with feedback or bug reports and instantly file rich Github tickets (ideally to mostly-automate resolution via Claude Code).

<Frame>
  <iframe />
</Frame>


# February 27, 2026
Source: https://docs.omni.co/demos/2026/20260227

AI Modeling, Cell-by-Cell Conditional Formatting, Dynamic Dashboard Table Height, Better AI Feedback, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Model Blobby bulk changes

*Chris Merrick · `Ai` `Modeling`*

AI has come to the data model. With new multi-file search you can coordinate actions across the full data model. Bunch of great use cases here and we'll start documenting all the best workflows. Let the robots do the maintenance.

<Frame>
  <iframe />
</Frame>

## Conditional formatting cell by cell

*Mariel Freyre · `Visualization` `Workbook` `Table`*

More work on the BI foundations - this time extending our conditional formatting logic to full Excel style (A1:B1) for completely flexible table styling.

<Frame>
  <iframe />
</Frame>

## Blobby learn to debug

*Jamie Davidson · `Ai`*

More tools for blobby. The new context debug helps blobby to explain why you get what you get. More to do here, but continuing to build tools to give developers control.

<Frame>
  <iframe />
</Frame>

## AI powered visualizations with new API

*Nate Agrin · `Visualization` `Api` `Ai`*

Now visualization is easy to access through the natural language APIs for consistent but intelligent charting no matter where you are calling Omni.

<Frame>
  <iframe />
</Frame>

## Dynamic dashboard tile height for tables

*Meredith Dodge · `Dashboards`*

You made a dashboard but the top table ranges between 10 rows and 100 based on the filters. You were stuck with scrollers or whitespace, but now height will dynamically adjust for better end user experience.

<Frame>
  <iframe />
</Frame>

## Emoji AI feedback

*Mariel Freyre · `Ai` `Ai Feedback`*

One of the most important tools for managing AI quality is getting feedback from your users. The new emoji feedback experience makes it simpler for your users to give great feedback and thus improve the AI experience in the future.

<Frame>
  <iframe />
</Frame>

## Scheduling with advanced dashboard layouts

*Trey Shugart · `Dashboards` `Scheduler` `Export`*

Schedules landing on the new dashboard experience - the last piece before GA.

<Frame>
  <iframe />
</Frame>

## CSV upload APIs

*TJ Banghart · `Api` `Csv` `Workbook` `Modeling`*

Now you can update and tune CSVs via the API, including associated model generation.

<Frame>
  <iframe />
</Frame>

## dbt for Starrrocks

*TJ Banghart · `dbt` `Starrocks` `Administration`*

We extended our dbt integration to the Starrocks dialect.

<Frame>
  <iframe />
</Frame>

## Databricks Lakebase support

*TJ Banghart · `Administration` `Databricks` `Lakebase`*

We've seen more customers complementing their Databricks warehouse with Lakebase. Now Omni supports both.

<Frame>
  <iframe />
</Frame>

## Sankey tune ups

*Dan Mosora · `Visualization`*

More vis tune-up, here adding optional percentages to Sankey.

<Frame>
  <iframe />
</Frame>

## More CSS color controls

*Jared Hardy · `Visualization` `Administration` `Colors` `Embed`*

We've extended our CSS app controls into the markdown vis for great light/dark integration and more customization.

<Frame>
  <iframe />
</Frame>

## Demo search mini app

* Drea ✨ · `Vibe Coding` `Apps` `Docs`\*

A handy micro-site to browse across the hundreds of demo videos.

<Frame>
  <iframe />
</Frame>

## New folder APIs

*Luke Bowerman · `Api` `Embed`*

Handful of new APIs for folder management like deletion or updating even with content inside.

<Frame>
  <iframe />
</Frame>

## Dashboard improvements (filters, etc)

*Luke Bowerman · `Dashboards`*

More progress on the new dashboard experience.

<Frame>
  <iframe />
</Frame>

## Edit mode themes plus themes quick builder

*Luke Bowerman · `Embed` `Administration` `Colors`*

New style controls for the edit mode bar and buttons plus a quick CSS generator for the app from an image.

<Frame>
  <iframe />
</Frame>

## Recent activity session viewer

*Luke Bowerman · `Content Organization` `Workbook` `Administration`*

Recent activity got a major upgrade for finding that analysis you did yesterday but didn't save. Now with sessionization!

<Frame>
  <iframe />
</Frame>

## Blobby dashboard clean up

*James Bueche · `Dashboards` `Ai`*

Don't want a tile anymore, now you can ask Blobby. Plus keyboard shortcut for deletion and movement.

<Frame>
  <iframe />
</Frame>

## Branch search

*Meredith Dodge · `Modeling` `Administration`*

Some new functionality to quickly find your branch in long lists.

<Frame>
  <iframe />
</Frame>

## Claude and Cursor skills

*Jack Sweeney · `Ai` `Mcp`*

Pair of new skills for Claude and Cursor to make sure they can take full advantage of the Omni app.

<Frame>
  <iframe />
</Frame>

## Snowflake external OAuth

*Chris Merrick · `Administration`*

Support for alternative Snowflake auth.

<Frame>
  <iframe />
</Frame>

## Docs internal tools

*Erin Cochran · `Docs` `Internal` `Developer Productivity`*

Some new internal workflows to make sure fresh code gets great docs fast.

<Frame>
  <iframe />
</Frame>

## New internal dev tools

*Luke Bowerman · `Inernal` `Developer Productivity`*

Quick demo of some new internal facing developer workflow improvements.

<Frame>
  <iframe />
</Frame>


# March 6, 2026
Source: https://docs.omni.co/demos/2026/20260306

AI dashboard building, forecasting, modeling, Salesforce MCP, treemaps, custom maps, button filters, and more new features.

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby builds a dashboard from scratch

*`Trip Tate · Ai Dashboards`*

Agent Blobby is getting smarter. Now you can create a dashboard from scratch with just a prompt. We'll be layering in style files and other controls here, but a new dashboard is not a prompt away.

<Frame>
  <iframe />
</Frame>

## Blob the builder

*`James Bueche · Ai Dashboards`*

Dashboard building is about more than one-shot prompts. In parallel we're working on tools to sit alongside your existing dashboards for refinement post creations - editing, updating, arranging, deletion. Anything you can do with UI we're lifting into the AI experience.

<Frame>
  <iframe />
</Frame>

## Blobby learns to forecast

*`Trip Tate · Ai Data Science Visualization`*

Blobby has a new skill. Now you can layer instant forecasts onto your time-series data (including several model options).

<Frame>
  <iframe />
</Frame>

## Model Blobby

*`Chris Swenson · Ai Modeling`*

We're still working on amazing AI tools for developers - here you see new branching controls and more dynamic back and forth to refine modeling actions by Blobby.

<Frame>
  <iframe />
</Frame>

## Salesforce MCP and updates in Blobby

*`Jamie Davidson · Ai Mcp Salesforce Actions`*

Blobby is now closing the loop. Here we show off a direct connection to Salesforce MCP for completely live data. And of course once you have the live connection it means you can also start updating records directly from Omni. Now your data analytics can lead directly into actions in your source systems.

<Frame>
  <iframe />
</Frame>

## Blobby debugger

*`Jamie Davidson · Ai Modeling Workbook`*

Of course we want the most refined tools to managing model context for AI, but that doesn't mean we can't make passive learning and history seamless too. Here you see more work on automated modeling to learn from AI sessions.

<Frame>
  <iframe />
</Frame>

## Button filters for dashboards

*`Alisa Tatarinova, Luke Bowerman · Dashboards Filters`*

We're still actively working on the filter experience for dashboards. Now you can toggle the filter type to a fully buttonized UI.

<Frame>
  <iframe />
</Frame>

## Custom SVG maps

*`Rob Miller · Visualization Maps`*

Brand new vis for the map lovers - now you can bring any custom SVG maps and interact easily.

<Frame>
  <iframe />
</Frame>

## Treemaps

*`Dan Mosora · Visualization`*

Another new vis type, this for quickly navigating hierarchical proportions.

<Frame>
  <iframe />
</Frame>

## Crossfilter UX improvements

*`Rob Miller · Dashboards`*

Few finishing touches on the cross-filter UX to make it feel intuitive and simple.

<Frame>
  <iframe />
</Frame>

## Pindrop game plus data driven tuning

*`William Watkins · Use Cases Playpindrop.app Ai Actions`*

We want to continue showing more end-to-end use cases of how to tie together great data analytics, AI, and, most importantly, actions. William demos his new game ([https://playpindrop.app](https://playpindrop.app), get in there and share your scores). But more than just an awesome game, we take a look at the analytics in Omni behind the scenes and how we can use that data to improve the user experience directly with balance adjustments.

<Frame>
  <iframe />
</Frame>

## Building an end-to-end custom demo

*`Peter Whitehead · Ai Use Cases Snowflake Cortex Claude skills Cursor skills`*

This is a soup to nuts demo of Omni with data creation, model creation, all the way to dashboards and AI querying. Plenty of Snowflake Cortex with Claude and Cursor skills alongside plenty of Omni.

<Frame>
  <iframe />
</Frame>

## More work on OmniTopics (ie. multi fact tables)

*`TJ Banghart · Modeling Workbook`*

TJ shows off some new UX for multi-fact tables, including easy filtered measure building across tables.

<Frame>
  <iframe />
</Frame>

## More BQ auth options

*`TJ Banghart · Bigquery Administration`*

A new quick-nav to the connection for a workbook, plus new auth tooling for BigQuery admins.

<Frame>
  <iframe />
</Frame>

## More work on dbt environments

*`Buck Ryan · Dbt`*

Bunch more refinement of dbt environments, including user tagging and more.

<Frame>
  <iframe />
</Frame>

## Guides

*`Becca Bruggman · Docs Use Cases`*

We're doing more than bulking up the product. Becca shows some new AI workflows we're using to beef up long-form guides ([https://docs.omni.co/guides](https://docs.omni.co/guides)) for more complex modeling and analysis topics in Omni.

<Frame>
  <iframe />
</Frame>

## Internal branch banner

*`Luke Bowerman · Internal Developer Productivity`*

Quick internal tool to make sure we can track experimental builds we're testing.

<Frame>
  <iframe />
</Frame>


# March 13, 2026
Source: https://docs.omni.co/demos/2026/20260313

Input Columns, Column Editing, GSheet Live Connect, and Tons of AI

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Input Column UX Refinement

*`Richard Czechowski · Spreadsheets Workbook Tables`*

Bunch of work on input columns, including new building and saving flow for input columns, dashboard editability, and concurrency handling.

<Frame>
  <iframe />
</Frame>

## Column Editing

*`Richard Czechowski · Spreadsheets Workbook Tables`*

Turn any existing column into an input column.  This means you can build a hidden overlay column for editing existing data - great for appy use cases on top of normal data flows.

<Frame>
  <iframe />
</Frame>

## Google Sheets Import

*`Richard Czechowski · Spreadsheets Workbook Tables Gsheets`*

Now instead of pasting data into Omni you can just point us to live data elsewhere.  Give us a Google Sheets URL and soon you'll be able to import sheets automatically, including refresh updates.

<Frame>
  <iframe />
</Frame>

## Crossfilter GA

*`Rob Miller · Dashboards`*

We're launching crossfiltering for everyone.  Now all your dashboards can be slice and dice.

<Frame>
  <iframe />
</Frame>

## Maps in Blobby

*`Rob Miller · Visualization AI`*

Bit of work to make sure the maps experience works great in AI

<Frame>
  <iframe />
</Frame>

## More Work on Blobby Quickstart

*`Gustav Staprans · AI`*

Creating some dedicated flows for going from zero to one with AI - including bringing external documentation and recording specific target questions to be answered with AI.

<Frame>
  <iframe />
</Frame>

## KPI Charts in Blobby

*`Nate Agrin · Visualization AI`*

We're making sure Blobby knows how to build great KPI tiles (think call out numbers, comparitors, sparklines, etc).

<Frame>
  <iframe />
</Frame>

## More IDE Blobby Work

*`Chris Swenson · Modeling AI`*

Working on refinements for IDE Blobby, including automatic branches, some nice UX on the new objects, workbook-page support, a nice acceptance workflow for new changes, and massive file handling (like your relationships).

<Frame>
  <iframe />
</Frame>

## AI Intelligence Settings

*`Steven Talbot · AI`*

A few new tools to control which models different Omni actions get directed to for balancing AI spend and level-of-intelligence.

<Frame>
  <iframe />
</Frame>

## AI Quality Improvements for Dates

*`Joel Dodge · AI`*

Some refinement to our system prompt to improve quality and correctness using complex date concepts.

<Frame>
  <iframe />
</Frame>

## Easier Embed Secret Rotation

*`Elliot Park · Embed`*

Now you can rotate secrets in-app trivially with multi-secret setups.

<Frame>
  <iframe />
</Frame>

## Container Dragging and Layout Refinement

*`Meredith Dodge · Dashboards`*

More work on making the drag experience feel amazing on new dashboards plus some tools for better tile and blank space management

<Frame>
  <iframe />
</Frame>

## More New Guides

*`Becca Bruggman · Docs`*

We're continuing to bulk up our long-form docs.  Bunch of new guides including level-of-detail, cohorting, and retail AI context building.

<Frame>
  <iframe />
</Frame>

## Datahub Catalog Support

*`Peter Whitehead · Integrations Datahub`*

We've built connectivity into some partner catalogs for understanding dependencies for you data in Omni.

<Frame>
  <iframe />
</Frame>

## External Model Development (Claude + Cursor)

*`Kylee Schroth · Modeling Use Cases`*

A quick demo of using our Claude and Cursor connectors to build data models with AI

<Frame>
  <iframe />
</Frame>


# March 20, 2026
Source: https://docs.omni.co/demos/2026/20260320

Blobby was learning this week, plus custom formats, selective filter faceting, and more

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## OmniBlobby (ie Blobby Follows You Throughout the App)

*`Gustav Staprans · AI Dashboards Modeling Anything`*

An early peek at the future of Blobby.  We're building towards an AI that can follow you around the entire app with context from modeling to content to administration, with live UX for the entire app right next door.

<Frame>
  <iframe />
</Frame>

## Blobby Learns Markdown and HTML

*`Rob Miller · AI Visualization Dashboards`*

Markdown vis opens up anything you can imagine on top of your trusted data.  But it's hard to build.  Soon Blobby will fill that gap for us - drag in pictures or just describe what you want and Blobby will make it happen.

<Frame>
  <iframe />
</Frame>

## Blobby Learn More Dashboard Building (ie. Tabs)

*`James Bueche · AI Dashboards`*

Dashboard Blobby getting smarter - now you can build tabbed dashboards from AI too!

<Frame>
  <iframe />
</Frame>

## Blobby Explores the Info Schema

*`Bernard Sanders · Use Cases Modeling`*

A nice use case using the AI model helper to refine the data model by pinging the info schema.

<Frame>
  <iframe />
</Frame>

## BYO Databricks Genie for AI

*`Gustav Staprans · AI Databricks`*

New BYO model support for Databricks Genie.

<Frame>
  <iframe />
</Frame>

## Blobby Learns FP\&A Reviews

*`Joe Seib · AI Finance Use Cases`*

We're trying to bring more of our internal AI uses cases to demo.  Here we show off a new skill for reviewing month-over-month finance changes and debugging with Blobby.  Sorry heavy redaction - we'll try to get a better visual for you all.

<Frame>
  <iframe />
</Frame>

## Claude MCP Builds a Dashboard

*`Bernard Sanders · AI Use Cases`*

A quick demo of Omni skills in Claude building free form dashboards outside the tool.

<Frame>
  <iframe />
</Frame>

## Blobby Builds a Bracket

*` · AI Use Cases`*

Blobby gets in the mix picking a bracket using CSV upload and some prompting.

<Frame>
  <iframe />
</Frame>

## Excel Style Field Formatting

*`TJ Banghart · Dashboards Workbook Modeling`*

We extended the field formatting to draw on the full depth of Excel formats.  Here we demo an example with phone number format.

<Frame>
  <iframe />
</Frame>

## Dynamic Connection Switching in the UI

*`Trip Tate · Dashboards Administration`*

New user-facing toggle to swap connections for use cases that may map dashboards or datasets across mirrored schemas.

<Frame>
  <iframe />
</Frame>

## Selective Filter Faceting

*`Dan Spangenberger · Modeling Filters`*

You can now declare selective filter facets in the data model (think country facets region but not visa-versa).

<Frame>
  <iframe />
</Frame>

## Model Constants

*`TJ Banghart · Modeling`*

Now you can declare constants in the data model (think formats, variables) that you can use anywhere in the modeling experience via @.

<Frame>
  <iframe />
</Frame>

## Snowflake Cortex Code Meets Omni

*`Peter Whitehead · Snowflake Cortex AI`*

With the launch of Cortex Code in Snowflake you have the power of Claude Code style workflows attached seamless to Snowflake and downstream tools like Omni.  Here we demo what that opens up.

<Frame>
  <iframe />
</Frame>

## Claude Learns to Debug the Omni Logs

*`Jonathan Swenson · Logs Internal Claude`*

Mostly internal facing workflow for how we can debug issues with Omni from the logs using Claude.

<Frame>
  <iframe />
</Frame>

## Shared Extensions Guide

*`Rebecca Bruggman · Docs`*

More new docs content - this one for the very complex shared extension models.

<Frame>
  <iframe />
</Frame>

## Faster PDF Previews with Scheduler

*`Trey Shugart · Scheduler Dashboards`*

We made it easy to now view what your scheduled PDFs will look like in Omni.

<Frame>
  <iframe />
</Frame>

## S3 delivery destination

*`Corey Ruderman · Scheduler S3`*

S3 is now an option for data deliveries out of Omni. [Video link](https://www.loom.com/share/aa3c94c094e2430684cb8b600c359272)

## Enhancement to AI Jobs API (Progress Webhook)

*`Corey Ruderman · Scheduler API`*

Now you can track progress on AI in app via a progress webook. [Video link](https://www.loom.com/share/c05d2432969742a6b1c17a9523681cb0)

## Omni Employee Mini Site

*`Sam Pittman · Internal Fun`*

We built a micro-site for learning a little more about all the Omnis.

<Frame>
  <iframe />
</Frame>

## Support Helper + Docs Recommender (Internal)

*`James Ostergaard · Internal Docs`*

Building more internal tools to get customers better, faster answers, and some additional workflow to make sure we are building docs behind questions that aren't easy enough to self serve on.

<Frame>
  <iframe />
</Frame>

## Faster Support Login (Internal)

*`James Ostergaard · Internal`*

Little browser extension to make it so we can help out a little more quickly.

<Frame>
  <iframe />
</Frame>


# March 27, 2026
Source: https://docs.omni.co/demos/2026/20260327

Blobby Slackbot, Custom Modeled Formats (Conditional Formatting, Markdown, and HTML), HTML Dashboards, and More (Lots of AI)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Slackbot

*`Corey Ruderman, Eli Cohen · Slack AI`*

We're getting ready to release Blobby into Slack.  Maybe a bit of refinement on permissions, but getting close.

<Frame>
  <iframe />
</Frame>

## Custom Field Styling (HTML + Markdown)

*`TJ Banghart · Modeling Workbook Dashboards Tables`*

A huge overhaul to field formatting in the model to open up conditional formatting, markdown, and HTML - including handlers for common patterns like currency (with conversion).

<Frame>
  <iframe />
</Frame>

## HTML Dashboards Early Look

*`Nathan Agrin · Dashboards AI`*

A first look at our new dashboard type.  Omni is all about analytics every way - sometimes that is clean, structured, easy-to-edit dashboards, and sometimes its going to be vibed HTML with anything you can imagine.  More work to do here, but heading down the path.

<Frame>
  <iframe />
</Frame>

## Blobby Learns to Parallelize

*`Steven Talbot · AI`*

Now Blobby can parallelize activity, speeding up queries and reducing token consumption.

<Frame>
  <iframe />
</Frame>

## Blobby Builds a Dashboard Almost Launch (Tabs)

*`Trip Tate · AI Dashboards`*

More work on the AI dashboard building experience - cleaning up the chat session and opening up tabbed layouts.

<Frame>
  <iframe />
</Frame>

## AI Split Screen Mode

*`Gustav Staprans · AI Everything`*

More progress on the AI side-by-side with the full app.

<Frame>
  <iframe />
</Frame>

## Blobby Voice Learns New Languages

*`Jared Hardy · AI Languages`*

AI voice mode can now work in multiple languages + a quick German demo.

<Frame>
  <iframe />
</Frame>

## Bunch of Dash Editing UX Refinement

*`Jared Hardy · Dashboards`*

Lots of quality of life improvements for dashboard layout and styling.

<Frame>
  <iframe />
</Frame>

## Blobby Gets Better at Color Palettes

*`Dan Mosora · AI Dashboards Visualization`*

We're training Blobby to use your existing color styling preferences when building.

<Frame>
  <iframe />
</Frame>

## Blobby Quickstarts

*`Gustav Staprans · AI`*

We're streamlining the get-started process, with plenty of AI helpers.

<Frame>
  <iframe />
</Frame>

## Custom Data Set Builder

*`Justin He · AI Internal Use Cases`*

We built some new tooling to create higher fidelity demo data sets.

<Frame>
  <iframe />
</Frame>

## AI Blog + New Vertical AI Guides

*`Rebecca Bruggman · Docs`*

Lots of new content in the docs about making great AI models in Omni.

<Frame>
  <iframe />
</Frame>


# April 3, 2026
Source: https://docs.omni.co/demos/2026/20260403

Blobby Gets Unleashed, CLI + Some Use Cases, New Filter UX, Content Validator UX Lift, and Tons of Dashboard Work

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby AI+++

*`Steven Talbot · AI`*

Probably the biggest change to Blobby so far.  Now Blobby can weave together many queries to answer questions that simply weren't possible before in Omni.

One of the main challenges of use AI on top of the semantic layer was the constraint we introduced to try to one-shot queries in our UI.  Some queries are just too complex for a clean UI representation - think unions, inequality joins, repeated view chaining.  Now Blobby can use governed, ground base queries, but weave them together with the flexibility of full SQL.  You get governance and trust, Blobby gets to now answer literally anything.

Very excited to the use cases this opens up and we demo a complex query example to show you (plus take a look at that pull request data!!!).

<Frame>
  <iframe />
</Frame>

## Exploring Advanced Features of the OmniCLI Tool

*`Nathan Agrin · CLI AI`*

Part 2 of the Omni CLI - a few use nice use cases.  Think local agents on top of our rich APIs (plus faster and fewer tokens).

<Frame>
  <iframe />
</Frame>

## Quick Demo of Omni CLI Tool Features

*`Nathan Agrin · CLI AI`*

First look at the newly released open source Omni CLI - wrapping and extending the core API.  Supports both org-wide access tokens or personal acces tokens.

<Frame>
  <iframe />
</Frame>

## Adding HTTPS Git Integration With Access Tokens

*`Christopher Merrick · Administration`*

Some new work to integrate securely for folks using git with https (or personal access tokens).

<Frame>
  <iframe />
</Frame>

## BlobbyBreaker Leaderboard

*`Jade Khiev · Fun`*

Like any good data company, we recorded some stats on our Blobby Breaker April 1 game.  Enjoy the easter egg stats in analytics.

<Frame>
  <iframe />
</Frame>

## AI Modeling Auto-Optimizer

*`James Davidson · AI Modeling`*

An early look at some new automated tools to improve AI context in the model passively.

<Frame>
  <iframe />
</Frame>

## Improved Conditional Formatting UX

*`Mariel Freyre · Workbook Visualization Tables`*

More improvements to the conditional formatting workflow to make sure we bring the UX experience of spreadsheets into Omni.

<Frame>
  <iframe />
</Frame>

## Huge Improvements to Content Validator

*`Mariel Freyre · Modeling Administration`*

We've gotten feedback that the content validator could use some tune ups, so Mariel spent some time digging in and making workflows simpler and faster.

<Frame>
  <iframe />
</Frame>

## Better Filter Mapping on Dashboards

*`Jared Hardy · Dashboards`*

Bunch of UX tune ups to make filter mapping on dashboards feel better.

<Frame>
  <iframe />
</Frame>

## Omni 1984

*`Luke Bowerman · Design Fun`*

You already knew you could customize the CSS of Omni to make it feel like yours, but Luke wanted to make sure Mac enjoyers weren't left out after we released the Windows 98 skin last year.

<Frame>
  <iframe />
</Frame>

## Custom Dashboard Filter UX

*`Alisa Tatarinova · Dashboards Filters`*

Bunch of work to customize your dashboard filter UX including multi-select, custom dates, and lots of UX work.  Rolling out on an ongoing basis, but tell us more about what you want to see.

<Frame>
  <iframe />
</Frame>

## More Themes Work (Including Logos!)

*`Luke Bowerman · Design Embed API`*

More tune up on the theming UX, including the ability to swap in logos and favicons in light and dark mode!  Plus a pair of new embed events for navigation control.

<Frame>
  <iframe />
</Frame>

## Custom Emojis + Turn Them Off

*`Luke Bowerman · Administration`*

We released the custom emojis page in-app (fun).  And allow you to turn off our emoji tab naming in app (not fun).

<Frame>
  <iframe />
</Frame>

## Dashboard UX Refinements

*`Meredith Dodge · Dashboards`*

Bunch of tune ups for dashboards around resizing, tab building, and other edit mode goodies.

<Frame>
  <iframe />
</Frame>

## Dashboard Labels - Descriptions and Colors

*`Luke Bowerman · Dashboards`*

Now dashboard labels have optional colors for easier nav + some work to layer in descriptions to help understanding.

<Frame>
  <iframe />
</Frame>

## Dashboard AI Names and Descriptions

*`Luke Bowerman · Dashboards AI`*

More AI everywhere - this time for suggesting dashboard names or descriptions

<Frame>
  <iframe />
</Frame>

## Recent Activity Overhaul

*`Luke Bowerman · Navigation`*

A major overhaul to the recent activity UX - consolidating chat but also adding clear descriptions the sessions to more easily find that thing you were working on three days ago that you lost.

<Frame>
  <iframe />
</Frame>

## Blobby Tunes Dashboard Visualizations

*`James Bueche · Dashboards AI`*

Blobby is learning everything - already you can build dashboards, re-arrange layouts, and now you can also tune up vis on the dashboard with AI as well.

<Frame>
  <iframe />
</Frame>

## Dashboard ERD

*`Luke Bowerman · Dashboards AI`*

A new feature we are playing with to understand filter dependencies on the dashboard visually.

<Frame>
  <iframe />
</Frame>

## Suggested Dashboard Tags

*`Luke Bowerman · Dashboards AI`*

More AI everywhere - we suggesting the best tags for your dashboards for easier findability.

<Frame>
  <iframe />
</Frame>

## Dashboard Best Practices Guide

*`William Watkins · Dashboards Docs`*

A meticulous new doc on building better dashboards.  We'll be teaching this to Blobby soon as well.

<Frame>
  <iframe />
</Frame>

## dbt Docs and Guides

*`Rebecca Bruggman · Docs dbt`*

A new section of docs on dbt best practices to make sure you are set up well and understand the breath of connectivity into Omni.

<Frame>
  <iframe />
</Frame>


# April 10, 2026
Source: https://docs.omni.co/demos/2026/20260410

A Model That Improves Itself, Topic ERDs, Blobby Build Dashboard Filters, Named Formats, Gigantic, Formatted Spreadsheets, and Lots More AI

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Automated Model Improvement (with AI)

*`Chris Swenson · AI Modeling`*

A data model that improves itself has always been the dream.  Use the product, have the model improve passively.  This is the first step in a bunch of ongoing work to read in usage data (in this case AI feedback) and suggest improvements to the data model.  Lots more work to come here, but building towards a future where the model is doing work for you in the background (with review loops of course).

<Frame>
  <iframe />
</Frame>

## FILTER() in Spreadsheets (Huge Formatted Downloads)

*`Richard Czechowski · Spreadsheets`*

We've had some asks for even bigger native spreadsheets (think 500k rows by 100 columns).  With the new FILTER() function now you can build and style in Omni with the ability to export these enormous tables to Excel fully styled.

<Frame>
  <iframe />
</Frame>

## Table Conditional Format in Excel Downloads

*`Richard Czechowski · Spreadsheets`*

Now your conditional formats from native tables will persist on download into Excel - fully styled tables wherever you want em.

<Frame>
  <iframe />
</Frame>

## Named Custom Formats

*`TJ Banghart · Modeling`*

A little more love for custom formats in the model - now you can name your own for usage anywhere in the app.

<Frame>
  <iframe />
</Frame>

## More Work on OmniTopics (Calcs, Pivots, Field Building)

*`TJ Banghart · Modeling Workbook`*

More work to make OmniTopics first class - so exploring data across parallel data sets (think users, products, and orders at the same time, but joined on time).

<Frame>
  <iframe />
</Frame>

## AI Vis Validation

*`Dan Mosora · AI Vis`*

We're working on making the visualizations built with AI higher quality and more reliable.

<Frame>
  <iframe />
</Frame>

## Blobby Learns to Build Dashboard Filters

*`Trip Tate · AI Dashboards`*

We want Blobby to take away the tedious work of building and mapping dashboard filters.  Coming soon!

<Frame>
  <iframe />
</Frame>

## Exploring an AI Model Evaluation Framework

*`James Davidson · AI Modeling`*

Blobby is becoming a core team member for most of our customers.  The next step in the maturity curve is understanding the impact of changes to your model context.  Here's a first look at that framework natively in Omni.

<Frame>
  <iframe />
</Frame>

## AI Agent Builds Models from SQL History

*`James Davidson · AI Modeling`*

A bunch of new work we're experimenting with to accelerate building data models.  Here we use the SQL logs to bootstrap model concepts.

<Frame>
  <iframe />
</Frame>

## Writing Databricks Metric Views from Omni

*`Peter Whitehead · AI Databricks Modeling`*

Making it that much easier to build Databricks Metrics Views directly from Omni (with some AI of course).

<Frame>
  <iframe />
</Frame>

## Topic Interactive ERD Diagrams

*`Bernard Sanders · AI Modeling Workbook`*

An awesome new tool for easily seeing what's available in a topic and how it fits together.

<Frame>
  <iframe />
</Frame>

## Analytics Data on AI Spend

*`Colin Zima · AI Administration Analytics`*

Some ongoing work to publish full data on AI spend in Omni.  Bit of work to sessionize the query data.  Next step will be some benchmark stats across the customer base for typical cost-per-query.

<Frame>
  <iframe />
</Frame>

## Blobby Summarizes What Omni Eng Team is Doing

*`Arielle Strong · AI Internal`*

A quick skill for synthesizing all the product we are shipping.

<Frame>
  <iframe />
</Frame>


# April 17, 2026
Source: https://docs.omni.co/demos/2026/20260417

Vis Layers, AI Analytics and Cost Data, dbt APIs, and Bunch of AI Improvements

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Introducing Layers for Enhanced Visualization Control

*`Nathan Agrin · Visualization`*

A first look at a major step forward for visualization.  We're bringing layers to the UI in Omni.

<Frame>
  <iframe />
</Frame>

## Simplified Command Inputs and Improved Help Text

*`Nathan Agrin · AI CLI`*

More work on the CLI to improve your experience.

<Frame>
  <iframe />
</Frame>

## AI Cost Data

*`Colin Zima · AI Analytics`*

A walkthrough of new AI cost visibility tooling built into Omni. See how we've sessionized AI usage logs to surface per-query costs across the entire customer base — including token usage, tool call counts, and percentile breakdowns. AI usage has nearly doubled in two weeks, and now we have the data infrastructure to understand exactly what it costs to power it.

<Frame>
  <iframe />
</Frame>

## Dashboard Advanced Layout Improvements

*`James Bueche · Dashboards`*

A rundown of several quality-of-life improvements to Omni's Advanced Layout editor: dynamic font sizing for KPI tiles, better sibling element selection, a new spacebar shortcut to prevent accidental nesting while dragging, arrow key support in resize inputs, a persistent field picker, and a batch fix for \~30 accessibility issues across the dashboard.

<Frame>
  <iframe />
</Frame>

## Connected Services & Integrations

*`Jared Hardy · MCP Administration`*

A demo of Omni's new integrations tab, now rolling out behind a feature flag. Customers can now connect external tools like Slack, GitHub, and Google Calendar directly to their Omni profile via OAuth. We also discuss the path forward — API wrappers vs. MCP, customer-driven extensibility, and what it took to ship the first four integrations.

<Frame>
  <iframe />
</Frame>

## Dashboard Building WIP

*`Gustav Staprans · Dashboards AI`*

An early look at work-in-progress AI tooling for dashboard editing in Omni. New tools let the AI search the dashboard for context before acting, change queries and visualizations simultaneously, and apply filters — all from natural language. Also includes a discussion on whether AI-driven dashboard building could eventually work entirely outside the UI.

<Frame>
  <iframe />
</Frame>

## DBT API Endpoints

*`Buck Ryan · dbt API`*

A demo of new DBT API endpoints in Omni, covering config management, environment creation/update, and exposures. The highlight is a full end-to-end workflow for customers with dynamic DBT environments: a pull request triggers automatic environment creation in Omni, schema setup in the warehouse, and full cleanup on close — all via GitHub Actions calling the new API.

<Frame>
  <iframe />
</Frame>

## Editing in AI Split View

*`Gustav Staprans · AI Dashboards`*

Demo of a new editing mode in Omni's Split View. When you enter edit mode, the AI picks up that context and can use dashboard editing tools — rearranging tiles, adding filters, and updating charts — all while you're looking at the live dashboard. We also discuss performance tradeoffs and what's coming next for making AI-driven edits faster.

<Frame>
  <iframe />
</Frame>

## AI Split View Performance

*`Gustav Staprans · AI`*

A quick look at a small but meaningful UX improvement to Split View in Omni. Opening and closing dashboard tiles now shows an incremental loading state and closes immediately — making navigation between split view and chat feel noticeably snappier. Shipping early next week.

<Frame>
  <iframe />
</Frame>


# April 24, 2026
Source: https://docs.omni.co/demos/2026/20260424

Blobby Vibe Codes an AI App (HTML Dashboards), Tons of Content Validator, Dynamic Session Length, and Tons of Vis (AI Vision, Slackbot Vis, and More Layers Work

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby Learns HTML App Building

*`Nathan Agrin · AI Dashboarding The Future`*

The blob is getting unleashed.  A first look at single-prompt full HTML application building in Omni.  Think governed queries through the semantic layer, but an entirely open, sandboxed front-end for building anything you can imagine using HTML and CSS.  The idea is to pair unbounded vibe coded apps next to traditional dashboards.  Plus lots of discussion about the future here.  Bring the vibes.

<Frame>
  <iframe />
</Frame>

## Visualization Layers

*`Rob Miller · Visualization`*

Continuing our work to introduce more flexible multi-series visualization

<Frame>
  <iframe />
</Frame>

## Content Validator Scans

*`Mariel Freyre · Content Validator Modeling`*

We added some new functionality to the content validator called 'scans'.  Now can run async validation processes.  Would love to hear your thoughts.

<Frame>
  <iframe />
</Frame>

## Semantic Layer Visualizer

*`Bernard Sanders · Modeling`*

More work on ERDs and interactive experience for understanding the semantic layer.

<Frame>
  <iframe />
</Frame>

## CLI V1 Updates

*`Nathan Agrin · CLI Modeling Administration`*

Bunch of CLI work - some type ahead improvements and bunch of work on parameterization.  In addition, have table formats alongside JSON outputs.

<Frame>
  <iframe />
</Frame>

## Allow Scheduler to Hit Cached Results

*`Jonathan Swenson · Scheduler`*

Now you can optionally have the scheduler hit the cache.

<Frame>
  <iframe />
</Frame>

## Data Labels Sparseness Controls

*`Nathan Agrin · Visualization`*

Some new tooling to control sparseness of your data labels.

<Frame>
  <iframe />
</Frame>

## DB Connection UX

*`Nathan Agrin · Administration`*

Some improvements to ergonomics for the DB connection page.  Also a first foray into Claude Design.

<Frame>
  <iframe />
</Frame>

## AI Vis Quality

*`Dan Mosora · AI Visualization`*

We're giving Blobby some eyeballs - an ability to visually understand what was built and make decisions about how to improve.

<Frame>
  <iframe />
</Frame>

## Content Validator Dashboard Filters

*`Mariel Freyre · Content Validator Modeling`*

Adding more brains to the content validator to make sure we handle dashboard filters well.  Want to make sure we can get to fully automated administration of your content system.

<Frame>
  <iframe />
</Frame>

## Bunch of Docs Claude Skills

*`Erin Cochran · Docs AI MCP`*

A bunch of new Claude skills for docs improvements.  First a skill for building more extensive modeling examples (ie tons of parameters, filters, etc).  The second example is for finding holes in the docs and bulking em up.  A third is for calling Omni skills from the MCP.

<Frame>
  <iframe />
</Frame>

## Slack Bot Chart Rendering

*`Nathan Agrin · Visualization AI Slackbot`*

Bringing the full power of Omni visualization to the Slackbot.

<Frame>
  <iframe />
</Frame>

## Adjust Omni Session Length

*`Christopher Merrick · Administration`*

Title says it all - now you can set session length in Omni if you want to lengthen or shorten.

<Frame>
  <iframe />
</Frame>

## Removing Unused Model Content in Dashboard

*`James Davidson · Modeling Administration`*

We're building tools to keep your workbook models clean.  Now you can purge out unused workbook model changes to make sure you aren't bringing around old, dated code you don't need.  All about keeping your back-end clean over time.

<Frame>
  <iframe />
</Frame>


# May 1, 2026
Source: https://docs.omni.co/demos/2026/20260501

Lots of Dashboard Work (Run Button, Moveable Filer Work, Timezone Controls), Slackbot Dashboards, Plus Tons of UX Throughout the App

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Dashboard Tabs & Reordering

*`Luke Bowerman · Dashboards`*

Reorder tabs in multi-page dashboards directly from the sidebar, and customize labels independently from page names. You can also set link targets and forward filter params to link dashboards together.

<Frame>
  <iframe />
</Frame>

## Page Tooltips from Descriptions

*`Luke Bowerman · Dashboards`*

Page descriptions now appear as tooltips when hovering over dashboard tabs and inline navigation elements. A small quality-of-life improvement to help viewers understand what each page contains.

<Frame>
  <iframe />
</Frame>

## Account-Wide Custom Error Messages

*`Luke Bowerman · Dashboards`*

Set a default custom error message and "no results" presentation that applies across all dashboards in your organization. Previously this had to be configured per-dashboard.

<Frame>
  <iframe />
</Frame>

## Dashboard Run Button

*`Luke Bowerman · Dashboards`*

Early prototype of a run button for dashboards — powered by adding autorun to your model. Lets viewers manually trigger query execution, with plans to support placement anywhere on the page in advanced layout.

<Frame>
  <iframe />
</Frame>

## Delete & Restore Documents

*`Luke Bowerman · Dashboards Administration`*

When navigating to a deleted document, Omni will now show you the document name and offer a one-click restore instead of a plain 404. Also covers upcoming auto-archiving of support-created documents on customer instances.

<Frame>
  <iframe />
</Frame>

## Advanced Layout Titles & Subtitles Work

*`Meredith Dodge · Dashboards`*

Query title items in advanced layout now have dedicated fields for title, subtitle, and AI-generated text — no more mustache variables in a markdown editor. Also covers new resize handles on stack containers and text alignment controls.

<Frame>
  <iframe />
</Frame>

## Moveable Filters / Filter Bar in Advanced Layout

*`Alisa Tatarinova · Dashboards Filters`*

Upgrading a dashboard to advanced layout now fully integrates the filter bar as a native layout element. Filters can be styled, dragged into tiles, and hidden — with a new hidden filters section for easy access.

<Frame>
  <iframe />
</Frame>

## Blobbreaker Conference Leaderboard Embed

*`Alisa Tatarinova · Fun`*

A custom Blockbreaker game built for an upcoming conference uses Omni as its live leaderboard via embed. The leaderboard is a markdown visualization with a hidden filter driven by the URL, updating in real time as scores come in.

<Frame>
  <iframe />
</Frame>

## Workbook Shortcuts & Query Views

*`Luke Bowerman · Workbook`*

New keyboard shortcut to collapse/expand all in the workbook, a quick-jump button to edit topics, smarter auto-generated query view names to avoid collisions, and a warning when switching tabs with unsaved topic changes.

<Frame>
  <iframe />
</Frame>

## Date & Number Column Formatting

*`Luke Bowerman · Workbook`*

New formatting options for date and number columns are now available directly in the results view — no more manual HTML. Formatting also detects your locale and applies EU conventions automatically where appropriate.

<Frame>
  <iframe />
</Frame>

## Edit View Drawer

*`Luke Bowerman · Workbook`*

A new edit view drawer lets you set labels, descriptions, and hidden fields directly from the explore UI without jumping to the workbook. Hidden fields are visible and recoverable right in the drawer.

<Frame>
  <iframe />
</Frame>

## Split View UI Redesign

*`Gustav Staprans · AI`*

A design refresh for split view that reclaims dead header space — chat now extends to the top of the screen, the profile icon floats contextually, and the dashboard header is restored with sharing and edit controls inline.

<Frame>
  <iframe />
</Frame>

## Time Zone Overrides

*`Conrad Slimmer · Dashboards Administration`*

A new content permission lets viewers switch time zones directly on dashboards and workbooks via a time zone picker. The selected time zone can be pinned in a shared URL so recipients see consistent data regardless of their local settings.

<Frame>
  <iframe />
</Frame>

## Always Scope View Names

*`Conrad Slimmer · Modeling`*

A new connection setting that fully scopes view names with their catalog, reducing ambiguity when working with multi-catalog databases or shared models with different default catalogs. Will be the default for newly created connections going forward.

<Frame>
  <iframe />
</Frame>

## Refresh Schema Permissions for Modelers

*`Conrad Slimmer · Administration Modeling`*

Modelers can now refresh schema without needing connection admin rights — automatically granted when there's only one shared model under a connection. A stepping stone toward making refresh schema a fully granular permission.

<Frame>
  <iframe />
</Frame>

## dbt Docs Update

*`Rebecca Bruggman · Docs dbt`*

Five new dbt integration docs and 52 new FAQs added this quarter, covering virtual schemas, Git workflows, constraints and deferrals, schema refresh behavior, and health check debugging.

<Frame>
  <iframe />
</Frame>

## Slackbot Dashboard Building & AI Jobs API

*`Corey Ruderman · Slackbot API Dashboards`*

Ask Omni's Slackbot to build a full dashboard from a natural language prompt — powered by the AI Jobs API, which means the same capability is also available programmatically via API and CLI for agentic workflows and bulk migrations.

<Frame>
  <iframe />
</Frame>


# May 8, 2026
Source: https://docs.omni.co/demos/2026/20260508

More HTML Dashboard Progress, Vis Layers and Multi-Measures, Lots of Dashboard Work (Filters, AI Summary Tiles), Plus Some Benchmarking on AI Quality, Speed, and Cost

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## dbt Environment Visibility Fix

*`Buck Ryan · dbt`*

Fixes a bug where users couldn't see environments owned by others when selecting a branch environment; now all environments are visible and grouped by owner type.

<Frame>
  <iframe />
</Frame>

## Deferred dbt Environments

*`Buck Ryan · dbt`*

New feature that lets a development environment defer to production for any views that don't match a locally-built dbt model, with a visual indicator highlighting which schemas are in the dev environment.

<Frame>
  <iframe />
</Frame>

## AI Split View Draft Mode

*`Gustav Staprans · AI `*

Demo of AI entering draft mode on a published dashboard and making chart type changes (e.g. switching to line charts) without the user manually entering edit mode first.

<Frame>
  <iframe />
</Frame>

## Forecasting Improvements

*`Trip Tate · Dashboards AI Visualization`*

Forecasting now queries at a daily grain to build a current-period forecast before stepping up to the output grain, and joins back forecast values for better visualization rather than using a chart overlay.

<Frame>
  <iframe />
</Frame>

## Blobby Dashboard Summary Tile

*`Trip Tate · Dashboards`*

Blobby Builds Dashboards now supports automatically including an AI-generated summary tile alongside charts in a dashboard plan.

<Frame>
  <iframe />
</Frame>

## Dynamic Connection Environments

*`Trip Tate · Dashboards`*

Refinements to the dynamic connection environments feature, including how manual environment assignments work alongside user attributes, a self-referential base environment, and scheduler integration to run schedules against a chosen environment.

<Frame>
  <iframe />
</Frame>

## Multi-Button Toggle Filter

*`Alisa Tatarinova · Dashboards`*

Adds support for a multi-button toggle group on string filters, allowing users to select multiple values from a button group instead of a single toggle.

<Frame>
  <iframe />
</Frame>

## Pinned Filter Bar

*`Alisa Tatarinova · Dashboards Filters`*

Dashboard setting to pin the filter bar so it stays visible while scrolling; includes a discussion about mobile behavior.

<Frame>
  <iframe />
</Frame>

## World Cup Bracket Challenge

*`Peter Whitehead · Visualization Dashboards Fun`*

Preview of a fun internal Omni-powered World Cup bracket app with data-driven insights, head-to-head match history, and drill-through dashboards for each team.

<Frame>
  <iframe />
</Frame>

## Layers and Multiple Measures

*`Rob Miller · Visualization`*

Work-in-progress feature allowing multiple measures to render in their own independent layers, with improved legend behavior and the ability to split individual measures by a dimension without affecting other layers.

<Frame>
  <iframe />
</Frame>

## Custom Homepage Dashboard

*`Bernard Sanders · Administration Dashboards`*

New global (and per-user) setting to replace the default Omni homepage with any dashboard; also supports passing as a URL parameter for embed via user attributes.

<Frame>
  <iframe />
</Frame>

## Instance Creation Admin Tool

*`Brian Frantz · Internal`*

New internal admin tool at admin.omniapp.co that lets any team member self-serve the creation of new Omni instances across AWS and Azure regions, replacing the previous ops-ticket process.

<Frame>
  <iframe />
</Frame>

## Dashboard Filter Overload Helper

*`James Davidson · Filters Dashboards`*

Quick UI helper that surfaces all filters already applied to a tile directly from the dashboard, making it easy to overload or sync filters without hunting through large field lists.

<Frame>
  <iframe />
</Frame>

## Default Connection Setting for AI

*`Gustav Staprans · AI Administration`*

Adds the ability to set a default connection in the AI chat interface, so users land on their preferred connection rather than having to switch manually each session.

<Frame>
  <iframe />
</Frame>

## Dashboard Filter Workbook Context

*`James Davidson · Filters Dashboards`*

Companion to the filter overload helper — when editing a tile's workbook, surfaces dashboard-level filters as recommended additions so filter state stays in sync between the dashboard and workbook.

<Frame>
  <iframe />
</Frame>

## LLM Benchmarking Omni vs Claude vs Cortex

*`Colin Zima · AI Data`*

Presents preliminary results from a rigorous internal benchmarking framework comparing Omni's AI query quality, cost, and speed against Claude (three configurations) and Snowflake Cortex — Omni leads on all three dimensions.

<Frame>
  <iframe />
</Frame>

## AI Viz Bug Fixes and Improvements

*`Nathan Agrin · Visualization AI`*

Several AI viz fixes: KPI tiles now show a recoverable error state instead of crashing, org color palette is now respected by the AI viz API, a new auto-viz parameter applies heuristic-based chart generation, and legend/margin rendering is improved for long legends.

<Frame>
  <iframe />
</Frame>

## Google Sheets App Script Integration

*`Bernard Sanders · Export Google Sheets`*

A shareable Apps Script that adds an Omni menu item to Google Sheets, allowing users to sync data from multiple Omni dashboard tiles into specific sheet locations — built in response to a Looker competitive gap.

<Frame>
  <iframe />
</Frame>

## Slack Bot Feedback Buttons

*`Eli Cohen · Slackbot AI`*

Adds inline thumbs-up/thumbs-down feedback buttons to Omni AI responses in Slack, with a follow-up form for additional detail, feeding results into the analytics feedback tracking system.

<Frame>
  <iframe />
</Frame>

## Dashboard Filter Opt-In

*`Meredith Dodge · Dashboards`*

Feature-flagged change that lets users toggle a filter to stop auto-applying to newly added queries, switching from the current opt-out model to an explicit opt-in model for more controlled filter scoping.

<Frame>
  <iframe />
</Frame>

## Markdown / HTML App Rendering

*`Nathan Agrin · Dashboards AI`*

Proof-of-concept for higher-fidelity Omni app rendering using MDX (Markdown + JSX/React), enabling reusable components, dynamic filters, and Omni theme integration within embedded apps.

<Frame>
  <iframe />
</Frame>

## Measure Name, Measure Values for Charts

*`Rob Miller · Visualization`*

New functionality to facet different measures the same way you can with dimensions using dynamic measure-name, measure-value tokens.

<Frame>
  <iframe />
</Frame>


# May 15, 2026
Source: https://docs.omni.co/demos/2026/20260515

AI Hub - Model Learning, Evals, Analytics for AI Development - Plus More Vibe Coded Dashboards, Input Columns, Omnikit API Tooling, and Mobile App

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Input Columns

*`Arielle Strong · Input Columns Spreadsheets Dashboards`*

Beta feature allowing users to add interactive input columns to dashboards, enabling value editing that triggers query reruns and updates dependent charts in real time.

<Frame>
  <iframe />
</Frame>

## Vibe Apps

*`Arielle Strong · Dashboards AI`*

Showcase of bespoke, code-driven apps built on Omni's semantic layer using Blobby — including infographics, interactive scenario adjusters, a Price is Right game, and a Snake game powered by live employee roster data.

<Frame>
  <iframe />
</Frame>

## AI Suggestions & Iterative Learning

*`Chris Swenson · AI Modeling`*

Demo of the full AI suggestion pipeline running on real Omni instance feedback data — automatically generating model improvement suggestions in the background and implementing them via the IDE modeling flow.

<Frame>
  <iframe />
</Frame>

## AI Hub

*`Chris Swenson · AI`*

Walkthrough of AI Hub, a new central landing page for AI configuration, analytics dashboards, and quality monitoring.

<Frame>
  <iframe />
</Frame>

## AI Evals

*`Joel Dodge · AI Modeling Evals`*

Prompt set benchmarking, branch comparisons, and judge scoring for all your AI building.

<Frame>
  <iframe />
</Frame>

## Schema Refresh & Model Navigation

*`Conrad Slimmer · Modeling`*

Quality-of-life improvements including hard vs. soft schema refresh support for scheduled/API refreshes, a model navigation dropdown between schema and shared models, YAML-based topic ignoring, and content validator topic replacement by label.

<Frame>
  <iframe />
</Frame>

## Timezone Overrides

*`Conrad Slimmer · Dashboards`*

New timezone picker added to the download and schedule dialogs, allowing users to specify the output timezone for exported files and scheduled deliveries.

<Frame>
  <iframe />
</Frame>

## Dashboard Preview & Split View

*`Gustav Staprans · AI Dashboards`*

Updated dashboard creation chip UI and new split view controls allowing users to go full-screen on either the chat or dashboard, with the chat sidebar persisting for easy navigation.

<Frame>
  <iframe />
</Frame>

## Markdown Waterfall Charts

*`Sarah Waterson · Visualization`*

Examples of waterfall charts built using markdown and calculated fields, supporting positive/negative coloring, dynamic sorting, custom labels, and varying numbers of stages.

<Frame>
  <iframe />
</Frame>

## OmniKit (API Toolkit)

*`Austin Aranda · API Workflow`*

Open-source admin console built on the Omni API that enables non-technical users to migrate dashboards between models, bulk move/copy/delete content, download exports, and generate PowerPoint presentations with native or Omni visuals — including a batch slicer feature.

<Frame>
  <iframe />
</Frame>

## Model Extends & Fully Resolved View

*`Cathy Lennon · Modeling`*

New "fully resolved" toggle in the model editor that shows the complete composition of a base model and all its extensions layered together, making it easier to understand inherited topics, views, and fields.

<Frame>
  <iframe />
</Frame>

## AI Agent Filter Editing

*`James Bueche · Dashboards`*

New filter management tools exposed to the AI editing agent, enabling it to create, edit, and delete dashboard filters — demonstrated by adding a filter by bike type to a bicycle trip dashboard.

<Frame>
  <iframe />
</Frame>

## ReviewBot & Doc Tooling

*`Erin Cochran · Docs`*

Interactive Claude Code skill that walks users through doc review suggestions one batch at a time, showing previews of proposed changes, letting users selectively apply them, and tracking applied vs. outstanding items in the review file.

<Frame>
  <iframe />
</Frame>

## Omni iPhone App Preview for Blobby

*`James Davidson · Mobile AI`*

A first look at the upcoming AI-focused Omni mobile app.  Making it easier to Blobby.

<Frame>
  <iframe />
</Frame>


# May 22, 2026
Source: https://docs.omni.co/demos/2026/20260522

More Vibe Apps, Vis, AI Progress Throughout the App + Model Branches in the URL

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Blobby UX

*`Gustav Staprans · AI`*

New plus menu replacing crowded input box buttons (connection selector, topic selector, file attachment), plus improved mobile-friendly layout that scales cleanly on small screens.

<Frame>
  <iframe />
</Frame>

## Compute Routing

*`Conrad Slimmer · Modeling`*

New `compute_routing` model parameter for Snowflake, Databricks, and BigQuery that lets you route AI queries to specific warehouses/slot reservations to avoid slowing down dashboards.

<Frame>
  <iframe />
</Frame>

## Branch ID in URL

*`Conrad Slimmer · Modeling`*

Branch ID now persists in the URL so sharing a link takes the recipient directly to the same branch. Includes improved branch schema navigation in the IDE.

<Frame>
  <iframe />
</Frame>

## Blobby Dashboard - Delete Filters

*`Trip Tate · Dashboards`*

Blobby can now delete dashboard filters (previously create-only), enabling filter editing via delete + recreate.

<Frame>
  <iframe />
</Frame>

## Blobby Dashboard - Linked Tabs

*`Trip Tate · Dashboards`*

Blobby now understands three duplication modes: same tile in two places, linked tab (shared query/different viz), and cloned with modified query.

<Frame>
  <iframe />
</Frame>

## AI Hub - Suggestions UI

*`Chris Swenson · AI`*

Polished up suggestions page, plus added citations for chats used to generate suggestions.

<Frame>
  <iframe />
</Frame>

## Email Image Width

*`Luke Bowerman · Deliveries`*

Email images now scale to 100% of the email client width instead of a fixed 1400px, improving mobile rendering.

<Frame>
  <iframe />
</Frame>

## Preview Embed App Mode

*`Luke Bowerman · Embed`*

`preview_embed` now supports app=application to emulate application mode, not just single-content mode.

<Frame>
  <iframe />
</Frame>

## YAML Links Target Support

*`Luke Bowerman · Modeling`*

`links` param now support explicit target values (e.g. `target: self`) instead of always defaulting to blank/new window.

<Frame>
  <iframe />
</Frame>

## Dashboard Add and Catalog UX

*`Luke Bowerman · Dashboards`*

Dashboard editor now shows a notification when content will be inserted inside a selected item, for both "Add New" and the catalog. Click to clear the selection if undesired.

<Frame>
  <iframe />
</Frame>

## Model Search Filter

*`Luke Bowerman · UX`*

New auto-focused search and connection filter when creating or browsing models in the IDE, workbook chat, and develop views — useful for orgs with large model collections.

<Frame>
  <iframe />
</Frame>

## Dashboard Preview Mode

*`Luke Bowerman · Dashboards`*

New preview mode in the dashboard editor lets you interact with a draft as if published (drill, mobile view, zoom) before going live.

<Frame>
  <iframe />
</Frame>

## Personal Content Role

*`Luke Bowerman · Admin`*

New model role to disable personal/My Content for specific users, keeping everything hub-only for orgs that require it. Configurable per user via custom roles.

<Frame>
  <iframe />
</Frame>

## PR Review Board Tool (internal)

*`Nate Agrin · DevOps`*

Internal Kanban-style board for managing PR reviews with AI-powered triage — summarizes verbose PR descriptions, identifies starting points in the code, and tracks review state.

<Frame>
  <iframe />
</Frame>

## Vega Axis Tick Fix

*`Nate Agrin · Visualizations`*

Fix for a long-standing Vega-Lite bug where axis ticks repeat when data ranges are very small.

<Frame>
  <iframe />
</Frame>

## Data App Builder

*`Nate Agrin · AI`*

Blobby can now build and iteratively edit data apps — create layouts, add maps, fix its own errors, and link directly to the workbook in edit mode.

<Frame>
  <iframe />
</Frame>

## AI Credit Controls

*`Elliot Park · Admin`*

Admin-configurable hard caps and downgrade thresholds for AI credit usage per org. When the cap is hit, new AI requests are blocked with a user-facing message.

<Frame>
  <iframe />
</Frame>

## Model History Performance

*`Cathy Lennon · Modeling`*

Model history page load times reduced from up to 18s (P95) to \~2s, and median from \~1s to \~400ms, via a series of backend query optimizations.

<Frame>
  <iframe />
</Frame>

## Blobby Visualization Feedback and Tree Map Updates

*`Dan Mosora · Visualizations`*

A two pack of videos.  First, a tool to provide feedback on AI visualizations so we can keep improving the hueristics.  Next, more work on treemap vis to add more bells and whistles.

<Frame>
  <iframe />
</Frame>


# May 29, 2026
Source: https://docs.omni.co/demos/2026/20260529

More Vibe Apps, Git Blame, Dynamic Dashboard Filters, Xlookup Drill, Calc Pushdown, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Single Value Viz

*`Nathan Agrin · Visualization`*

Bug fixes and new features for the single value viz type, including font size controls and color options.

<Frame>
  <iframe />
</Frame>

## Blobby App Builder

*`Nathan Agrin · AI Dashboards`*

Improvements to Blobby's AI app generation — coherent in-place editing, dark mode styling, and a new side-by-side UI.

<Frame>
  <iframe />
</Frame>

## Blobby ERD Diagram

*`Keegan Cianfrone · Dashboards Use Cases`*

Using Blobby as a Vibe coding tool to generate an interactive ERD diagram for the analytics model, complete with expandable field dropdowns.

<Frame>
  <iframe />
</Frame>

## Dynamic Dashboard Filters

*`Alisa Tatarinova · Dashboards Filters`*

New dashboard control that lets viewers add ad hoc filters across any available field without pre-configuration by the dashboard creator.

<Frame>
  <iframe />
</Frame>

## Blobby Undo

*`James Bueche · Dashboards`*

Blobby-specific undo/redo history stack that tracks and reverses AI-made dashboard changes independently of manual edits.

<Frame>
  <iframe />
</Frame>

## Markdown Columns

*`Jess Gaines · Visualization Use Cases`*

Demo of what's now possible with GA'd Markdown columns — rich embedded portal examples that feel more like full applications.

<Frame>
  <iframe />
</Frame>

## AI Hub Sentiment Analysis

*`Jade Khiev · AI Administration`*

New dataset tracking sentiment on Blobby user prompts, live in the internal Omni instance, with AI able to identify frustration even in multiple languages.

<Frame>
  <iframe />
</Frame>

## Blobby Model Switching

*`Gustav Staprans · AI`*

Blobby can now dynamically switch between models to find the best one to answer a question, reducing the need to manually select a connection or model.

<Frame>
  <iframe />
</Frame>

## Blobby Dashboard Summary

*`Gustav Staprans · AI Dashboards`*

Blobby can now open a dashboard and describe what's on it, with plans to chain this with dashboard search for a fully automatic workflow.

<Frame>
  <iframe />
</Frame>

## Model History

*`Cathy Lennon · Modeling`*

New annotated model file history UI showing who changed what and when, with hover details and links to the full commit history page.

<Frame>
  <iframe />
</Frame>

## YAML Serialization Back-end Migration

*`Cathy Lennon · Performance`*

Internal PSA — moving YAML parsing from front end to back end for performance gains, with a diff tool to catch serialization inconsistencies before rollout.

<Frame>
  <iframe />
</Frame>

## XLOOKUP Calc Drills

*`Steven Talbot · Workbook Dashboards`*

Drill support added for Xlookup calcs, allowing users to drill into the source query of an Xlookup reference directly from a chart or table.

<Frame>
  <iframe />
</Frame>

## Calc Row Limit Push Down

*`Steven Talbot · Workbook Dashboards`*

New option to push calc aggregations (sum, rank, etc.) across all rows beyond the row limit, with a model-level parameter to set this as the default behavior.

<Frame>
  <iframe />
</Frame>

## Scheduled AI

*`Corey Ruderman · Ai Scheduler`*

Early demo of scheduling AI skills and prompts on a cadence, with results delivered to email or Slack — anything you can do in-app can be scheduled.

<Frame>
  <iframe />
</Frame>

## SQL Editor Improvements

*`Christopher Merrick · SQL Workbook`*

Better SQL autocomplete — table names now load without expanding schemas, plus improved column awareness with table-context boosting.

<Frame>
  <iframe />
</Frame>


# June 5, 2026
Source: https://docs.omni.co/demos/2026/20260605

More Vibe Apps, AI Evals, More Dashboard Improvements, Markdown Column Promotion, and Sub-Agents

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI Customer Evals

*`Joel Dodge · AI Modeling`*

GA release of the AI hub eval framework — create prompt sets, run evals against different model branches (shared, fastest, smartest), and compare results side-by-side with an AI judge scoring accuracy.

<Frame>
  <iframe />
</Frame>

## AI Tracing & Observability

*`Joel Dodge · AI Modeling`*

Internal tool for super/support users to inspect every LLM call Blobby makes - view full system prompts, tool definitions, parallel tool calls, and nested sub-agent spans in a collapsible trace drawer.

<Frame>
  <iframe />
</Frame>

## AI Chat UI Cleanup

*`Gustav Staprans · AI`*

Bottom bar declutter (topic chip + subtle model/connection display) and replacement of the split-view sidebar with inline header tabs for chat history, fixing nested-sidebar issues and enabling future left/right panel positioning.

<Frame>
  <iframe />
</Frame>

## Dashboard Agent Tab Cleanup

*`Trip Tate · Dashboards AI`*

Blobby can now delete unused workbook tabs on command, with protection against removing tabs that are the source of linked/cross-tab calculations.

<Frame>
  <iframe />
</Frame>

## Sub-Agent Orchestration

*`Trip Tate · AI`*

Proof-of-concept showing the main agent invoking a sub-agent via tool call to offload complex work (e.g. dashboard creation), keeping the main context clean and enabling iterative replanning when queries fail mid-flow.

<Frame>
  <iframe />
</Frame>

## History Filter by File

*`Conrad Slimmer · Modeling`*

New filter on the version history view to show only commits where a specific file changed — speeds up binary-search debugging when tracking down when a model or view was modified.

<Frame>
  <iframe />
</Frame>

## Color Calculation Fix

*`Jared Hardy · Design UX`*

Bug fix for incorrect light/dark contrast calculation on custom chart colors — dynamic color previews now update correctly as users change positive/negative palette settings.

<Frame>
  <iframe />
</Frame>

## Dashboard Advanced Layout Alignment Helpers

*`Jared Hardy · Dashboards`*

New alignment guides (red snap lines) for items within the same container layer, including half-size snapping, plus in-progress ruler/column-count indicators to help size and align elements without the properties panel.

<Frame>
  <iframe />
</Frame>

## AI Model Suggestions

*`Jade Khiev · AI Modeling`*

AI-generated suggestions for improving topic AI context, now with diff view (not full rewrites), sentiment-aware quality signals, scheduled daily runs at 2 AM, and upcoming ignore/reject feedback loop.

<Frame>
  <iframe />
</Frame>

## Apps Data Storage Restructure and Generation Improvement

*`Nathan Agrin · Apps AI`*

Major structural rewrite — apps now stored like dashboards (own data table), query generation delegated to existing query tools, Blobby can self-fix rendering issues from screenshots, improved security envelope, and apps now appear in the content/permission system.

<Frame>
  <iframe />
</Frame>

## Markdown Column Promote

*`TJ Banghart · Workbook Modeling`*

New "Promote" button on markdown column vis configs to save the current formatting back to the workbook as the model default, with a "Revert to model definition" option to undo.

<Frame>
  <iframe />
</Frame>

## Top N Control

*`TJ Banghart · Modeling Workbook`*

Users can now change the Top N value directly in the viz without it being locked to the modeled default, including optional min/max bounds — works on both workbooks and dashboards.

<Frame>
  <iframe />
</Frame>

## Dashboard API V2

*`Luke Bowerman · Dashboards`*

New breaking-change PATCH endpoint for programmatically editing dashboards — supports targeting a specific draft or published doc, partial updates (send only what changed), explicit null to delete elements, and AI-generated history summaries.

<Frame>
  <iframe />
</Frame>

## AI Tool Disable Controls

*`James Davidson · AI`*

Per-model setting to selectively disable specific Blobby tools (Viz, user memory, conversation learning) — reduces token cost and enables behavioral governance; integrated with the eval framework.

<Frame>
  <iframe />
</Frame>

## AI Skill Permissions

*`James Davidson · AI Administration`*

Skills can now be conditionally shown/hidden based on existing access grants — users without the required grant don't see the skill in the UI, effectively adding content-level permissions to skills.

<Frame>
  <iframe />
</Frame>

## Omni AI Native Markdown Context Demo

*`Nathan Agrin · AI Modeling`*

Testing enabling Markdown files directly in the model.  This is analogous to a CLAUDE.md file.  The goal here is to start testing how we can push Omni more into the AI first world.  In a future world you could imagine someone working with an OMNI.md file directly on the filesystem, talking to a headless Omni through Claude.

<Frame>
  <iframe />
</Frame>


# June 12, 2026
Source: https://docs.omni.co/demos/2026/20260612

Tons of Apps Examples, Improving the Evals Framework, Pixel Perfect First Look, Github App Support, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Invoice Reconciliation App

*`Joe Seib · AI Apps, Use Cases`*

Joe demos a Blobby-built app that compares vendor invoices against contract amounts, helping the finance team catch billing discrepancies before approving payments.

<Frame>
  <iframe />
</Frame>

## App Edit Flow and Draft-Publish

*`Meredith Dodge · AI, Apps`*

Product demo of improvements to the app editing experience — Blobby can now re-open and edit existing apps, a draft/publish flow with version history is coming, and a "query-first" workflow lets you build a workbook query and then generate an app from it.

<Frame>
  <iframe />
</Frame>

## Salesforce Pipeline App

*`Adrien Beaufils · AI Apps, Use Cases`*

Adrian demos a Blobby-built Salesforce deal analysis app with polished UI showing pipeline data, deal timelines, BDR notes, case studies, and direct links — built to fill gaps where Salesforce falls short for AEs and SEs.

<Frame>
  <iframe />
</Frame>

## GitHub App Git Integration

*`Conrad Slimmer · Git, Modeling`*

Demo of work-in-progress GitHub App-based authentication for Omni's Git integration, replacing SSH/HTTPS password auth and opening the door to future features like automated PR creation and status checks in the Omni UI.

<Frame>
  <iframe />
</Frame>

## Financial Balance Movement Pattern Docs

*`Conor O'Mara · Docs, Use Cases`*

A semantic layer query pattern for finance customers that correctly calculates opening balance, closing balance, and movement regardless of how dimensions are pivoted.

<Frame>
  <iframe />
</Frame>

## Omni Chrome Extension

*`Conor O'Mara · API, Apps`*

Conor demos an updated version of the internal Omni Chrome extension (new tab page) refreshed with the new brand guidelines — updated palette, greeting, links, and a Blobby hover animation.

<Frame>
  <iframe />
</Frame>

## AI Model Suggestion Ignore

*`Chris Swenson · Modeling, AI`*

Demo of a new feature giving users control over AI suggestion lifecycle — users can ignore suggestions with an optional reason, view ignored suggestions, and the AI uses the reason to avoid re-suggesting or to redirect its suggestion accordingly.

<Frame>
  <iframe />
</Frame>

## Thundra Multi-Instance Manager

*`Luke Bowerman · Internal Tools`*

Demo of Thundra, a rewritten internal dev tool for managing multiple concurrent local Omni instances — shows branch info, PR links, drag-and-drop branch checkout, and port distribution. Includes a PSA that V2 Document APIs are now shipped and will exit experimental status within the week.

<Frame>
  <iframe />
</Frame>

## App Builder Field Switcher Control

*`James Bueche · AI, Dashboards`*

Brief demo of new app builder capability to expose controls (starting with a field switcher) to the builder via the agent, allowing dynamic field switching to be added to apps.

<Frame>
  <iframe />
</Frame>

## AI Hub Eval Expected Behavior

*`Joel Dodge · AI, Evals`*

Demo of a new "expected behavior" column in AI Hub's eval UI — lets users provide a rubric or heuristic hint to the AI judge for evaluating prompt responses, with full API coverage shipping the same day.

<Frame>
  <iframe />
</Frame>

## Claude MCP to Blobby App Lift

*`Arielle Strong · AI, Dashboards`*

Demo of lifting a Claude-generated MCP dashboard (hard-coded HTML data) directly into Omni via Blobby — Blobby recreates the app with real semantic layer queries, making it shareable and maintainable. Also previews upcoming MCP tool support for creating Omni apps directly from Claude.

<Frame>
  <iframe />
</Frame>

## Pixel-Perfect Reports

*`Arielle Strong · Dashboards, Scheduler`*

Early preview of a new pixel-perfect report editor being built into Omni for print-ready outputs like bank statements, invoices, and regulatory reports — featuring headers, footers, repeating sections, live data connections, and page-splitting tables, built on a third-party banded report engine.

<Frame>
  <iframe />
</Frame>

## App Generation Streaming Feedback

*`Dan Mosora · AI, Apps`*

Demo of a quality-of-life improvement showing live token streaming in the app generation UI so users can see the agent working in real time rather than waiting silently, plus a fix for date axis rendering in generated charts.

<Frame>
  <iframe />
</Frame>

## App SDK Improvements

*`Nathan Agrin · AI, Apps, SDK`*

Roundup of app SDK improvements: a new "app" chip label distinguishing apps from dashboards, report reformatting capability, data refresh controls (with and without cache), number formatting fix for large integers, and security hardening across the app SDK.

<Frame>
  <iframe />
</Frame>

## Blobby Connection Setup

*`Nathan Agrin · Administration, AI`*

Demo of a resurrected feature (now built on Mythos) allowing users to create new database connections directly through a Blobby conversation — credentials are screened before reaching the LLM, and the connection is immediately live and queryable.

<Frame>
  <iframe />
</Frame>

## Engineering Activity App

*`Dan Mosora · Apps, Use Cases`*

A completed app showing engineering team activity (lines of code, commits, files touched) generated entirely by Blobby during the meeting, demoing the edit flow with live streaming updates as the app rewrites itself on edit.

<Frame>
  <iframe />
</Frame>


# June 19, 2026
Source: https://docs.omni.co/demos/2026/20260619

Scheduled AI, Pixel Perfect Getting Close, Agentic MCP, Notion MCP, Serialized Content Preview, and More!

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Scheduled AI Prompts Email Delivery

*`Corey Ruderman · AI Scheduler`*

Schedule AI prompts to run on a cadence and deliver summaries via email, with full CRUD API coverage and support for groups, custom models, and future destinations like Slack, S3, and PDF.

<Frame>
  <iframe />
</Frame>

## Notion Integration for Blobby

*`Jade Khiev · AI Notion`*

Connect your personal Notion account to Blobby via MCP to read, query, and write to Notion pages directly from chat — plus define Omni model skills to automate Notion writes against specific databases.

<Frame>
  <iframe />
</Frame>

## Suggestions Multi-Select

*`Chris Swenson · Modeling AI`*

Select all AI suggestions at once and implement or ignore them in bulk, rather than acting on each one individually.

<Frame>
  <iframe />
</Frame>

## Login Page SAML Cleanup

*`Luke Bowerman · Administration Design`*

Redesigned login page that lets admins disable the "Sign in with Google" button and toggle email link login off, leaving only SAML or OIDC as needed.

<Frame>
  <iframe />
</Frame>

## Embed UI Customization

*`Luke Bowerman · Embed`*

New UI settings object options for embeds — control whether the document breadcrumb is shown or linked, and hide the per-chart triple-dot context menu.

<Frame>
  <iframe />
</Frame>

## Topic Search Re-Pick

*`Luke Bowerman · Workbook`*

After selecting a topic, you can now search and switch to a different topic without leaving the page — useful for navigating large topic collections quickly.

<Frame>
  <iframe />
</Frame>

## Git Pull Requests for Content (Serialized Content Early Look)

*`Conrad Slimmer · Modeling Dashboards`*

Early POC of serialized document JSON committed to Git on publish — enables PR-based review workflows with diffs showing exactly what changed in workbook queries and document structure.

<Frame>
  <iframe />
</Frame>

## Dashboard Agent Source Tab Awareness

*`Trip Tate · Dashboards AI`*

The modeling agent now recognizes source tabs that aren't visible on the dashboard and correctly avoids cleaning them up as unused.

<Frame>
  <iframe />
</Frame>

## MCP Full Agent Access

*`Trip Tate · AI MCP`*

Expose the full Blobby agent via MCP so external clients like Claude Desktop can invoke open-ended analysis, dashboard building, and all other agent capabilities — not just query execution.

<Frame>
  <iframe />
</Frame>

## Dashboard Spacer Divider Placeholder Components

*`Luke Bowerman · Dashboards`*

Three new dashboard layout components: a draggable spacer, a configurable horizontal/vertical divider, and a placeholder tile for wireframing dashboards before queries are built.

<Frame>
  <iframe />
</Frame>

## Embed Architecture Dev Prod Guide

*`Rebecca Bruggman · Docs`*

New external documentation walking through a full dev/prod embed setup — architecture diagrams, instance configuration, permissions, and a pre-launch checklist.

<Frame>
  <iframe />
</Frame>

## dbt Decoded

*`Rebecca Bruggman · Docs`*

Internal 33-page guide to dbt in the context of Omni, covering key features, FAQs, modeling patterns, and customer conversations — plus a curated Omni Cloud project built from 300+ support tickets and 30 Fathom calls.

<Frame>
  <iframe />
</Frame>

## Blobby File Upload LookML XML HTML

*`Jade Khiev · AI Administration`*

Blobby now accepts LookML, XML, and HTML files via drag-and-drop — useful for migration workflows and dropping in Claude-generated HTML prototypes ahead of live apps.

<Frame>
  <iframe />
</Frame>

## Pixel Perfect Reporting AI Layout Generation

*`Richard Czechowski · Pixel Perfect Dashboards`*

Pixel-perfect reports now sit in the full dashboard/apps hierarchy with proper Chrome; AI can generate invoices, sales receipts, W-2s, and other structured documents from the RDLC schema with no manual layout work.

<Frame>
  <iframe />
</Frame>


# June 26, 2026
Source: https://docs.omni.co/demos/2026/20260626

AI Annotations GA, Tons of Apps Work, Scheduled AI (Routines), AI Debug Tools, Better SQL Autocomplete, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Deploy Health Dashboard and Observability

*`Kyle Speer · Internal Engineering`*

Kyle demos a new deploy health dashboard showing P90/P50 latency and error rates, plus CloudWatch anomaly detection and Slack DM notifications for each step of the deploy pipeline.

<Frame>
  <iframe />
</Frame>

## Blobby Debug Agent

*`Joel Dodge · AI`*

New debug tooling for Blobby chat sessions — a bug icon opens a side drawer with a dedicated debug agent that has full access to everything Blobby saw and did (excluding raw customer data), letting you ask why decisions were made or investigate unexpected outputs.

<Frame>
  <iframe />
</Frame>

## Claude MCP OmniDev Tracing

*`Joel Dodge · AI`*

Internal developer tooling using Claude Code with OmniDev as an MCP server to read trace/span data from Blobby sessions and reason about bugs — demoed against a case of three parallel tool calls returning identical AI explanations.

<Frame>
  <iframe />
</Frame>

## Apps Without Required Queries

*`Nathan Agrin · AI Apps`*

Nate demos the ability to create Omni apps with no associated queries, removing the previous friction of having to stub a query first before building an app UI.

<Frame>
  <iframe />
</Frame>

## App Syntax Error Fix

*`Nathan Agrin · AI Apps`*

A new "Fix This" button automatically detects and repairs syntax errors in app code — demoed by manually introducing a stray brace that breaks the app, then one-clicking to fix it.

<Frame>
  <iframe />
</Frame>

## App CSV Download and Sandbox Permissions

*`Nathan Agrin · AI Apps`*

Apps can now download data as CSV via a new Download button, enabled by amending the iframe sandbox attribute to include allow-downloads — plus a hint at upcoming writeback support for input data in apps.

<Frame>
  <iframe />
</Frame>

## Routines Slack Delivery

*`Corey Ruderman · AI Scheduler`*

Scheduled AI prompt routines (Blobby automations) can now deliver their output directly to a Slack channel or DM, with follow-up conversation available in the thread via the bot.

<Frame>
  <iframe />
</Frame>

## Session Sentiment Classification

*`Jade Khiev · AI Analytics`*

Batch sentiment classification of Blobby prompts and full chat sessions powered by Bedrock/Anthropic, with a lightweight app to browse per-prompt and per-session outcomes — intended to improve models and eventually expose analytics to customers.

<Frame>
  <iframe />
</Frame>

## App Targeted Edits

*`Dan Mosora · AI Apps`*

Instead of regenerating an entire 25K-token app document on every change, the app editor now sends edits as a series of small targeted chunks, visualized as a diff animation in the sidebar. TLDR; faster, cheaper edits.

<Frame>
  <iframe />
</Frame>

## AI Annotations

*`Chris Swenson · AI Workbook Dashboards Magic`*

Shipped/GA feature — a new Explain button lets users draw a shape on the canvas and send an annotated screenshot directly to Blobby, which uses a root cause analysis skill to respond.

<Frame>
  <iframe />
</Frame>

## Split View IDE AI

*`Chris Swenson · AI Modeling`*

Early work on split view support in the SQL IDE, replicating existing IDE AI capabilities (autocomplete, AI assist) in a split-pane layout — broader questions about entry points and modeling availability still being decided.

<Frame>
  <iframe />
</Frame>

## Animated Bubble Chart App

*`Russell Garner · Apps Use Cases`*

An app built in \~5 minutes using Omni's whitelisted charting libraries to replicate Hans Rosling's famous animated bubble chart, making time a meaningful axis for portfolio/project data visualization.

<Frame>
  <iframe />
</Frame>

## Data Delivery Domain Allow List

*`Eli Cohen · Scheduler Administration`*

Admins can now restrict which email domains Omni will deliver dashboard deliveries and routines to — if a recipient's domain isn't on the allow list, they're filtered out. Applies to user groups too.

<Frame>
  <iframe />
</Frame>

## Chat UI Skills Menu Consolidation

*`Peter Schrader · AI Design`*

The Blobby chat UI is being reorganized — skills collapse into a dedicated menu after first use to reclaim space, the bottom bar evolves into actionable items vs. configuration, and a scroll behavior fix keeps your messages in view after streaming completes.

<Frame>
  <iframe />
</Frame>

## SQL Autocomplete

*`Peter Schrader · Workbook SQL`*

Advanced SQL autocomplete now surfaces actual column names in the editor — works for joins, bare tables, and basic aliasing, covering \~80% of use cases; CTEs and subqueries are future work.

<Frame>
  <iframe />
</Frame>

## AI Hub Schema Toggle

*`Lei Tang · AI Modeling`*

A new core views/schema toggle in AI Hub setup lets admins selectively hide tables from Blobby's context, reducing noise for new connections with thousands of tables and solving the cold-start problem.

<Frame>
  <iframe />
</Frame>

## App Theme Variables

*`Meredith Dodge · AI Design`*

Omni org theme variables (primary button color, dark/light mode, etc.) are now injected into the app iframe so apps look seamless with the rest of Omni by default — with the option to opt out and use a custom theme.

<Frame>
  <iframe />
</Frame>

## Floating Blobby

*`Gustav Staprans · AI`*

A floating, draggable Blobby button is coming to workbook and dashboard views for globally consistent AI access — position persists on reload, and the chat open/close control is moving to the top header.

<Frame>
  <iframe />
</Frame>


# July 6, 2026
Source: https://docs.omni.co/demos/2026/20260706

Grab Bag of New Apps, AI Building Pixel Perfect Reports, Omni Semantics Live in Excel, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## App Demos Showcase

*`Various · AI Apps`*

A grab bag of new apps we've built to show off what's possible in the new framework.

<Frame>
  <iframe />
</Frame>

## Omni Semantic Layer in Excel (Headless Omni)

*`Christopher Merrick · Headless semantics Excel`*

A quick demo of using Omni as a headless semantic layer for work in Excel.  This enables all the richness of the Omni data model natively in Excel.

<Frame>
  <iframe />
</Frame>

## Sonnet 5 vs 4.6 Eval Results

*`Oliver Chang · AI`*

We did some testing of Sonnet 5 vs the current 4.6 set-up to understand quality impact, plus some discussion on developing open source LLM options.

<Frame>
  <iframe />
</Frame>

## AI Generated Pixel Perfect Reports

*`Richard Czechowski · AI Pixel Perfect`*

More progress on type a few words and get a perfectly formatted document.  This brings together query construction and layout for building printable documents from scratch in a single prompt.

<Frame>
  <iframe />
</Frame>

## Guiding Users to Their Omni Instance

*`Christopher Merrick · Administration`*

We built a little navigation to help you find your Omni environment without the URL.  Plus a router for folks with multi-instance setups.

<Frame>
  <iframe />
</Frame>


# July 10, 2026
Source: https://docs.omni.co/demos/2026/20260710

Monster Week - App Fine Tuning, Writeback, and Maps; Improved Filter Mapping, AI Scheduling, Mobile Dashboards, Dash on Homepage, and AI Calcs That Persist

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## App Demos

*`Various · AI Apps`*

Rapid-fire showcase of 10+ employee-built apps including a bar chart race, slam poetry generator, Omni access level trainer, job search tool, pharma benchmarking app, gaming shelf kiosk, support ticket feed, embed session network map, prediction market, agent CSAT explorer, claims explorer, ramp guide tracker, board deck builder, pipeline change skill, and a World Cup squad builder.

<Frame>
  <iframe />
</Frame>

## Mobile Dashboard Layouts

*`Luke Bowerman · Dashboards Mobile`*

Demo of improved mobile rendering for dashboards — automatic flex/wrap behavior and new per-tile controls to stack, wrap, or hide tiles on mobile without needing separate split layouts.

<Frame>
  <iframe />
</Frame>

## AI Calcs on Postgres

*`Richard Czechowski · AI Calcs`*

AI calcs running on Postgres via Bedrock, extending AI calc support beyond databases with native AI functions to any connected DB.

<Frame>
  <iframe />
</Frame>

## AI Calc Writeback

*`Richard Czechowski · AI Calcs Writeback`*

Demo of saving AI calc results as editable input columns — manually override labels, fill in blanks with AI, and preserve human edits on rerun.

<Frame>
  <iframe />
</Frame>

## MCP Server Settings

*`James Bueche · AI MCP Administration`*

New dedicated MCP settings page in the AI hub with granular sub-toggles for agentic capabilities, letting org admins enable/disable specific MCP tool sets including the richer agentic Ask Omni experience.

<Frame>
  <iframe />
</Frame>

## Dynamic Connection Environments

*`Trip Tate · Administration`*

New environment toggle in AI chat showing which database environment queries are running against, matching the existing workbook-level control.

<Frame>
  <iframe />
</Frame>

## Dashboard on Homepage

*`Trip Tate · Dashboards Administration AI`*

Dashboard embedded inline on the Omni homepage — no redirect, renders in place, with app-on-homepage support planned to follow.

<Frame>
  <iframe />
</Frame>

## Writeback in Apps

*`Nathan Agrin · AI Apps Writeback`*

Demo of Writeback — a simple to-do app persisting data to the server, queryable like a CSV or input column from within a workbook.  Raise your hand if you want this early.

<Frame>
  <iframe />
</Frame>

## Blobby Floating Buddy

*`Gustav Staprans · AI`*

Floating Blobby widget that persists across the app, remembers its position, pre-loads your last chat on open, and maintains split view as you navigate between dashboards and workbooks.

<Frame>
  <iframe />
</Frame>

## Activity Page Artifact Linking

*`Gustav Staprans · AI`*

Upcoming feature associating dashboards and analyses to the chat that created them, so reopening an artifact also reopens its originating chat.

<Frame>
  <iframe />
</Frame>

## Dashboard Filter Mapping Improvements

*`Alisa Tatarinova · Dashboards Filters`*

New ability to filter dashboard controls by page, plus a reverse view showing which filters and controls are applied to a given query — with locate-and-highlight and multi-select via shift-click.

<Frame>
  <iframe />
</Frame>

## Inspect and Annotate Mode for Apps (Claude Design for Apps)

*`Dan Mosora · AI Apps The Future`*

Work-in-progress browser-inspector-style edit experience for apps — click any element to push it into chat for AI editing, with annotation support for screenshots.  Next couple weeks for this one - huge step forward.

<Frame>
  <iframe />
</Frame>

## Blobby Scheduling

*`Eli Cohen · AI Export Scheduler`*

Blobby can now create scheduled AI routines — e.g. "email me a summary of Slack agent trends every Monday morning" — currently behind a flag.

<Frame>
  <iframe />
</Frame>

## Deliveries and Alerts Panel Improvements

*`Conor McGovern · Scheduler`*

Small enhancements to the deliveries and alerts panel: pagination, search/filter, and a send confirmation dialog.

<Frame>
  <iframe />
</Frame>

## App Builder Map Providers

*`Nathan Agrin · AI Apps`*

New app settings menu allowing app authors to add external map, image, and data source providers — starting with free/open-source options, with Mapbox/Google Maps support coming via user-provided keys. Also covers CSV/PDF export capabilities and upcoming filter-to-query wiring improvements.

<Frame>
  <iframe />
</Frame>


# July 17, 2026
Source: https://docs.omni.co/demos/2026/20260717

More AI Apps, Tons of Vis Work, Field Usage in the IDE, Improve dbt Development, More Extracts Work, and Multi-Connection Workbooks

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## App Super Demo

*`Various · AI Apps`*

A rapid-fire showcase of externally shareable Omni apps — contact center analytics, hospital network clinical drilling, event notes with PDF export, race car telemetry, automotive auction comparison, spin the wheel, data dictionary, pet boarding, high-value customer profiles, Omni AI architecture presentation, and GTM headcount planning.

<Frame>
  <iframe />
</Frame>

## IDE Usage Pane

*`James Davidson · Modeling`*

New pane in the Omni IDE showing which dashboards and fields reference a given object, enabling impact-radius analysis before making model changes.

<Frame>
  <iframe />
</Frame>

## Color Scale Pinning

*`Rob Miller · Visualization`*

Adds the ability to pin a midpoint value on quantitative color scales and clamp outliers, making diverging charts render more clearly across maps and other viz types.

<Frame>
  <iframe />
</Frame>

## Legend Interactivity on Multi-Measure Charts

*`Rob Miller · Visualization`*

Legend click-to-filter now works on multi-measure charts, not just single-measure ones.

<Frame>
  <iframe />
</Frame>

## Viz Layers Editor Preview

*`Rob Miller · Visualization`*

Preview of the new viz layers editor, allowing independent control of multiple series on a single chart — mix chart types, segment individual lines, create small multiples by measure, and more.

<Frame>
  <iframe />
</Frame>

## Blobby Web Search

*`Gustav Staprans · AI`*

New admin toggle to enable web search in Blobby, with sub-processor disclosure, feature flag requirement, and small per-search credit cost.

<Frame>
  <iframe />
</Frame>

## Blobby Chat Side Toggle

*`Gustav Staprans · AI UX`*

New toggle (and potential user attribute) to swap the Blobby chat panel from left to right, with header detail updates that follow the position change.

<Frame>
  <iframe />
</Frame>

## Blobby Response Folding

*`Peter Schrader · AI`*

Blobby now folds verbose research/tool-call steps (schema lookups, model searches) into a collapsed section, surfacing only the actionable result to reduce scrolling.

<Frame>
  <iframe />
</Frame>

## Blobby Query Generation Flags

*`Steven Talbot · AI Modeling`*

New admin flags to restrict Blobby's query generation — control whether it can use CTEs, custom fields, or restricted queries; intended as a safety valve, not a recommended default.

<Frame>
  <iframe />
</Frame>

## Filter by Query for Dates

*`Steven Talbot · Filters Workbook`*

Filter by query now works for date fields, using the date granularity of the source query to determine which values pass through.

<Frame>
  <iframe />
</Frame>

## Multi-Connection / Multi-Model Workbooks

*`Steven Talbot · Workbook Dashboards`*

Early preview of cross connection workbooks — query a field from a different model/database connection without leaving the current workbook, relaxing the single-shared-model constraint for final dashboards.

<Frame>
  <iframe />
</Frame>

## dbt Development Workflow

*`Buck Ryan · dbt`*

Centralized dbt IDE improvements: choose environment and Git branch in one place, auto-sync on save, inline validation errors with troubleshooting guidance, and the ability to ignore errors by directory.

<Frame>
  <iframe />
</Frame>

## Viz Label Series Color Matching

*`Mike Torosian · Visualization`*

New match series color option for chart data labels on bar, area, and line charts (Vega-based), automatically coloring each label to match its series.

<Frame>
  <iframe />
</Frame>

## Blobby Draft Mode on New Dashboard

*`Chris Swenson · AI Dashboards`*

When Blobby creates a new dashboard it now opens directly in draft mode, removing the extra step of manually switching before making edits.

<Frame>
  <iframe />
</Frame>

## Blobby Split View State Persistence

*`Chris Swenson · AI UX`*

The Blobby split view now remembers which content was open (workbook, IDE tab, etc.) when you return to a chat, restoring the previous right-panel state automatically.

<Frame>
  <iframe />
</Frame>

## Composite Topics GA

*`TJ Banghart · Modeling Workbook`*

Composite topics are now generally available with no feature flag — supports AI context, field directives, and AI chat; joins two topics on shared dimensions or views behind the scenes.

<Frame>
  <iframe />
</Frame>

## Topic-Level Extracts

*`TJ Banghart · Modeling Extracts Dashboards`*

Early-stage extract caching at the topic level using DuckDB/Duck Lake — curate a topic's fields into a flat extract and generate a pre-warmed cache keyed to default filters and user attributes for fast dashboard loads.

<Frame>
  <iframe />
</Frame>


# July 24, 2026
Source: https://docs.omni.co/demos/2026/20260724

Schedule and Alerts for AI, More Pixel Perfext, App Fine Tuning, Dashboard Run Botton, Open Source AI Testing, Apps on Homepage, Measure Trellising, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Apps Demos

*`Various · AI Apps`*

The full apps demos block: QBR Google Slides generator, marketing events app, special needs pet registry, NFL team comparison, patient out-of-pocket app, routines output, Sankey diagram app, and template library preview.

<Frame>
  <iframe />
</Frame>

## Deployment Guides

*`Drea Brown · Docs`*

Announcement that live deployment documentation is now available, including deployment guides and in-depth docs per deployment type.

<Frame>
  <iframe />
</Frame>

## Integrations Visibility in Agent

*`Gustav Staprans · AI Design`*

Admin-configured integrations (Notion, GitHub, etc.) now appear directly in the Omni chat UI so users can connect without going to their profile page.

<Frame>
  <iframe />
</Frame>

## Conditional Routines (Schedule and Alert for AI)

*`Corey Ruderman · Alerting AI`*

Routines that only deliver when an AI-interpreted condition is met (e.g. "email me only if weekly order volume fell more than 20%"), with a live demo of setup and condition evaluation.

<Frame>
  <iframe />
</Frame>

## Blobby Sidebar Queries in Workbook

*`Gustav Staprans · AI Workbook`*

Queries run from the Blobby sidebar now stay in the sidebar by default instead of overwriting the workbook tab, enabling iterative analysis.

<Frame>
  <iframe />
</Frame>

## Spreadsheet Auto-Save

*`Richard Czechowski · Spreadsheets`*

Silent background auto-save for spreadsheets with an "unsaved changes" indicator that saves without disrupting the active tab.

<Frame>
  <iframe />
</Frame>

## Markdown Viz Pivot Iteration

*`Richard Czechowski · Visualization Apps`*

Markdown visualizations can now iterate over pivot columns, not just rows, with the same capability available in HTML visualizations.

<Frame>
  <iframe />
</Frame>

## Reports Deliveries

*`Richard Czechowski · Export Pixel Perfect`*

Reports now support scheduled deliveries in PDF, PNG (split per page), and XLSX formats.

<Frame>
  <iframe />
</Frame>

## Table Column Resize Fix

*`Richard Czechowski · Visualization Performance`*

Feature flag fix that locks column widths on first render so tables no longer jank and resize unexpectedly while scrolling with wrap enabled.

<Frame>
  <iframe />
</Frame>

## Apps on Homepage

*`Trip Tate · Administration Content Management`*

Dashboards and apps can now be set as the homepage, with options to show inline or as a full takeover, configurable via AI settings.

<Frame>
  <iframe />
</Frame>

## Multi-Measure Chart Trellising

*`Rob Miller · Visualization`*

Multi-measure charts now support trellising, building on last week's legend interaction improvements.

<Frame>
  <iframe />
</Frame>

## MCP Access to Apps

*`Dan Mosora · AI Apps MCP`*

MCP integration for Apps: create and edit apps via the Agentic API, with draft review before publishing and a polling job status flow.

<Frame>
  <iframe />
</Frame>

## Inspect and Annotate for Apps Redesign

*`Dan Mosora · AI Apps`*

The inspect and annotate feature was rewritten to integrate with the app-wide annotation framework, now with consistent pink styling and interaction patterns.

<Frame>
  <iframe />
</Frame>

## App Edit Improvements

*`Dan Mosora · AI Apps`*

The agent now uses a two-stage incremental build instead of attempting a full rewrite when editing large apps, reducing truncation and timeout failures.

<Frame>
  <iframe />
</Frame>

## Multi-Select Bulk Actions for Dashboards

*`James Bueche · Dashboards`*

Users can now hold Shift to multi-select items in Apps, with selections reflected in the outline panel; delete is supported now with align, grouping, and move coming soon.

<Frame>
  <iframe />
</Frame>

## Schema Exclusion Config

*`Conrad Slimmer · Modeling`*

Schema model config now supports exclusion syntax (e.g. "-public") and wildcards (e.g. "-\_dbt") so you can exclude schemas without enumerating every included one.

<Frame>
  <iframe />
</Frame>

## GitHub App for dbt Integration

*`Conrad Slimmer · Modeling Git`*

GitHub App installation is now available for dbt integration (in addition to model Git integration), enabling OAuth-free repo access with optional commit signing.

<Frame>
  <iframe />
</Frame>

## Folder Breadcrumb Root Setting

*`Luke Bowerman · Administration Content Management`*

Admins can now set any folder as the breadcrumb root, hiding parent folders from the breadcrumb trail — useful for curated embed experiences.

<Frame>
  <iframe />
</Frame>

## Dashboard Auto-Run Toggle

*`Luke Bowerman · Dashboards`*

A new autorun\_dashboard: false YAML flag prevents dashboards from running queries on every filter change, instead showing a Run button — ideal for expensive queries.

<Frame>
  <iframe />
</Frame>

## App Query Inspector

*`Luke Bowerman · AI Apps`*

Early-stage tooling that annotates app DOM elements with references to their underlying queries, letting you inspect what data powers each part of an app and see applied filters.

<Frame>
  <iframe />
</Frame>

## AI Eval Blobby Benchmark

*`Oliver Chang · AI Quality`*

Expanded Blobby benchmark with difficulty tiers and prompt perturbation variance; Kimi 2.7 scored 49/60 vs Sonnet's 47/60 on hard prompts with no thinking.

<Frame>
  <iframe />
</Frame>


# July 31, 2026
Source: https://docs.omni.co/demos/2026/20260731

Tons of Apps Work (Auditing, URL Persistence, Editing Improvement), Omni JDBC, AI Scheduler Work, Cross Connection Topics, Vis Work, and More

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Apps Challenge and Demos

*`Various · Apps AI`*

Recap of the 4-week app skills challenge (91 participants, 82 industries) plus live demos: Campaign Hub for marketing events, a sauna booking/ops manager, and an MA productivity suite with home dashboard, org model explorer, and services forecast.

<Frame>
  <iframe />
</Frame>

## Trellis and Map Fixes

*`Rob Miller · Visualization`*

Rob demos three visualization improvements: independent Y-axis scales per trellis facet, correct implicit field ordering in trellis, and moveable/hideable map legends.

<Frame>
  <iframe />
</Frame>

## App Editor Revert

*`Dylan Israel · Apps AI`*

Dylan shows a new revert button in the app editor that lets you undo changes without having to refresh the page.

<Frame>
  <iframe />
</Frame>

## App Navigation Links

*`Dylan Israel · Apps AI`*

Dylan demos a new app setting that controls iframe/sandbox permissions for navigation links, with a confirmation modal for first-time requests and clearer user messaging when the setting is off.

<Frame>
  <iframe />
</Frame>

## Composite Topics Cross-Connection Import

*`TJ Banghart · Modeling Workbook`*

TJ demos importing a topic from a separate database connection (e.g. Snowflake into BigQuery) to enable cross-connection joins via DuckDB, as a precursor to foreign tab / X-lookup support.

<Frame>
  <iframe />
</Frame>

## AI Cold Start Accuracy Improvements

*`Lei Tang · AI`*

Eval results showing Blobby's cold-start accuracy on Omni's own Snowflake instance improved from \~70–80% to 88% over two weeks, driven by better search and SQL/CTE parser fixes.

<Frame>
  <iframe />
</Frame>

## AI Schema and Table Visibility Configuration

*`Lei Tang · AI`*

New UI to toggle schemas and tables on/off for AI visibility when connecting a new database, plus an "Ask AI for suggestions" button that auto-hides dev/staging/junk tables so Blobby works better out of the box.

<Frame>
  <iframe />
</Frame>

## Sankey Diagram Labeling Controls

*`Dan Mosora · Visualization`*

Sankey diagrams now show entry-point-relative percentages (e.g. 50% of flows entering a node) rather than total-flow percentages, making multi-path analysis more intuitive.

<Frame>
  <iframe />
</Frame>

## Kotlin Serialization Performance

*`Cathy Lennon · Performance`*

Cathy shows the results of migrating serialization from Node to Kotlin: event loop lag on key endpoints dropped from \~300s peaks to near zero after a full rollout on July 23rd.

<Frame>
  <iframe />
</Frame>

## App Filter URL Persistence

*`Meredith Dodge · Apps AI`*

App filter selections are now reflected in the URL, so users can share a filtered state or refresh the page without losing their filters.

<Frame>
  <iframe />
</Frame>

## App URL Parameter State

*`Meredith Dodge · Apps AI`*

Blobby can now write arbitrary UI state (e.g. active tab) into URL parameters prefixed with ap, enabling shareable and refresh-safe app states without write-back.

<Frame>
  <iframe />
</Frame>

## App Chart Palette Inheritance

*`Meredith Dodge · Apps Visualization`*

Apps now inherit the organization's default chart color palette, so changing the palette setting automatically updates chart colors across all apps without any code changes.

<Frame>
  <iframe />
</Frame>

## App Inspector Tooling

*`Luke Bowerman · Apps AI`*

Early look at consolidating the app editor's inspect, query, and audit tools under a single Inspect button to reduce clutter in the toolbar.

<Frame>
  <iframe />
</Frame>

## App Audit Tool

*`Luke Bowerman · Apps AI`*

New LLM-powered app audit tool that analyzes app structure, generates a Mermaid data-flow diagram, and runs security/quality checks — with versioning so audits don't re-consume tokens on unchanged code.

<Frame>
  <iframe />
</Frame>

## App Query Tagging

*`Luke Bowerman · Apps AI`*

Queries in apps are now tagged with characteristics (truncated, uses total raw, many measures, etc.) to surface potential issues and give developers tips without requiring them to inspect the query manually.

<Frame>
  <iframe />
</Frame>

## App Appearance Theme Persistence

*`Luke Bowerman · Apps AI`*

Dark/light mode preference is now persisted across devices for logged-in users, so your theme follows you instead of resetting on each session.

<Frame>
  <iframe />
</Frame>

## My Activity Type Filtering

*`Luke Bowerman · Apps AI`*

The My Activity feed now supports filtering by content type, making it easier to find specific recent items.

<Frame>
  <iframe />
</Frame>

## Delivery Personalization Warning

*`Luke Bowerman · Scheduler`*

A new confirmation prompt warns users how many deliveries will be affected when enabling delivery personalization, reducing accidental bulk updates. Also includes a PSA about a proactively found embed SDK security issue and the upcoming update request to customers.

<Frame>
  <iframe />
</Frame>

## Omni Python Driver

*`Christopher Merrick · Python API`*

Omni topics can now be queried from Python notebooks via a new Arrow-protocol driver, letting users use Omni as a portable semantic layer from any Python environment.

<Frame>
  <iframe />
</Frame>

## Omni JDBC Driver

*`Christopher Merrick · Python API JDBC`*

The same protocol powering the Python driver also exposes a JDBC interface, allowing tools like DBeaver and any JDBC-compatible application to query Omni topics directly.

<Frame>
  <iframe />
</Frame>

## Agent Routine Management (AI Manages Schedules)

*`Eli Cohen · Scheduler AI`*

The Omni agent can now update, pause, and resume routines via natural language, rounding out routine management tooling for the agent.

<Frame>
  <iframe />
</Frame>

## Model YAML Inspector

*`James Ostergaard · Modeling Workbook`*

New shortcut in the query inspector to view the YAML field definitions for all fields in the current query inline, without switching context to the model.

<Frame>
  <iframe />
</Frame>


# August 7, 2026
Source: https://docs.omni.co/demos/2026/20260807

AI Summaries for Everything, Lots of App Work, and Bunch of Quality of Life

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## AI Summaries on Apps

*`Mariel Freyre · AI Apps`*

Demo of AI summaries on multi-query apps. New behavior: when a filter applies across all queries, each query gets an updated AI summary. Also shows combined cross-query insights in a single summary block.

<Frame>
  <iframe />
</Frame>

## Scenario Planner App

*`Kimberly DelSignore · Apps AI`*

Demo of an Anaplan-style scenario planning app built in Omni using Blobby. Shows a segment builder with live data, growth assumption toggles, headcount inputs, and a decision matrix that updates when you run a recommendation.

<Frame>
  <iframe />
</Frame>

## Live Spreadsheet Export from Scenario Builder

*`Kimberly DelSignore · Apps AI Export`*

Demo of exporting the scenario planner model to a live Google Sheet via Apps Script — not just hard-coded values but actual spreadsheet formulas derived from the Omni model, so finance users can continue working in their preferred tool.

<Frame>
  <iframe />
</Frame>

## Skills Discoverability UI

*`James Bueche · AI Skills`*

Demo of a new in-app Skills management UI (building on Routines patterns). Shows adding a skill, uploading a skill file to auto-populate fields, viewing skill details, editing, and running a skill directly into Blobby chat. Includes discussion of future invocation via Blobby, slash commands, API, and MCP.

<Frame>
  <iframe />
</Frame>

## Family Tree App

*`JD Costantini · AI Apps`*

Demo of a family tree app built in Omni by uploading a 1968 family reunion sheet to Blobby. Shows interactive tree navigation, expand-all, clicking into individuals, and a write-back UI for adding new members with photos and bios.

<Frame>
  <iframe />
</Frame>

## My Documents Sort Order Memory

*`Luke Bowerman · Content Management`*

My Documents now remembers your last-used sort order (e.g. newest) across sessions. Page size preference is also persisted. Setting will be extended to other content system views.

<Frame>
  <iframe />
</Frame>

## Opt-Out Product Announcements

*`Luke Bowerman · Administration`*

Admins can now opt out of in-app product announcements — useful for custom embed customers who want to control messaging. Admin-only alerts (e.g. Slack agent notices) are unaffected. Paired with an existing opt-out for Easter eggs.

<Frame>
  <iframe />
</Frame>

## Delivery Personalization Never-Option

*`Luke Bowerman · Administration Export`*

New "never personalize" toggle for deliveries, which hides the personalization option system-wide across all scheduled sends. Gated with a confirmation warning showing what will change before committing.

<Frame>
  <iframe />
</Frame>

## User Attribute Value Search

*`Luke Bowerman · Administration`*

User attribute filters now support "contains" matching on attribute values (previously only empty/not-empty). Admins can now search for users whose attribute exactly or partially matches a given string.

<Frame>
  <iframe />
</Frame>

## Dashboard Race Condition Fix Popup

*`Luke Bowerman · Performance Dashboards`*

A rare but recurring race condition that breaks dashboards now surfaces a self-serve "click to fix" button for editors. Non-editors see a permissions-aware message. A separate "cannot be repaired" path routes users to support.

<Frame>
  <iframe />
</Frame>

## Bulk Feature Flag Management

*`Luke Bowerman · Internal`*

New internal admin UI for bulk-adding or bulk-removing feature flags across users. Supports typed input of multiple flags, warns before applying, and has a best-effort mode for flags that don't exist. Not yet shipped publicly.

<Frame>
  <iframe />
</Frame>

## Trash Visibility Window

*`Luke Bowerman · Content Management`*

New admin setting to limit how many items appear in the trash by recency. Defaults to 180 days, configurable up to 10 years. Prevents trash views from loading thousands of items. A warning badge shows when older items are hidden.

<Frame>
  <iframe />
</Frame>

## App Full-Screen Mode

*`Luke Bowerman · Apps UX`*

Apps and dashboards now support true OS-level full screen (like Google Slides present mode), taking over the entire display. Works for dashboards, workbooks, and apps. Chrome does it silently; Safari requests permission. Shipping in 1–2 days.

<Frame>
  <iframe />
</Frame>

## Filter Data Panel Cross-Mapping

*`Luke Bowerman · Apps Filters`*

New data panel block (built by Alyssa) that shows filter mapping details: which queries a filter points to, whether mapped values are valid, and an error tooltip when a filter produces an unmappable value. Helps users debug cross-query filter issues.

<Frame>
  <iframe />
</Frame>

## Internal Triage App

*`Luke Bowerman · Internal`*

Internal tool that surfaces recent bug submissions and uses historical triage data to recommend a priority level (P1–P4). Includes templated comment shortcuts for requesting clarification. Built on the existing PR flow tooling.

<Frame>
  <iframe />
</Frame>

## MCP Search Existing Queries

*`Gustav Staprans · AI MCP`*

Demo of new MCP tools (side project) that let AI clients search the Omni content index, list queries on existing documents, and run them — without generating new queries. Enables referencing trusted, pre-built content from any MCP surface. Includes discussion of token usage, search ranking, and metadata best practices.

<Frame>
  <iframe />
</Frame>

## Spider-Man Tracker App

*`Austin Aranda · AI Apps Fun`*

Demo of a Spider-Man incident tracker app built in two prompts with Blobby. Shows a map with animated route replay, sighting/incident/villain filters, damage reports per villain (e.g. Green Goblin: \$9.1M, 47 injured), and anomaly-based location prediction.

<Frame>
  <iframe />
</Frame>

## Omni LMS App

*`Austin Aranda · AI Apps Fun`*

Demo of a learning management system built in Omni from the PS developer 101 deck. Includes structured lessons (what is Omni, semantic layer, etc.), click-through module navigation, a knowledge-check quiz with scoring, and gamified rewards (Blobby stickers). Designed for customer onboarding and adoption.

<Frame>
  <iframe />
</Frame>

## Internal Feature Flags App

*`Erin Cochran · Docs Internal`*

App that pulls live feature flag status directly from the codebase (updated on every code change). Shows flags filtered by beta/dev/prod-enabled status, flag details (who can enable, docs links, removal status), and metadata freshness (last updated in code vs. last metadata update).

<Frame>
  <iframe />
</Frame>

## Doc Search SEO Diagnostic Skills

*`Erin Cochran · Docs Internal`*

Two Claude skills that audit Omni's help doc search rankings: the first runs a report diagnosing why terms rank poorly (buried content, missing headings, vocabulary mismatch) using Mintlify's MCP; the second applies fixes and opens a pull request. An Omni app tracks findings, interventions, and score trends over time.

<Frame>
  <iframe />
</Frame>

## Agentic Summary Tiles

*`James Davidson · AI Dashboards`*

Demo of a new agentic (non-deterministic) summary tile type for dashboards. Unlike existing summary tiles tied to a single query, this tile runs like a Blobby chat session — determining its own queries, running multiple, and synthesizing results. Includes discussion of tool restrictions, one-shot display context, filter integration challenges, and planned SDK exposure for apps.

<Frame>
  <iframe />
</Frame>


# August 14, 2026
Source: https://docs.omni.co/demos/2026/20260814

Python in Omni, API calls and Writeback in Apps, Retail / Custom Calendars, More MCP Work, and Tons of UX and Content Management Improvements

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Visualization Layers Aggregation

*`Rob Miller · Visualization`*

Rob walks through a fix for the "aggregate on aggregate" problem in Layers, where averaging pre-aggregated values produced jagged lines. Shows how the viz now automatically detects the query shape and requests the right grain for subtotals, pivots, and trellised charts.

<Frame>
  <iframe />
</Frame>

## Input Columns App

*`Nathan Agrin · Apps AI`*

Demo of a new app built with editable input columns — a Boolean security-training field that persists across refreshes and syncs with the underlying workbook query. Requires manually adding the input column to the query for now; app-side creation is still pending.

<Frame>
  <iframe />
</Frame>

## Python In Omni

*`Jonathan Swenson · Python`*

Early prototype of running Python directly inside Omni via an AI agent. Shows queries being generated, Python code executed against the results, and a discussion of sandboxing constraints (limited libraries, restricted network access) needed before it ships.

<Frame>
  <iframe />
</Frame>

## Toast Hover Actions

*`Luke Bowerman · UX`*

Small UX improvement to toast notifications in the internal Storybook — hovering reveals a copy icon to grab the toast message, and hovering also pauses the auto-dismiss timer.

<Frame>
  <iframe />
</Frame>

## User Content Sharing To The Organization

*`Luke Bowerman · Administration Content Management`*

Demo of sharing a folder or document from My Documents to the entire org, plus a look at the "Share with Me" view and the underlying virtual spaces infrastructure that will allow multiple hubs later this year.

<Frame>
  <iframe />
</Frame>

## Required Filter Tiles

*`Luke Bowerman · Dashboards`*

Shows an upcoming change to how required filters affect other tiles on a dashboard — tiles not tied to the required filter's filter map will now still run instead of being blocked.

<Frame>
  <iframe />
</Frame>

## Dashboard Stop Queries Button

*`Luke Bowerman · Dashboards`*

New "stop queries" control for dashboards with long-running or runaway queries, including a footer shortcut and behavior when auto-refresh is enabled.

<Frame>
  <iframe />
</Frame>

## Content Version History

*`Luke Bowerman · Content Management`*

New consolidated version history view that merges the previously separate workbook change history and draft history into one place, with filtering by draft/published/archived/type. Coming to dashboards and apps shortly after workbooks.

<Frame>
  <iframe />
</Frame>

## Granular App Permissions

*`Meredith Dodge · Administration`*

Demo of granular model permissions that let admins restrict a user's ability to edit or create apps while still allowing dashboard/workbook edits — aimed at embed customers who want end users to view apps without modifying them.

<Frame>
  <iframe />
</Frame>

## Groups Tab Quality Of Life

*`Meredith Dodge · Administration`*

Quick addition of a Groups tab on the Users page, letting admins add or remove a user from multiple groups directly with a confirmation dialog (bulk removal still requires the API).

<Frame>
  <iframe />
</Frame>

## API Calling From Apps

*`Dylan Israel · Apps AI`*

Dylan demos early infrastructure for calling external APIs from within Omni apps, including backend-handled authentication and a Blobby-assisted flow for confirming and triggering an update call.

<Frame>
  <iframe />
</Frame>

## dbt Health Notification

*`Buck Ryan · dbt`*

The old dbt health indicator is replaced with a notification bubble on the dbt IDE tab that surfaces file-matching issues and lets you distinguish real mismatches from ignorable warnings.

<Frame>
  <iframe />
</Frame>

## Run Query MCP Tool

*`Gustav Staprans · AI MCP`*

New "Run Query" MCP tool that lets AI-generated queries be re-executed on demand without persisting them as a dashboard or workbook — useful for repeatedly refreshing data in external tools like Claude artifacts.

<Frame>
  <iframe />
</Frame>

## XLOOKUP SQL Tabs

*`Steven Talbot · Workbook SQL`*

Demo of Xlookups working between raw SQL tabs, query tabs, and now cross-model ("foreign") tabs, including how the switch-model tool resolves the right model automatically and current row-limit constraints.

<Frame>
  <iframe />
</Frame>

## Custom Calendar (Retail Calendars)

*`Steven Talbot · Modeling Calendars`*

Experimental support for custom calendar dimensions that remap real dates to a fiscal or retail calendar via a join, plus discussion of extending the idea to custom hierarchies and multi-tenant embed use cases.

<Frame>
  <iframe />
</Frame>

## AI BYOK Model Updates

*`Oliver Chang · AI BYOK`*

Updates on Bring-Your-Own-Key model support: a dashboard-editing crash fix for Kimi K3, OpenAI models now working via the Response API, and accuracy benchmarking showing a faster, cheaper tier scoring 50% on a hard prompt set.

<Frame>
  <iframe />
</Frame>

## Navigation AI In Workbook

*`Gustav Staprans · AI`*

Demo of new navigation AI in Workbook that lets the AI switch tabs, inspect other tabs' charts, and decide whether to update the current tab or a different one — unlocking cross-tab edits like recoloring a chart on a tab you're not viewing.

<Frame>
  <iframe />
</Frame>


# August 21, 2026
Source: https://docs.omni.co/demos/2026/20260821

More Python Progress (Plus Some Use Cases!), Bunch of New Apps and Skills Workflows (Writeback, AI Summary), Plus New Vis Labels, Perf Work, and Cross-DB Workbooks

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Omni Migration Tools

*`Jamie Davidson · BI Migration`*

Jamie walks through Omni's AI-assisted migration workflow, importing a Metabase dashboard and using AI to translate it into Omni data models, dashboards, and drafts for review.

<Frame>
  <iframe />
</Frame>

## Python Notebook Workflow

*`Jonathan Swenson · Python`*

A look at an early-stage notebook interface (Marimo/Jupyter-style) for running queries with pandas, referencing data frames, saving state, and iterating on cells.

<Frame>
  <iframe />
</Frame>

## OmniFrames DataFrame Library

*`Dan Spangenberger · Python`*

Dan introduces OmniFrames, a new Pandas/PySpark-style data frame library built on Omni's semantic layer that pushes compute down to the warehouse, including UDFs and computed columns.

<Frame>
  <iframe />
</Frame>

## Snowflake UFO Sightings Prediction

*`Austin Aranda · Python`*

Austin demonstrates using OmniFrames and Python to build a spatial prediction model on a sample UFO sightings dataset, then writes the predictions back to Snowflake and visualizes them in a dashboard.

<Frame>
  <iframe />
</Frame>

## Pylon Sentiment Analysis

*`Austin Aranda · Apps Use Cases`*

Austin shows an internal sentiment analysis example using Pylon support data to surface negative customer experience themes for the team.

<Frame>
  <iframe />
</Frame>

## Dashboard Builder UI Enhancements

*`Ben Horne · Dashboards`*

A quick tour of new dashboard creation features: adding text tiles/headers directly in create mode and applying custom brand color palettes to charts.

<Frame>
  <iframe />
</Frame>

## Skills Builder

*`Arielle Strong · AI Skills`*

A demo (on behalf of James) of a new skills system that lets Blobby build and update reusable skills directly from a chat conversation, which then surface as slash commands.

<Frame>
  <iframe />
</Frame>

## Multi-Query AI Summarization App

*`Arielle Strong · Apps Use Cases`*

An app that summarizes pipeline metrics across multiple queries, with dynamic prompt variants triggered by buttons and shareable via URL-based filters.

<Frame>
  <iframe />
</Frame>

## Write-back Apps

*`Arielle Strong · Apps Writeback`*

Early write-back capabilities for apps, showing input columns that let users edit and persist data (tags, notes, comments) back to the warehouse from within an app.

<Frame>
  <iframe />
</Frame>

## App Security Safe Domains

*`Dan Mosora · Apps Administration`*

New org-level security controls for apps, including safe domain allowlists for loading images and org-wide default policies that admins can enforce.

<Frame>
  <iframe />
</Frame>

## Onepager Skill

*`Nathan Agrin · AI Skills`*

A custom Blobby skill ("/onepager") that generates concise one-to-two-page reference documents to help ramp up on unfamiliar domains.

<Frame>
  <iframe />
</Frame>

## Query Deserialization Performance Fix

*`Nathan Agrin · Performance`*

A behind-the-scenes performance improvement discovered while exploring browser-worker query execution, cutting deserialization time by one to two orders of magnitude.

<Frame>
  <iframe />
</Frame>

## Vizland Labels Feature

*`Nathan Agrin · Visualization`*

A preview of a new labels feature built on Vizland's layers system, enabling per-layer data labels, independent formatting, and correct legend filtering behavior.

<Frame>
  <iframe />
</Frame>

## Cross-Model Tabs

*`Jade Khiev · Workbook Dashboards`*

An overview of cross-model tabs, letting users build and switch between workbook tabs backed by different models within a single workbook.

<Frame>
  <iframe />
</Frame>

## Session-Level AI Suggestion Classification

*`Jade Khiev · AI Analytics Administration`*

A deep dive into session-level classification of AI chat data, covering labeling, topic/summary generation, and how this powers smarter AI suggestions.

<Frame>
  <iframe />
</Frame>

## dbt Docs Refresh

*`Erin Cochran · dbt Docs`*

A refreshed, more guided version of Omni's dbt integration documentation, including a new metadata reference for dbt sync behavior.

<Frame>
  <iframe />
</Frame>

## Credits Usage Feature Flag

*`James Davidson · AI Administration`*

A new feature flag showing per-prompt AI credit usage within chat instances, plus a running total of credits used in a user's profile.

<Frame>
  <iframe />
</Frame>

## Embedding Apps with Filters and Resize Events

*`Meredith Dodge · Apps Embed`*

Embedded apps are out in beta! All of the flexibility and visual control of native apps with the governance and user management depth of the core Omni embedded app.

<Frame>
  <iframe />
</Frame>


# August 28, 2026
Source: https://docs.omni.co/demos/2026/20260828

Read/Write Applications, Blobby Manages Your Workbook Tabs, User Memory, Cube Planning and Building, and Omni With Any LLM You Can Imagine

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Apps POC Tracker

*`William Watkins · Apps AI`*

William demos a new Omni app for SEs and sales teams to track POCs — capturing success criteria with customers, logging notes/values, and auto-generating shareable CSVs and executive readouts from Fathom recordings.

<Frame>
  <iframe />
</Frame>

## App Styling and Theming

*`Jared Hardy · Apps AI UX`*

A look at new prompt-driven styling options for Omni apps, including full-width headers, editorial layouts, retro themes, split views, and font/color swaps — plus early work on shared style-guide context for consistent app theming.

<Frame>
  <iframe />
</Frame>

## Inspector Query Details

*`Jared Hardy · Apps AI`*

New refinements to the data inspector panel show more detail on underlying queries, with improved highlighting, click-to-expand query details, and clearer visibility into filters and field placement across an app.

<Frame>
  <iframe />
</Frame>

## Apps Public API Navigation

*`Austin Aranda · Apps Content Organization`*

A demo of a custom home navigation app built on Omni's new public APIs, featuring a data catalog with ERD views, joins, field descriptions, favorites/shared/recent views, and search — giving users a way to explore dashboards before opening them.

<Frame>
  <iframe />
</Frame>

## Dashboard Editing via Slackbot

*`Ben Horne · Dashboards MCP`*

Editing published Omni dashboards directly from Slack via MCP — the bot automatically spins up a draft, changes a chart type, adds a new chart, and adds a filter, all without touching the live published version.

<Frame>
  <iframe />
</Frame>

## Workbook AI Tab Management

*`Chris Swenson · Workbook AI`*

New AI capabilities let users manage workbook tabs directly from chat — updating existing tabs, creating new ones, and renaming tabs based on natural-language requests, reducing manual workbook cleanup.

<Frame>
  <iframe />
</Frame>

## Run Dashboard Queries from Chat

*`Gustav Staprans · AI Dashboards`*

A customer-requested feature that lets users run existing dashboard queries directly from chat — searching for relevant dashboards and executing their queries without needing to open the dashboard or enter split view.

<Frame>
  <iframe />
</Frame>

## User Memory Feature

*`Gustav Staprans · AI`*

Omni's newly GA'd user memory feature automatically remembers user-specific details (like a GitHub username) during chat sessions, with manual review/undo controls and an admin toggle to enable or disable it for their organization.

<Frame>
  <iframe />
</Frame>

## CSV Upload for Apps

*`Nathan Agrin · Apps AI Upload`*

A demo of CSV upload for Omni apps — turning uploaded spreadsheets into interactive, queryable app views, including a custom "shame list" spreadsheet app for tracking team goal submissions.

<Frame>
  <iframe />
</Frame>

## Layers by Default Feature Flag

*`Rob Miller · Visualization`*

A heads-up that a new feature flag will make the Layers editor the default experience for all new visualizations, bringing a new chart picker, more click-based interactions, and an opt-out path back to the classic editor.

<Frame>
  <iframe />
</Frame>

## AI Model Provider Cost Comparison

*`Zef Li · AI Model Selection`*

We compare AI model providers (including upcoming Bedrock support) side by side on cost and output quality, showing real credit-cost differences between cheaper and more expensive models.

<Frame>
  <iframe />
</Frame>

## Blobby Debugging and Assertions

*`Dylan Israel · Apps AI Administration`*

New debugging tools give Blobby the ability to capture console asserts, error logs, and screenshots when something fails in an app — helping explain what went wrong and enabling smarter, self-diagnosing fixes during app design and testing.

<Frame>
  <iframe />
</Frame>

## Automatic Cube Planning and Management

*`TJ Banghart · Dashboards Cubing AI`*

Building more into the cubing layer to allow Blobby to smartly build roll-ups to improve performance and cost for dashboards.

<Frame>
  <iframe />
</Frame>


# September 4, 2026
Source: https://docs.omni.co/demos/2026/20260904

Git Overhaul, Personalized Sidebar, Fireworks AI Support, Stable Table Names for Input Columns, More Apps Development (Including APIs, Snapshots, and Image Copying)

<Note>
  **Stay in the loop!** Subscribe to the [demo RSS feed](/demos/rss.xml) to be notified when we post new demos.

  Demos highlight what we are working on or experimenting with, but are not a guarantee of release. Let us know your thoughts at [support@omni.co](mailto:support@omni.co).
</Note>

## Document Ownership

*`Luke Bowerman · Content Org`*

Luke walks through the new document ownership model — content can now have multiple owners, each getting access requests and creator attribution, with groups excluded from ownership.

<Frame>
  <iframe />
</Frame>

## Hub Performance Fix

*`Luke Bowerman · Content Org`*

A deep dive into a customer-reported slow-page-load issue in the Hub, tracing it to inefficient loaders and showing a 12x performance improvement after the fix.

<Frame>
  <iframe />
</Frame>

## Connection Models Tab

*`Luke Bowerman · Modeling`*

A new Models tab on the connection page lists all models tied to that connection, lets you add new ones, and skips the Develop page entirely for single-model setups.

<Frame>
  <iframe />
</Frame>

## Sidebar Customization

*`Luke Bowerman · UX Personalization`*

A full walkthrough of the new Settings > Sidebar customization page — renaming items, swapping icons, adding built-in items, external links, and content links, plus import/export and relabeling that propagates app-wide.

<Frame>
  <iframe />
</Frame>

<Note>
  **Built-in groups are fixed in place in implementation:** The four groups that ship with Omni always stay in place and stay complete. You can rename them, swap their icons, and reset any one of them back to its default, but you can't reorder or remove a built-in group, and built-in items inside them can't be deleted or hidden. Your own custom groups can go anywhere below the first group.
</Note>

## AI Input Redesign

*`Peter Schrader · AI`*

Sarah, Mark, and Gustav's redesigned AI input component simplifies model/topic selection, adds smarter grouping and search, and scales gracefully for simple and complex connection setups.

<Frame>
  <iframe />
</Frame>

## Chart Layers Update

*`Rob Miller · Visualization`*

Charts using layers now default to measure name/value tokens for stacking, several previously broken layer features are fixed, and the confusing "all layers" UX has been replaced with unified controls.

<Frame>
  <iframe />
</Frame>

## Embeddable Reports (Pixel Perfect)

*`Richard Czechowski · Pixel Perfect`*

Reports (pixel perfect) can now be embedded with a cleaner UI, stripping out unnecessary chrome and options for a more seamless embedded view.

<Frame>
  <iframe />
</Frame>

## Stable Warehouse Table Names

*`Richard Czechowski · Input Columns`*

Input columns are moving to stable warehouse table names instead of creating a new table on every edit, making it easier to reference tables outside of Omni.

<Frame>
  <iframe />
</Frame>

## Chat To File Navigation

*`Chris Swenson · UX Modeling`*

A new button lets you jump straight from a chat back to the file you were working on, correctly reloading the branch that was active at the time.

<Frame>
  <iframe />
</Frame>

## Blobby Skills CRUD Tools

*`James Bueche · Skills`*

New tools let Blobby find, update, and manage existing skills — not just create them — demonstrated by bulk-converting a set of skills from one topic to another.

<Frame>
  <iframe />
</Frame>

## Git Integration Proof of Concept

*`Cathy Lennon · Git Modeling Administration`*

A proof of concept for a friendlier Git integration flow that stops Omni from auto-reverting commits on invalid YAML or unpulled changes, instead surfacing clear validation feedback and configurable checks.

<Frame>
  <iframe />
</Frame>

## Apps API Endpoints

*`Dan Mosora · Apps AI API`*

New GET and PUT API endpoints for apps let you programmatically read and update draft app content.

<Frame>
  <iframe />
</Frame>

## Apps Agent Read Tool Fix

*`Dan Mosora · Apps AI`*

A new read tool gives the agent better awareness of an app's HTML source, fixing context issues and reducing cost by only reading full app code when necessary.

<Frame>
  <iframe />
</Frame>

## Apps Clipboard Access

*` Dylan Israel · Apps AI UX`*

Apps can now copy images (SVGs and PNGs) to the clipboard, not just text, enabling use cases like debug buttons and shareable charts.

<Frame>
  <iframe />
</Frame>

## Fireworks AI LLM Provider

*`Oliver Chang · AI`*

A new Fireworks AI omni-managed provider option brings access to cheaper open-weight LLMs like GLM and Kimi, currently behind an internal feature flag.

<Frame>
  <iframe />
</Frame>

## Scheduler Legend Layout Fix

*`Nathan Agrin · Scheduler`*

A new auto-layout algorithm improves how the scheduler's native Vega legend renders, fixing cropped or awkwardly placed legends for customers with large legend content.

<Frame>
  <iframe />
</Frame>

## Blobby Shareable Artifacts

*`Nathan Agrin · AI Apps`*

A look at bringing Claude-style shareable artifacts to Blobby, allowing apps to selectively inline data so a frozen moment of conversation can be shared with others.

<Frame>
  <iframe />
</Frame>


# 2026 Demos
Source: https://docs.omni.co/demos/2026/index

Browse all 2026 Omni product demo videos covering AI modeling, input columns, custom formats, CLI tools, and more features.

<Callout icon="circle-play">
  **Check out the latest demo!**

  [September 4, 2026](/demos/2026/20260904): Git Overhaul, Personalized Sidebar, Fireworks AI Support, Stable Table Names for Input Columns, More Apps Development (Including APIs, Snapshots, and Image Copying)
</Callout>

* [September 4, 2026](/demos/2026/20260904): Git Overhaul, Personalized Sidebar, Fireworks AI Support, Stable Table Names for Input Columns, More Apps Development (Including APIs, Snapshots, and Image Copying)
* [August 28, 2026](/demos/2026/20260828): Read/Write Applications, Blobby Manages Your Workbook Tabs, User Memory, Cube Planning and Building, and Omni With Any LLM You Can Imagine
* [August 21, 2026](/demos/2026/20260821): More Python Progress (Plus Some Use Cases!), Bunch of New Apps and Skills Workflows (Writeback, AI Summary), Plus New Vis Labels, Perf Work, and Cross-DB Workbooks
* [August 14, 2026](/demos/2026/20260814): Python in Omni, API calls and Writeback in Apps, Retail / Custom Calendars, More MCP Work, and Tons of UX and Content Management Improvements
* [August 7, 2026](/demos/2026/20260807): AI Summaries for Everything, Lots of App Work, and Bunch of Quality of Life
* [July 31, 2026](/demos/2026/20260731): Tons of Apps Work (Auditing, URL Persistence, Editing Improvement), Omni JDBC, AI Scheduler Work, Cross Connection Topics, Vis Work, and More
* [July 24, 2026](/demos/2026/20260724): Schedule and Alerts for AI, More Pixel Perfext, App Fine Tuning, Dashboard Run Botton, Open Source AI Testing, Apps on Homepage, Measure Trellising, and More
* [July 17, 2026](/demos/2026/20260717): More AI Apps, Tons of Vis Work, Field Usage in the IDE, Improve dbt Development, More Extracts Work, and Multi-Connection Workbooks
* [July 10, 2026](/demos/2026/20260710): Monster Week - App Fine Tuning, Writeback, and Maps; Improved Filter Mapping, AI Scheduling, Mobile Dashboards, Dash on Homepage, and AI Calcs That Persist
* [July 6, 2026](/demos/2026/20260706): Grab Bag of New Apps, AI Building Pixel Perfect Reports, Omni Semantics Live in Excel, and More
* [June 26, 2026](/demos/2026/20260626): AI Annotations GA, Tons of Apps Work, Scheduled AI (Routines), AI Debug Tools, Better SQL Autocomplete, and More
* [June 19, 2026](/demos/2026/20260619): Scheduled AI, Pixel Perfect Getting Close, Agentic MCP, Notion MCP, Serialized Content Preview, and More!
* [June 12, 2026](/demos/2026/20260612): Tons of Apps Examples, Improving the Evals Framework, Pixel Perfect First Look, Github App Support, and More
* [June 5, 2026](/demos/2026/20260605): More Vibe Apps, AI Evals, More Dashboard Improvements, Markdown Column Promotion, and Sub-Agents
* [May 29, 2026](/demos/2026/20260529): More Vibe Apps, Git Blame, Dynamic Dashboard Filters, Xlookup Drill, Calc Pushdown, and More
* [May 22, 2026](/demos/2026/20260522): More Vibe Apps, Vis, AI Progress Throughout the App + Model Branches in the URL
* [May 15, 2026](/demos/2026/20260515): AI Hub - Model Learning, Evals, Analytics for AI Development - Plus More Vibe Coded Dashboards, Input Columns, Omnikit API Tooling, and Mobile App
* [May 8, 2026](/demos/2026/20260508): More HTML Dashboard Progress, Vis Layers and Multi-Measures, Lots of Dashboard Work (Filters, AI Summary Tiles), Plus Some Benchmarking on AI Quality, Speed, and Cost
* [May 1, 2026](/demos/2026/20260501): Lots of Dashboard Work (Run Button, Moveable Filer Work, Timezone Controls), Slackbot Dashboards, Plus Tons of UX Throughout the App
* [April 24, 2026](/demos/2026/20260424): Blobby Vibe Codes an AI App (HTML Dashboards), Tons of Content Validator, Dynamic Session Length, and Tons of Vis (AI Vision, Slackbot Vis, and More Layers Work
* [April 17, 2026](/demos/2026/20260417): Vis Layers, AI Analytics and Cost Data, dbt APIs, and Bunch of AI Improvements
* [April 10, 2026](/demos/2026/20260410): A Model That Improves Itself, Topic ERDs, Blobby Build Dashboard Filters, Named Formats, Gigantic, Formatted Spreadsheets, and Lots More AI
* [April 3, 2026](/demos/2026/20260403): Blobby Gets Unleashed, CLI + Some Use Cases, New Filter UX, Content Validator UX Lift, and Tons of Dashboard Work
* [March 27, 2026](/demos/2026/20260327): Blobby Slackbot, Custom Modeled Formats (Conditional Formatting, Markdown, and HTML), HTML Dashboards, and More (Lots of AI)
* [March 20, 2026](/demos/2026/20260320): Blobby was learning this week, plus custom formats, selective filter faceting, and more
* [March 13, 2026](/demos/2026/20260313): Input Columns, Column Editing, GSheet Live Connect, and Tons of AI
* [March 6, 2026](/demos/2026/20260306): AI dashboard building, forecasting, modeling, Salesforce MCP, treemaps, custom maps, button filters, and more new features.
* [February 27, 2026](/demos/2026/20260227): AI Modeling, Cell-by-Cell Conditional Formatting, Dynamic Dashboard Table Height, Better AI Feedback, and More
* [February 20, 2026](/demos/2026/20260220): Input Columns, Blobby Learns to Validate Work, AI Quickstarts, and More
* [February 13, 2026](/demos/2026/20260213): Blobby Joins the Modeling Team, Omni Becomes Your MCP, AI in All Views and Fields, Visual Drilling, New Dashboard Search, and More
* [February 6, 2026](/demos/2026/20260206): 34 Demos - A Peek into the Future of Omni (Hint, Lots of AI)
* [January 30, 2026](/demos/2026/20260130): Blobby Builds a Dashboard, Better AI Streaming, Funnel Vis, and Way More AI + Everything Else
* [January 23, 2026](/demos/2026/20260123): Selectable Table Cells, Dashboard Filter Buttons and Custom UX, Dashboard Tab Vanity URLs, and Plenty More
* [January 16, 2026](/demos/2026/20260116): Lots More AI (Homepage AI, Multi-Vis), Sankey Launch, Multi-Fact Topics, Paginated Subtotals and Huge Bucket of QOL Work
* [January 9, 2026](/demos/2026/20260109): Tons of AI (BYO LLM, Model Debugger, KPI Vis, Cron), and 23 Other Demos (Lots of Quality of Life)
* [January 2, 2026](/demos/2026/20260102): Slackbot v0, Field Picker Multi-Level Nesting, Tons of Perf, SQL Ai Field Suggestions, Google Drive in Blobby (25 Demos to Start 2026)


# Omni Demos
Source: https://docs.omni.co/demos/index

Watch weekly video demos of new and upcoming Omni features, including AI, dashboards, modeling, embedding, and platform updates.

<Tip>
  **Want to be notified about new updates?** Click the **Subscribe** button and use the URL to set up an RSS feed in [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) or an [RSS aggregator](https://feeder.co/).
</Tip>

<Callout icon="circle-play">
  **Check out the latest demo!**

  [September 4, 2026](/demos/2026/20260904): Git Overhaul, Personalized Sidebar, Fireworks AI Support, Stable Table Names for Input Columns, More Apps Development (Including APIs, Snapshots, and Image Copying)
</Callout>

<Update label="September 4, 2026">
  [September 4, 2026](https://docs.omni.co/demos/2026/20260904): Git Overhaul, Personalized Sidebar, Fireworks AI Support, Stable Table Names for Input Columns, More Apps Development (Including APIs, Snapshots, and Image Copying)
</Update>

<Update label="August 28, 2026">
  [August 28, 2026](https://docs.omni.co/demos/2026/20260828): Read/Write Applications, Blobby Manages Your Workbook Tabs, User Memory, Cube Planning and Building, and Omni With Any LLM You Can Imagine
</Update>

<Update label="August 21, 2026">
  [August 21, 2026](https://docs.omni.co/demos/2026/20260821): More Python Progress (Plus Some Use Cases!), Bunch of New Apps and Skills Workflows (Writeback, AI Summary), Plus New Vis Labels, Perf Work, and Cross-DB Workbooks
</Update>

<Update label="August 14, 2026">
  [August 14, 2026](https://docs.omni.co/demos/2026/20260814): Python in Omni, API calls and Writeback in Apps, Retail / Custom Calendars, More MCP Work, and Tons of UX and Content Management Improvements
</Update>

<Update label="August 7, 2026">
  [August 7, 2026](https://docs.omni.co/demos/2026/20260807): AI Summaries for Everything, Lots of App Work, and Bunch of Quality of Life
</Update>

<Update label="July 31, 2026">
  [July 31, 2026](https://docs.omni.co/demos/2026/20260731): Tons of Apps Work (Auditing, URL Persistence, Editing Improvement), Omni JDBC, AI Scheduler Work, Cross Connection Topics, Vis Work, and More
</Update>

<Update label="July 24, 2026">
  [July 24, 2026](https://docs.omni.co/demos/2026/20260724): Schedule and Alerts for AI, More Pixel Perfext, App Fine Tuning, Dashboard Run Botton, Open Source AI Testing, Apps on Homepage, Measure Trellising, and More
</Update>

<Update label="July 17, 2026">
  [July 17, 2026](https://docs.omni.co/demos/2026/20260717): More AI Apps, Tons of Vis Work, Field Usage in the IDE, Improve dbt Development, More Extracts Work, and Multi-Connection Workbooks
</Update>

<Update label="July 10, 2026">
  [July 10, 2026](https://docs.omni.co/demos/2026/20260710): Monster Week - App Fine Tuning, Writeback, and Maps; Improved Filter Mapping, AI Scheduling, Mobile Dashboards, Dash on Homepage, and AI Calcs That Persist
</Update>

<Update label="July 6, 2026">
  [July 6, 2026](https://docs.omni.co/demos/2026/20260706): Grab Bag of New Apps, AI Building Pixel Perfect Reports, Omni Semantics Live in Excel, and More
</Update>

<Update label="June 26, 2026">
  [June 26, 2026](https://docs.omni.co/demos/2026/20260626): AI Annotations GA, Tons of Apps Work, Scheduled AI (Routines), AI Debug Tools, Better SQL Autocomplete, and More
</Update>

<Update label="June 19, 2026">
  [June 19, 2026](https://docs.omni.co/demos/2026/20260619): Scheduled AI, Pixel Perfect Getting Close, Agentic MCP, Notion MCP, Serialized Content Preview, and More!
</Update>

<Update label="June 12, 2026">
  [June 12, 2026](https://docs.omni.co/demos/2026/20260612): Tons of Apps Examples, Improving the Evals Framework, Pixel Perfect First Look, Github App Support, and More
</Update>

<Update label="June 5, 2026">
  [June 5, 2026](https://docs.omni.co/demos/2026/20260605): More Vibe Apps, AI Evals, More Dashboard Improvements, Markdown Column Promotion, and Sub-Agents
</Update>

<Update label="May 29, 2026">
  [May 29, 2026](https://docs.omni.co/demos/2026/20260529): More Vibe Apps, Git Blame, Dynamic Dashboard Filters, Xlookup Drill, Calc Pushdown, and More
</Update>

<Update label="May 22, 2026">
  [May 22, 2026](https://docs.omni.co/demos/2026/20260522): More Vibe Apps, Vis, AI Progress Throughout the App + Model Branches in the URL
</Update>

<Update label="May 15, 2026">
  [May 15, 2026](https://docs.omni.co/demos/2026/20260515): AI Hub - Model Learning, Evals, Analytics for AI Development - Plus More Vibe Coded Dashboards, Input Columns, Omnikit API Tooling, and Mobile App
</Update>

<Update label="May 8, 2026">
  [May 8, 2026](https://docs.omni.co/demos/2026/20260508): More HTML Dashboard Progress, Vis Layers and Multi-Measures, Lots of Dashboard Work (Filters, AI Summary Tiles), Plus Some Benchmarking on AI Quality, Speed, and Cost
</Update>

<Update label="May 1, 2026">
  [May 1, 2026](https://docs.omni.co/demos/2026/20260501): Lots of Dashboard Work (Run Button, Moveable Filer Work, Timezone Controls), Slackbot Dashboards, Plus Tons of UX Throughout the App
</Update>

<Update label="April 24, 2026">
  [April 24, 2026](https://docs.omni.co/demos/2026/20260424): Blobby Vibe Codes an AI App (HTML Dashboards), Tons of Content Validator, Dynamic Session Length, and Tons of Vis (AI Vision, Slackbot Vis, and More Layers Work
</Update>

<Update label="April 17, 2026">
  [April 17, 2026](https://docs.omni.co/demos/2026/20260417): Vis Layers, AI Analytics and Cost Data, dbt APIs, and Bunch of AI Improvements
</Update>

<Update label="April 10, 2026">
  [April 10, 2026](https://docs.omni.co/demos/2026/20260410): A Model That Improves Itself, Topic ERDs, Blobby Build Dashboard Filters, Named Formats, Gigantic, Formatted Spreadsheets, and Lots More AI
</Update>

<Update label="April 3, 2026">
  [April 3, 2026](https://docs.omni.co/demos/2026/20260403): Blobby Gets Unleashed, CLI + Some Use Cases, New Filter UX, Content Validator UX Lift, and Tons of Dashboard Work
</Update>

<Update label="March 27, 2026">
  [March 27, 2026](https://docs.omni.co/demos/2026/20260327): Blobby Slackbot, Custom Modeled Formats (Conditional Formatting, Markdown, and HTML), HTML Dashboards, and More (Lots of AI)
</Update>

<Update label="March 20, 2026">
  [March 20, 2026](https://docs.omni.co/demos/2026/20260320): Blobby was learning this week, plus custom formats, selective filter faceting, and more
</Update>

<Update label="March 13, 2026">
  [March 13, 2026](https://docs.omni.co/demos/2026/20260313): Input Columns, Column Editing, GSheet Live Connect, and Tons of AI
</Update>

<Update label="March 6, 2026">
  [March 6, 2026](https://docs.omni.co/demos/2026/20260306): AI dashboard building, forecasting, modeling, Salesforce MCP, treemaps, custom maps, button filters, and more new features.
</Update>

<Update label="February 27, 2026">
  [February 27, 2026](https://docs.omni.co/demos/2026/20260227): AI Modeling, Cell-by-Cell Conditional Formatting, Dynamic Dashboard Table Height, Better AI Feedback, and More
</Update>

<Update label="February 20, 2026">
  [February 20, 2026](https://docs.omni.co/demos/2026/20260220): Input Columns, Blobby Learns to Validate Work, AI Quickstarts, and More
</Update>

<Update label="February 13, 2026">
  [February 13, 2026](https://docs.omni.co/demos/2026/20260213): Blobby Joins the Modeling Team, Omni Becomes Your MCP, AI in All Views and Fields, Visual Drilling, New Dashboard Search, and More
</Update>

<Update label="February 6, 2026">
  [February 6, 2026](https://docs.omni.co/demos/2026/20260206): 34 Demos - A Peek into the Future of Omni (Hint, Lots of AI)
</Update>

<Update label="January 30, 2026">
  [January 30, 2026](https://docs.omni.co/demos/2026/20260130): Blobby Builds a Dashboard, Better AI Streaming, Funnel Vis, and Way More AI + Everything Else
</Update>

<Update label="January 23, 2026">
  [January 23, 2026](https://docs.omni.co/demos/2026/20260123): Selectable Table Cells, Dashboard Filter Buttons and Custom UX, Dashboard Tab Vanity URLs, and Plenty More
</Update>

<Update label="January 16, 2026">
  [January 16, 2026](https://docs.omni.co/demos/2026/20260116): Lots More AI (Homepage AI, Multi-Vis), Sankey Launch, Multi-Fact Topics, Paginated Subtotals and Huge Bucket of QOL Work
</Update>

<Update label="January 9, 2026">
  [January 9, 2026](https://docs.omni.co/demos/2026/20260109): Tons of AI (BYO LLM, Model Debugger, KPI Vis, Cron), and 23 Other Demos (Lots of Quality of Life)
</Update>

<Update label="January 2, 2026">
  [January 2, 2026](https://docs.omni.co/demos/2026/20260102): Slackbot v0, Field Picker Multi-Level Nesting, Tons of Perf, SQL Ai Field Suggestions, Google Drive in Blobby (25 Demos to Start 2026)
</Update>

<Update label="December 19, 2025">
  [December 19, 2025](https://docs.omni.co/demos/2025/20251219): BYOLLM, AI Slash Commands, SQL Totals, Duration Fields, Tabs Beta, Query Snowflake Semantic Views, and So Much More (22 Videos!)
</Update>

<Update label="December 12, 2025">
  [December 12, 2025](https://docs.omni.co/demos/2025/20251212): Dashboard tabs, request access, filter layout, zoom, drag rebuild, complex filters, custom emojis, and 22 total demos.
</Update>

<Update label="December 5, 2025">
  [December 5, 2025](https://docs.omni.co/demos/2025/20251205): Tabbed Dash Beta, Per User AI, Lots More AI, Ridiculously Performant Giant Vis, Pie Rebuild Almost Launch, and More
</Update>

<Update label="December 1, 2025">
  [December 1, 2025](https://docs.omni.co/demos/2025/20251201): Blobby Learns to Search Google Drive, Tons of AI (Vis, Calcs, IDE), More Dash Containers, ADBC, and More
</Update>

<Update label="November 21, 2025">
  [November 21, 2025](https://docs.omni.co/demos/2025/20251121): Tons of New AI (Modeling, Visualization, User Attributes), Dynamic Top N, Pull Request Required Dashboards, Azure, and More!!
</Update>

<Update label="November 14, 2025">
  [November 14, 2025](https://docs.omni.co/demos/2025/20251114): Dashboard View As, Dashboard Summary AI Getting Close, New Docs, Better Query Killing and More
</Update>

<Update label="November 7, 2025">
  [November 7, 2025](https://docs.omni.co/demos/2025/20251107): Stacked Bar Sorting, Deep Research Launch, Topic Scoped Fields in the UI, Lots of Performance Work and More
</Update>

<Update label="October 31, 2025">
  [October 31, 2025](https://docs.omni.co/demos/2025/20251031): Tons of Dashboard Work (AI Summaries, Custom Errors, Localization, and More), More Cubes, and Getting Close on Custom Permissions
</Update>

<Update label="October 24, 2025">
  [October 24, 2025](https://docs.omni.co/demos/2025/20251024): Tons of Dashboard Work, More AI, Better Conditional Formatting, and More
</Update>

<Update label="October 17, 2025">
  [October 17, 2025](https://docs.omni.co/demos/2025/20251017): AI Workflows, ERD Diagrams, CSS Previews, New Filter UX, and More Blobbies Than You Can Handle
</Update>

<Update label="October 10, 2025">
  [October 10, 2025](https://docs.omni.co/demos/2025/20251010): Docs in the IDE, Cube Building, Lots of AI, External Model Dev Launch, dbt Metrics, Spreadsheet Export, and More
</Update>

<Update label="October 3, 2025">
  [October 3, 2025](https://docs.omni.co/demos/2025/20251003): External Development IDE, Lots of Blobby, Moving Dashboard Filters, Localization, SQL Preamble, and 15 (!!!) More
</Update>

<Update label="September 26, 2025">
  [September 26, 2025](https://docs.omni.co/demos/2025/20250926): Fast Rendering of Giant Visualizations, New Schema Model Navigation, Mapping Result GeoJSON, and More
</Update>

<Update label="September 19, 2025">
  [September 19, 2025](https://docs.omni.co/demos/2025/20250919): dbt Semantic Layer, MCP OAuth, Model Blame, AI Session URLs, Huge Performance Wins for Vis, and 11 More!
</Update>

<Update label="September 12, 2025">
  [September 12, 2025](https://docs.omni.co/demos/2025/20250912): A New User Attribute Debugger UI, MCP Oauth, Vis Reaggregation Alpha, and More
</Update>

<Update label="September 5, 2025">
  [September 5, 2025](https://docs.omni.co/demos/2025/20250905): Custom Permissions, YAML Editor Guest Demo, Independent Chart Stacking Controls, and More Quality of Life
</Update>

<Update label="August 29, 2025">
  [August 29, 2025](https://docs.omni.co/demos/2025/20250829): AI Session Saving, IDE Folders, New SQL Experience, and Lots More
</Update>

<Update label="August 22, 2025">
  [August 22, 2025](https://docs.omni.co/demos/2025/20250822): Dynamic Dashboard Spreadsheets, Spreadsheet Drill, Google Sheets Export, and lots of Blobby (Dashboard AI, Smart Filters, and Dash Search)
</Update>

<Update label="August 15, 2025">
  [August 15, 2025](https://docs.omni.co/demos/2025/20250815): Blobby Learns Filtered Measures, Bunch of API (Including A+ Docs), New SQL Mode, Databricks Metrics Views, and Tons of Quality of Life Work
</Update>

<Update label="August 8, 2025">
  [August 8, 2025](https://docs.omni.co/demos/2025/20250808): Blobby Builds a Dashboard, More AI Everywhere, Snowflake Semantic Layer Sync, Top N + Other, and More
</Update>

<Update label="August 1, 2025">
  [August 1, 2025](https://docs.omni.co/demos/2025/20250801): dbt Exposures, New Embed Demo, Guest Learning Microsite, Dashboard Summarization, and More
</Update>

<Update label="July 25, 2025">
  [July 25, 2025](https://docs.omni.co/demos/2025/20250725): A big pile of your most requested features this week!
</Update>

<Update label="July 18, 2025">
  [July 18, 2025](https://docs.omni.co/demos/2025/20250718): Agent Blobby, Dashboard AI, Embedded AI Guest Demo, Topic Builder UI, Global Cache Busting Button, Plus Lots of Vis
</Update>

<Update label="July 11, 2025">
  [July 11, 2025](https://docs.omni.co/demos/2025/20250711): DB OAuth Passthrough (soon), Lots of Spreadsheets, Unlimited Excel Downloads, More Better Vis, Embed Error Eventing, and More
</Update>

<Update label="July 3, 2025">
  [July 3, 2025](https://docs.omni.co/demos/2025/20250703): Fill Gaps in Any Date Series, More AI Auto-Modeling, More Model Permissions, and More
</Update>

<Update label="June 27, 2025">
  [June 27, 2025](https://docs.omni.co/demos/2025/20250627): Automated Data Modeling from AI Sessions, Instant Dashboard Filters, Unlimited Paginated Data Tables, Unfurled Tables in Schedules, and 15 More!
</Update>

<Update label="June 20, 2025">
  [June 20, 2025](https://docs.omni.co/demos/2025/20250620): EAV Modeling, AI with Subqueries, Paginated PDFs, Trellis Soon, MCP Soon, and Lots More
</Update>

<Update label="June 13, 2025">
  [June 13, 2025](https://docs.omni.co/demos/2025/20250613): Omni MCP Getting Close, AI Summary Vis, Trellis Charts, Faster Workbooks, Custom Blobby, and More
</Update>

<Update label="June 6, 2025">
  [June 6, 2025](https://docs.omni.co/demos/2025/20250606): Omni MCP 1.0, Spreadsheets Getting Closer to Release, New Model Debug Modes, Markdown Vis AI, and More
</Update>

<Update label="May 30, 2025">
  [May 30, 2025](https://docs.omni.co/demos/2025/20250530): dbt Tests in AI Context, Blobby Chrome Extension, Workbook Quick Starts, Embed Folder Naming, Performance Work, and More
</Update>

<Update label="May 23, 2025">
  [May 23, 2025](https://docs.omni.co/demos/2025/20250523): AI Field Creation, AI MCP v0, Streaming AI Results, Level of Detail Calculation, Lots of Dashboard Improvements, and More
</Update>

<Update label="May 16, 2025">
  [May 16, 2025](https://docs.omni.co/demos/2025/20250516): Embedded AI, Tiny Grid Dashboard Launch, More AI (Chart Config, Field Descriptions), Or Access Grants, Complex Date Filters, and More
</Update>

<Update label="May 9, 2025">
  [May 9, 2025](https://docs.omni.co/demos/2025/20250509): Blobby Mobile, An AI Demo on Our Actual Data, Front End Topic Building, API Mini Apps, Scheduler APIs, and Much More
</Update>

<Update label="May 2, 2025">
  [May 2, 2025](https://docs.omni.co/demos/2025/20250502): More AI (Ai Mode Launch, New Slackbot), Custom Embed Nav, More API, and Handful of New Custom Vis
</Update>

<Update label="April 25, 2025">
  [April 25, 2025](https://docs.omni.co/demos/2025/20250425): AI Mode + More AI, dbt Description Push Down, IDE Search, Table Styling and More
</Update>

<Update label="April 18, 2025">
  [April 18, 2025](https://docs.omni.co/demos/2025/20250418): Lots of Mini Apps, Better IDE Search, Multi-tab Spreadsheets, Topic and View Visual Editor, More AI and More
</Update>

<Update label="April 11, 2025">
  [April 11, 2025](https://docs.omni.co/demos/2025/20250411): Dynamic Model Layers, Embed Nav Builder, Better AI Retry, and More Analytics
</Update>

<Update label="April 4, 2025">
  [April 4, 2025](https://docs.omni.co/demos/2025/20250404): Filter on Calcs, AI Retry, AI Evals, Query View UX, Google Sheets Export, and Much More
</Update>

<Update label="March 28, 2025">
  [March 28, 2025](https://docs.omni.co/demos/2025/20250328): AI Progress Everywhere (Field Context, AI API, Training Docs), New DB Throttling Controls, Content in Branches, and More
</Update>

<Update label="March 21, 2025">
  [March 21, 2025](https://docs.omni.co/demos/2025/20250321): New Filter Controls, Dataset Builders, Lots of Custom Vis, and Plenty More
</Update>

<Update label="March 14, 2025">
  [March 14, 2025](https://docs.omni.co/demos/2025/20250314): Guest Vis Demo, Editing Vis from the Dashboard, CSV Upload Edit Workflows, a Slack Emoji App, and More
</Update>

<Update label="March 7, 2025">
  [March 7, 2025](https://docs.omni.co/demos/2025/20250307): Docs AI, Editing Visualizations Directly on the Dashboard, Unlimited Schedules and Downloads, dbt Environment Clean-up and More
</Update>

<Update label="February 28, 2025">
  [February 28, 2025](https://docs.omni.co/demos/2025/20250228): Lots of CSV Upload and Spreadsheets, Heatmaps, Color Promotion, and Lots More
</Update>

<Update label="February 21, 2025">
  [February 21, 2025](https://docs.omni.co/demos/2025/20250221): CSVs in the Data Warehouse (and Editable in a Spreadsheet!), Chart Color Promotion, and 13 More Demos
</Update>

<Update label="February 14, 2025">
  [February 14, 2025](https://docs.omni.co/demos/2025/20250214): CSV Upload Soft Launch, Instant Filters, More Color Work, Better Chart Labels, and More
</Update>

<Update label="February 6, 2025">
  [February 6, 2025](https://docs.omni.co/demos/2025/20250206): AI Filters, Dashboard Performance Reports, Clear Time Filters, Per-User Attributes Page, Our First Spreadsheet App, and More
</Update>

<Update label="January 31, 2025">
  [January 31, 2025](https://docs.omni.co/demos/2025/20250131): Smart Labels, Editing Vis from the Dashboard, AI Chart Building, Cache Busting API, and More
</Update>

<Update label="January 24, 2025">
  [January 24, 2025](https://docs.omni.co/demos/2025/20250124): CSV Upload (Preview), AI Summary Tiles, Advanced Vis UI Builder, Embed URL Sharing, and More
</Update>

<Update label="January 17, 2025">
  [January 17, 2025](https://docs.omni.co/demos/2025/20250117): Lots of API, Vis Series Coloring, AI Query Summary, Model Usage Analytics, and Lots of Polish and Pretty Vis
</Update>

<Update label="January 10, 2025">
  [January 10, 2025](https://docs.omni.co/demos/2025/20250110): Snowflake Cortex Columns, Sub-Folders (Early), Editing dbt Models, and Much More
</Update>

<Update label="January 3, 2025">
  [January 3, 2025](https://docs.omni.co/demos/2025/20250103): Bunch of AI Improvements, More/Better Usage Data, Concurrency Improvements, and More
</Update>

<Update label="December 20, 2024">
  [December 20, 2024](https://docs.omni.co/demos/2024/20241220): Controls in Tiles, Topic-less AI, and Lots of Small Wins Throughout the App
</Update>

<Update label="December 13, 2024">
  [December 13, 2024](https://docs.omni.co/demos/2024/20241213): Color Modeling Launch, More Excel Functions, Dynamic Column Modeling, Drafts Refinement and Lots of Polish
</Update>

<Update label="December 6, 2024">
  [December 6, 2024](https://docs.omni.co/demos/2024/20241206): dbt Reader, Nearly-Alpha Spreadsheets, Inline IDE Auto-Correct, and Lots More
</Update>

<Update label="December 2, 2024">
  [December 2, 2024](https://docs.omni.co/demos/2024/20241202): Simpler dashboard URLs, tab descriptions, calc descriptions, table and vis view, topic files, and more
</Update>

<Update label="November 22, 2024">
  [November 22, 2024](https://docs.omni.co/demos/2024/20241122): *Actual* Spreadsheets, Mapping Vis Colors in the Data Model, and Much More
</Update>

<Update label="November 15, 2024">
  [November 15, 2024](https://docs.omni.co/demos/2024/20241115): Flexible Totals (Including Dimensions and Calc), Calculations with Controls, Better SQL, and More
</Update>

<Update label="November 8, 2024">
  [November 8, 2024](https://docs.omni.co/demos/2024/20241108): AI Tuning, Lots of Visualization Improvements, Better Date Filtering, and Our First Customer Demo
</Update>

<Update label="November 1, 2024">
  [November 1, 2024](https://docs.omni.co/demos/2024/20241101): User Specific Timezones, AI Query Tuning, Versioning Dashboards, and Much More
</Update>

<Update label="October 25, 2024">
  [October 25, 2024](https://docs.omni.co/demos/2024/20241025): Vis Config Locking, More Smart Autocomplete, Model Speeds-Ups and Some Table Polish
</Update>

<Update label="October 18, 2024">
  [October 18, 2024](https://docs.omni.co/demos/2024/20241018): Smart IDE auto-complete, map regions, more dashboard CSS, embedded dashboard scheduling,
</Update>

<Update label="October 11, 2024">
  [October 11, 2024](https://docs.omni.co/demos/2024/20241011): New model controls for timeframes and filter value labels, more visualization configuration, and a nice demo of richer dashboard styling
</Update>

<Update label="October 4, 2024">
  [October 4, 2024](https://docs.omni.co/demos/2024/20241004): dbt SQL mode, schema refresh via git, and new content permissions
</Update>

<Update label="September 27, 2024">
  [September 27, 2024](https://docs.omni.co/demos/2024/20240927): Embedded saving and sharing, map regions, period-over-period measures, Snowflake native deployment, and much more
</Update>

<Update label="September 20, 2024">
  [September 20, 2024](https://docs.omni.co/demos/2024/20240920): Exploding pivots, embedded dashboard sharing, global color palettes, and much more
</Update>

<Update label="September 13, 2024">
  [September 13, 2024](https://docs.omni.co/demos/2024/20240913): Global color palettes, cross-tab spreadsheet references and 12 (?!) more
</Update>

<Update label="September 6, 2024">
  [September 6, 2024](https://docs.omni.co/demos/2024/20240906): Workbook Drafts Preview, SFTP Scheduling, Embedded Content Management, and More
</Update>

<Update label="August 30, 2024">
  [August 30, 2024](https://docs.omni.co/demos/2024/20240830): Drill queries, dashboard links, TEXT() promotion, and more
</Update>

<Update label="August 23, 2024">
  [August 23, 2024](https://docs.omni.co/demos/2024/20240823): Embed dashboard linking, send to Google Sheets, calculations on SQL, and 11 more!
</Update>

<Update label="August 16, 2024">
  [August 16, 2024](https://docs.omni.co/demos/2024/20240816): Unlimited downloads, even more custom visualizations in markdown, better advanced visualization UX, and more
</Update>

<Update label="August 9, 2024">
  [August 9, 2024](https://docs.omni.co/demos/2024/20240809): Sticky visualization settings, better auto-vis, unlimited downloads, and more
</Update>

<Update label="August 2, 2024">
  [August 2, 2024](https://docs.omni.co/demos/2024/20240802): Dashboard themes, dashboard vanity URLs, XLOOKUP portability, in\_query, single-use views in topics and much more!
</Update>

<Update label="July 26, 2024">
  [July 26, 2024](https://docs.omni.co/demos/2024/20240726): IDE redesigns, lots of filter work, and much more
</Update>

<Update label="July 19, 2024">
  [July 19, 2024](https://docs.omni.co/demos/2024/20240719): IDE error auto-fixing, refresh schema on schedule, KPI styling enhancements, improved SQL auto-complete and lots more
</Update>

<Update label="July 12, 2024">
  [July 12, 2024](https://docs.omni.co/demos/2024/20240712): Query API alpha, table enhancements, controls for controls and lots more!
</Update>

<Update label="July 8, 2024">
  [July 8, 2024](https://docs.omni.co/demos/2024/20240708): Content as code, Drill modals in workbook & dbt pushdown
</Update>

<Update label="June 28, 2024">
  [June 28, 2024](https://docs.omni.co/demos/2024/20240628): Alerts, Email Bursting (User Attributes in Schedules), AI Querying, & More
</Update>

<Update label="June 21, 2024">
  [June 21, 2024](https://docs.omni.co/demos/2024/20240621): Workbook UX (+ Tab Reordering), Vis Config Stickiness, Inline Images in Tables, & More
</Update>

<Update label="June 14, 2024">
  [June 14, 2024](https://docs.omni.co/demos/2024/20240614): AI Copilot + History, Environment Variables for dbt, Legend Controls & more
</Update>

<Update label="June 7, 2024">
  [June 7, 2024](https://docs.omni.co/demos/2024/20240607): Dynamic Tables - Links and Events, Default Row Level Access Controls, Snowflake Native App, & more
</Update>

<Update label="May 31, 2024">
  [May 31, 2024](https://docs.omni.co/demos/2024/20240531): Branch Mode + Git, Single-Tile Scheduling, Dynamic dbt Schema Improvements, & more
</Update>

<Update label="May 24, 2024">
  [May 24, 2024](https://docs.omni.co/demos/2024/20240524): Omni In-App Logging, Tab Rearranging and Styling, Single-Dashboard-Only User Permission, & more
</Update>

<Update label="May 17, 2024">
  [May 17, 2024](https://docs.omni.co/demos/2024/20240517): Filter by Query, Field Swappers on the Dashboard, New Permissions Reporting
</Update>

<Update label="May 10, 2024">
  [May 10, 2024](https://docs.omni.co/demos/2024/20240510): Table Styling, Excel Downloads With Formulas (Launched), Stickier Vis Config (Launched), & more
</Update>

<Update label="May 3, 2024">
  [May 3, 2024](https://docs.omni.co/demos/2024/20240503): XLOOKUP, Embedded Workbooks, Dynamic Fields / Select Fields From Filters, & more
</Update>

<Update label="April 26, 2024">
  [April 26, 2024](https://docs.omni.co/demos/2024/20240426): Compound Filters, Pull Requests + Model History Cleanup, Dynamic dbt Warehouses, & more
</Update>

<Update label="April 19, 2024">
  [April 19, 2024](https://docs.omni.co/demos/2024/20240419): Dynamic Fields (Parameters), Sudo / Permissions Testing (Launched), In-Database Aggregate Awareness, & More
</Update>

<Update label="April 12, 2024">
  [April 12, 2024](https://docs.omni.co/demos/2024/20240412): Incremental Model Promotion From the Workbook, Workbook Embedding, API + Schema Refresh Via API, & more
</Update>

<Update label="April 5, 2024">
  [April 5, 2024](https://docs.omni.co/demos/2024/20240405): Dynamic dbt Schema Swapping, 3-Argument SUMIF, Cell References in SUMIF AND COUNTIF, & more
</Update>

<Update label="March 29, 2024">
  [March 29, 2024](https://docs.omni.co/demos/2024/20240329): Text-to-Vis (Vega Lite GPT), Text-to-Query (GPT Workbooks), Admin User Impersonation (Sudo), & more
</Update>

<Update label="March 22, 2024">
  [March 22, 2024](https://docs.omni.co/demos/2024/20240322): Dashboard PDF & CSV Downloads, Embed Themes (Gradients and Custom Fonts), & more
</Update>

<Update label="March 15, 2024">
  [March 15, 2024](https://docs.omni.co/demos/2024/20240315): Looker migration, Tables (Row Height, Markdown), Conditional Formatting, & more
</Update>

<Update label="March 8, 2024">
  [March 8, 2024](https://docs.omni.co/demos/2024/20240308): ETL Freshness, Dynamic dbt schema switching, Period-Over-Period, & more
</Update>

<Update label="March 1, 2024">
  [March 1, 2024](https://docs.omni.co/demos/2024/20240301): SCIM user management, Design polish, Connection refresh error improvements (with dbt), Simpler permissions, & more
</Update>

<Update label="February 23, 2024">
  [February 23, 2024](https://docs.omni.co/demos/2024/20240223): Ridiculously fast embedded dashboards, Seamless dashboard refreshing, Bonus filter wiring & more
</Update>

<Update label="February 16, 2024">
  [February 16, 2024](https://docs.omni.co/demos/2024/20240216): Complete CSS control for embed dashboard styling, Git workflows in data modeling,Filtering iframes, & more
</Update>

<Update label="February 9, 2024">
  [February 9, 2024](https://docs.omni.co/demos/2024/20240209): Dashboard styling control designs, Content validator + Clickhouse, Spreadsheet calcs over pivots, & more
</Update>

<Update label="February 2, 2024">
  [February 2, 2024](https://docs.omni.co/demos/2024/20240202): Slack scheduling, usage analytics and more!
</Update>

<Update label="January 26, 2024">
  [January 26, 2024](https://docs.omni.co/demos/2024/20240126): Calculations date math & pivot progress, Filtered dashboard emailing, dbt, & more
</Update>

<Update label="January 19, 2024">
  [January 19, 2024](https://docs.omni.co/demos/2024/20240119): Field level permissions, Content validator, Access filters, Pivots & more
</Update>

<Update label="January 12, 2024">
  [January 12, 2024](https://docs.omni.co/demos/2024/20240112): Adding free text, Better filtering, New calcs, & more
</Update>

<Update label="January 5, 2024">
  [January 5, 2024](https://docs.omni.co/demos/2024/20240105): Calcs GPT, Caching controls, Content permissions, & more
</Update>

<Update label="December 22, 2023">
  [December 22, 2023](https://docs.omni.co/demos/2023/20231222): Gleam embed site, Early content permissions, Extends, & more
</Update>

<Update label="December 15, 2023">
  [December 15, 2023](https://docs.omni.co/demos/2023/20231215): Content system, Custom homepage, Topic joins, Composed model history, & more
</Update>

<Update label="December 8, 2023">
  [December 8, 2023](https://docs.omni.co/demos/2023/20231208): Improved performance, SQL viewer permissions, Quick rollback CLI, & more
</Update>

<Update label="December 1, 2023">
  [December 1, 2023](https://docs.omni.co/demos/2023/20231201): Embedded demo, Field picker 2.0, Topic permissions, Better binning, & more
</Update>

<Update label="November 17, 2023">
  [November 17, 2023](https://docs.omni.co/demos/2023/20231117): Seamless dashboard drill-down, UX odds & ends, Permission groups, & more
</Update>

<Update label="November 10, 2023">
  [November 10, 2023](https://docs.omni.co/demos/2023/20231110): Dashboard drill iframe, Vis config overhaul, Table layout designs, & more
</Update>

<Update label="November 3, 2023">
  [November 3, 2023](https://docs.omni.co/demos/2023/20231103): Google Sheets embedding, Transpose & measures on rows, Calculations refinement, & more
</Update>

<Update label="October 27, 2023">
  [October 27, 2023](https://docs.omni.co/demos/2023/20231027): More embedding, KPI colors, ignored\_views, Snowflake Info Schema App, & more
</Update>

<Update label="October 20, 2023">
  [October 20, 2023](https://docs.omni.co/demos/2023/20231020): Embedded user management &  more table calculations
</Update>


# Omni agent skills
Source: https://docs.omni.co/developers/agent-skills/index

Extend your IDE with Omni analytics skills for building models, running queries, managing content, and more.

Omni's agent skills bring analytics capabilities directly into your development environment. They are open-source skills that let you explore models, run queries, build dashboards, and manage your Omni instance — all without leaving your IDE.

The skills use [Omni's CLI](/developers/cli) and activate automatically based on your request. They work with AI coding assistants including Claude Code, Cursor, Codex, Cortex Code, CoCo, and more.

<Note>
  Agent skills are different from the [MCP Server](/ai/mcp). The MCP Server enables natural language querying of your data, while agent skills provide a broader set of capabilities for model building, content management, administration, and more.
</Note>

## What you can do

* Explore and inspect semantic models, topics, views, and fields
* Run queries against Omni's semantic layer
* Create and edit model definitions in YAML
* Find, browse, and manage dashboards and workbooks
* Build and update dashboards programmatically
* Optimize models for [the Omni Agent](/ai/chat)
* Manage users, groups, permissions, and schedules

## Supported platforms

<Columns>
  <Card title="Claude Code" icon="terminal" href="/developers/agent-skills/install#claude-code">
    Full plugin install with 9 skills and 3 agents
  </Card>

  <Card title="Cursor" icon="arrow-pointer" href="/developers/agent-skills/install#cursor">
    Full plugin install plus 3 `.mdc` rules
  </Card>

  <Card title="OpenAI Codex" icon="openai" href="/developers/agent-skills/install#skills-sh-compatible-agents">
    Uses the shared skills.sh install flow
  </Card>

  <Card title="GitHub Copilot" icon="github" href="/developers/agent-skills/install#skills-sh-compatible-agents">
    Uses the shared skills.sh install flow
  </Card>

  <Card title="Gemini CLI" icon="sparkles" href="/developers/agent-skills/install#skills-sh-compatible-agents">
    Uses the shared skills.sh install flow
  </Card>

  <Card title="Snowflake Cortex Code" icon="snowflake" href="/developers/agent-skills/install#cortex-code">
    Loads the repo's `SKILL.md` directories as custom skills
  </Card>
</Columns>

## Example prompts

Ask naturally:

```text theme={null}
"What topics are available in our Omni model?"
"Run a query showing revenue by month"
"Add a new dimension for customer tier to the users view"
"Find the dashboard about sales performance"
"Build a dashboard showing revenue by month"
"Improve the AI context on our orders topic"
"Give the marketing team access to the sales dashboard"
"Generate a signed embed URL for this dashboard"
"Convert this Omni topic to a Snowflake Semantic View"
```

For direct agent routing:

```text theme={null}
@omni-analyst What are our top 10 products by revenue this quarter?
@omni-modeler Add customer lifetime value metrics to the users view
@omni-admin-agent Set up weekly PDF delivery of the executive dashboard
```

## Related

* [Omni REST API reference](/api)
* [Modeling documentation](/modeling)
* [Optimize models for Omni's AI](/modeling/develop/ai-optimization)
* [Omni MCP Server](/ai/mcp)
* [Claude Code plugin documentation](https://code.claude.com/docs/en/plugins)
* [Cursor plugin documentation](https://cursor.com/docs/plugins)
* [skills.sh](https://skills.sh)

## Contributing

Contributions to Omni's agent skills are welcome! Open a pull request or file an issue in the [GitHub repository](https://github.com/exploreomni/omni-agent-skills).


# Installing Omni agent skills
Source: https://docs.omni.co/developers/agent-skills/install

Install Omni agent skills in Claude Code, Cursor, Cortex Code, and skills.sh-compatible agents.

<Tip>
  Looking to update an existing install? See [Updating Omni agent skills](/developers/agent-skills/update).
</Tip>

## Requirements

To use the Omni agent skills, you'll need to first install the Omni CLI. See the [CLI installation guide](/developers/cli/install) for more information.

## Claude Code

### Install the plugin

<Steps>
  <Step title="Add the marketplace plugin">
    Agent skills for Claude Code can be installed through the Claude Marketplace (recommended) or through a Git URL.

    Run **one** of the following:

    ```bash Marketplace (recommended) theme={null}
    /plugin marketplace add exploreomni/omni-agent-skills
    ```

    ```bash Git URL theme={null}
    /plugin marketplace add https://github.com/exploreomni/omni-agent-skills.git
    ```
  </Step>

  <Step title="Install the plugin">
    ```bash theme={null}
    /plugin install omni-analytics@omni-analytics
    ```
  </Step>
</Steps>

### Install integrations plugin

Optionally install the integrations plugin (Snowflake Semantic Views, etc.):

```bash theme={null}
/plugin install omni-integrations@omni-analytics
```

### Team deployment

To make this plugin available to your entire team automatically, add it to your project's `.claude/settings.json`:

```json theme={null}
{
  "extraKnownMarketplaces": {
    "omni-analytics": {
      "source": {
        "source": "github",
        "repo": "exploreomni/omni-agent-skills"
      }
    }
  },
  "enabledPlugins": ["omni-analytics@omni-analytics", "omni-integrations@omni-analytics"]
}
```

When team members trust the repository folder, Claude Code automatically installs the marketplace and plugin.

## Cursor

### Install the plugin

```text theme={null}
/add-plugin https://github.com/exploreomni/omni-agent-skills.git
```

This will also install [Cursor rule files](/developers/agent-skills/skills#cursor-rules).

### Install the integrations plugin

To also install the integrations plugin (Snowflake Semantic Views, etc.), use [Cursor's team marketplace import](https://cursor.com/docs/plugins) (**Dashboard > Settings > Plugins > Import**) with the repo URL `https://github.com/exploreomni/omni-agent-skills`. Both `omni-analytics` and `omni-integrations` will appear as separate installable plugins.

## Cortex Code

Cortex Code can load Omni skills directly as custom skill folders. For the CLI, copy one or more folders from this repo's `skills/` directory into project-local `.cortex/skills/` or user-level `~/.snowflake/cortex/skills/`. In Snowsight workspaces, you can upload the same skill folders directly.

### Install all skills in current project

```bash theme={null}
mkdir -p .cortex/skills
cp -R skills/* .cortex/skills/
```

### Install one skill

```bash theme={null}
mkdir -p .cortex/skills
cp -R skills/omni-query .cortex/skills/
```

### Install integrations skills

```bash theme={null}
mkdir -p .cortex/skills
cp -R skills/omni-integrations .cortex/skills/
```

## skills.sh-compatible agents

Use this path for agents that load skills through [skills.sh](https://skills.sh), including [OpenAI Codex](https://openai.com/codex/), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [GitHub Copilot](https://github.com/features/copilot), and other compatible agent runtimes.

### Preview available skills

```bash theme={null}
npx skills add exploreomni/omni-agent-skills --list
```

### Install all skills

```bash theme={null}
npx skills add exploreomni/omni-agent-skills
```

### Install one skill

```bash theme={null}
npx skills add https://github.com/exploreomni/omni-agent-skills --skill omni-query
```

### Install integrations skills

```bash theme={null}
npx skills add https://github.com/exploreomni/omni-agent-skills --skill omni-integrations
```

### Install globally

```bash theme={null}
npx skills add exploreomni/omni-agent-skills --global
```

### Check for updates

```bash theme={null}
npx skills check
```

### Update installed skills

```bash theme={null}
npx skills update
```

## Next steps

<Info>
  To ensure agent skills are up-to-date, enable automatic updates, update them manually from your IDE, or reinstall the skills. Refer to the documentation for your IDE for information about enabling automatic updates.
</Info>


# Omni agent skills reference
Source: https://docs.omni.co/developers/agent-skills/skills

Reference for all Omni agent skills, agents, and Cursor rules included in the plugin.

## omni-analytics

These activate from natural-language requests:

| Skill                     | Description                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| **omni-model-explorer**   | Discover and inspect models, topics, views, fields, dimensions, measures, and relationships               |
| **omni-model-builder**    | Create and edit views, topics, dimensions, measures, and relationships in YAML                            |
| **omni-query**            | Run queries against Omni's semantic layer and interpret results                                           |
| **omni-content-explorer** | Find, browse, and organize dashboards, workbooks, and folders                                             |
| **omni-content-builder**  | Create, update, and manage documents and dashboards programmatically - lifecycle, tiles, filters, layouts |
| **omni-ai-optimizer**     | Optimize your Omni model for Blobby, the Omni Agent                                                       |
| **omni-admin**            | Manage connections, users, groups, permissions, schedules, and schema refreshes                           |
| **omni-embed**            | Embed Omni dashboards in external applications - URL signing, themes, and postMessage events              |
| **omni-ai-eval**          | Evaluate AI query generation accuracy — run test prompts, compare results, and score across dimensions    |

## omni-integrations

Install the integrations plugin to use these skills. See the [Installation guide](/developers/agent-skills/install) for more information.

| Skill                               | Description                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| **omni-to-snowflake-semantic-view** | Convert an Omni Analytics topic into a Snowflake Semantic View YAML definition |

## Agents

These are built for heavier workflows where explicit delegation is useful:

| Agent                | Description                                               |
| -------------------- | --------------------------------------------------------- |
| **omni-analyst**     | Explores models, runs queries, and delivers insights      |
| **omni-modeler**     | Builds semantic models, writes YAML, and optimizes for AI |
| **omni-admin-agent** | Manages users, permissions, schedules, and connections    |

## Cursor rules

<Note>
  Cursor loads the `rules/` directory automatically. Claude Code, Cortex Code, and skills.sh-compatible agents do not load these files as plugin rules, so outside Cursor they should be treated as shared reference material unless you copy them into that tool's own rule mechanism.
</Note>

These `.mdc` files are included for Cursor's rules system:

| Rule                      | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| **omni-api-conventions**  | Auth headers, base URL patterns, error handling, and pagination   |
| **omni-yaml-conventions** | YAML file types, field syntax, and dimension and measure patterns |
| **omni-terminology**      | Maps business intelligence terms to Omni-specific vocabulary      |


# Updating Omni agent skills
Source: https://docs.omni.co/developers/agent-skills/update

Update Omni agent skills and troubleshoot cached or stale plugin versions.

<Tip>
  To ensure agent skills are up-to-date, enable automatic updates, update them manually from your IDE, or reinstall the skills. Refer to the documentation for your IDE for information about enabling automatic updates.
</Tip>

## Claude Code

Enable auto-updates:

1. Run `/plugin`
2. Go to **Marketplaces**
3. Select the marketplace → **Enable auto-update**

Or update manually from the `/plugin` menu.

## Cursor, Cortex Code, and skills.sh-Compatible agents

Re-run the installation command or re-copy the updated `skills/` folders to pull the latest version. See the [Installation guide](/developers/agent-skills/install) for the installation commands for each platform.

## Troubleshooting

If your skills appear outdated, or the install command reports the plugin is "already installed" while skills aren't loading, your IDE may be serving a cached version. This can happen when the uninstall process doesn't fully clean up all registry and cache entries.

To ensure you're running the latest version, manually clear the stale plugin data and reinstall.

### Claude Code

<Steps>
  <Step title="Remove registry entries">
    Edit the following files and remove any `omni-analytics` entries:

    * **`~/.claude/settings.json`** — Remove `"omni-analytics@omni-analytics"` from `enabledPlugins` and the `"omni-analytics"` block from `extraKnownMarketplaces`
    * **`~/.claude/plugins/installed_plugins.json`** — Remove the `omni-analytics` entry
    * **`~/.claude/plugins/known_marketplaces.json`** — Remove the `omni-analytics` entry
  </Step>

  <Step title="Delete cached files">
    ```bash theme={null}
    rm -rf ~/.claude/plugins/cache/omni-analytics/
    rm -rf ~/.claude/plugins/marketplaces/omni-analytics/
    ```
  </Step>

  <Step title="Reinstall the latest version">
    In a Claude session, run:

    ```text theme={null}
    /plugin marketplace add exploreomni/omni-agent-skills
    /plugin install omni-analytics@omni-analytics
    /reload-plugins
    ```
  </Step>
</Steps>

### Cursor

<Steps>
  <Step title="Remove the plugin">
    Unregister the plugin:

    ```text theme={null}
    /remove-plugin omni-analytics
    ```
  </Step>

  <Step title="Delete cached files">
    Cursor caches plugin repositories locally. Remove the cached clone:

    ```bash theme={null}
    rm -rf ~/.cursor/plugins/omni-analytics/
    ```
  </Step>

  <Step title="Reinstall the latest version">
    Run the following to reinstall the latest version of the Omni skills:

    ```
    /add-plugin https://github.com/exploreomni/omni-agent-skills.git
    ```

    Cursor will pull a fresh copy of the repository with the latest skills.
  </Step>
</Steps>


# Authentication - Omni CLI
Source: https://docs.omni.co/developers/cli/authentication

Choose how to authenticate the Omni CLI with your instance: OAuth for streamlined setup or API keys for manual control.

The Omni CLI supports two authentication methods. Choose the one that best fits your needs:

|                  | OAuth                                         | API key                                                        |
| ---------------- | --------------------------------------------- | -------------------------------------------------------------- |
| Best for         | Individual users who want quick, secure setup | Admins managing keys centrally, or automated workflows (CI/CD) |
| Setup complexity | Low - browser flow                            | Medium - manual configuration                                  |
| Key management   | Automatic                                     | Manual                                                         |
| Token expiry     | 8 hours (auto-refreshes)                      | None                                                           |
| User permissions | Uses your permissions                         | Uses key creator's permissions                                 |

## OAuth authentication

OAuth lets the CLI connect to Omni without requiring you to manually create and manage API keys. When you authenticate with `omni config login`, Omni creates an API key on your behalf and links it to your user account.

<Note>
  CLI OAuth PATs are different from standard PATs. See the [CLI OAuth PATs section](#cli-oauth-pats) for more information.
</Note>

### Requirements

To use OAuth authentication with the CLI, your organization must have:

* **Personal access tokens (PATs)** enabled - Organization Admins can activate them by going to **Settings > API access > Personal tokens**

### How it works

When you authenticate the CLI using OAuth, the flow looks like this:

1. Run `omni config login` in your terminal.
2. Your browser opens to an authorization page for your Omni organization.
3. Review the permissions on the authorization page.
4. Click **Authorize**.
5. The CLI receives the tokens and stores them securely.

After authorization, all CLI commands use your Omni permissions and access controls. The flow uses OAuth 2.1 with PKCE for security.

### CLI OAuth PATs

When you authenticate with `omni config login`, Omni automatically creates a special PAT called a **CLI OAuth PAT**. These differ from standard PATs in a few ways:

<Steps>
  <Step title="Any user can create one">
    Standard PATs require **Restricted Querier** or higher permissions, but CLI OAuth PATs are created automatically for any user who completes the OAuth flow.
  </Step>

  <Step title="Access tokens expire after 8 hours">
    For security, CLI access tokens expire after 8 hours. The CLI automatically refreshes tokens using refresh token rotation, so you don't need to worry about expiration during normal usage.
  </Step>

  <Step title="Refresh tokens rotate on each use">
    When the CLI refreshes your access token, it receives a new refresh token and the old one is invalidated. This prevents replay attacks.
  </Step>

  <Step title="Permissions reflect the user's in-app permissions">
    CLI OAuth PATs inherit the creating user's in-app permissions.
  </Step>

  <Step title="Not visible in Omni">
    CLI OAuth PATs are not currently visible in Omni.
  </Step>
</Steps>

For a full comparison of all API key types in Omni, refer to the [API authentication](/api/authentication) documentation.

### Authenticating with OAuth

To authenticate the CLI with OAuth:

```bash theme={null}
omni config login
```

Your browser opens to the authorization page. After you authorize, the CLI is ready to use.

## API key authentication

API key authentication gives you direct control over key creation and management. This approach is useful when:

* You need to manage API keys centrally for your organization
* You're setting up automated workflows or CI/CD pipelines
* You want to use a service account rather than individual user credentials
* You prefer tokens that don't expire

### How it works

1. Create an [API key in Omni](/api/authentication)
2. Set the API key as an environment variable or configure it during `omni config init`
3. The CLI includes the key in all requests to Omni

### Authenticating with an API key

You can provide your API key in two ways:

**Option 1: Environment variable**

```bash theme={null}
export OMNI_API_TOKEN=omni_osk_...
```

**Option 2: During configuration**

```bash theme={null}
omni config init
```

When prompted, enter your API token.

## Troubleshooting

### OAuth issues

<AccordionGroup>
  <Accordion title="Personal Access Tokens aren't enabled (403 error)">
    Ask an admin to enable PATs: **Settings > API access > Personal tokens**
  </Accordion>

  <Accordion title="Authorization flow doesn't start">
    * Verify your browser is set as the default application for HTTP links
    * Check that your Omni instance is accessible from your browser
    * Try running `omni config login --help` to verify the CLI is properly installed
  </Accordion>

  <Accordion title="Authorization fails after clicking &#x22;Authorize&#x22;">
    * Check that your browser allows redirects to localhost
    * Verify you have permission to create API keys in your organization
    * Try running `omni config login` again
  </Accordion>

  <Accordion title="Token expired errors after 8 hours">
    The CLI automatically refreshes tokens. If you see this error:

    * Run `omni config login` again to re-authenticate
    * Check that your refresh token hasn't been revoked in Omni settings
  </Accordion>
</AccordionGroup>

### API key issues

<AccordionGroup>
  <Accordion title="Authentication fails">
    * Verify the API key is correct and hasn't been revoked
    * Check that the key has appropriate permissions
    * Ensure you're using the correct instance URL
    * Try setting `OMNI_API_TOKEN` directly in your environment
  </Accordion>
</AccordionGroup>

### General issues

<AccordionGroup>
  <Accordion title="Commands fail after successful authentication">
    * Confirm the API key is active in your Omni settings
    * Verify you have access to the resources you're trying to access
    * Check that your Omni user permissions allow the operation
  </Accordion>
</AccordionGroup>

## Next steps

Ready to start using the CLI? See the [quickstart guide](/developers/cli/quickstart) to run your first commands.


# AI commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/ai

Reference for the omni ai command group: query generation, jobs, conversations, and credit controls.

AI-powered query generation, job management, and documentation search. See the [AI API documentation](/api/ai) for more information.

<Note>
  AI evals, model suggestions, and routines have their own command groups: [`omni ai-eval`](/developers/cli/commands/ai-eval), [`omni ai-model-suggestions`](/developers/cli/commands/ai-model-suggestions), and [`omni ai-routines`](/developers/cli/commands/ai-routines).
</Note>

```bash theme={null}
omni ai <command> 
```

| Command                                | Description                                                   |
| -------------------------------------- | ------------------------------------------------------------- |
| `generate-query`                       | Generate and optionally execute a query from natural language |
| `pick-topic`                           | Pick the best topic for a prompt                              |
| `search-omni-docs`                     | Search Omni documentation                                     |
| `job-submit`                           | Submit an AI job                                              |
| `job-status`                           | Get AI job status                                             |
| `job-cancel`                           | Cancel an AI job                                              |
| `job-result`                           | Get AI job result                                             |
| `job-visualization`                    | Render AI job visualization                                   |
| `job-feedback-submit`                  | Rate a finished AI job's response, successful or failed       |
| `branding`                             | Get AI helper branding                                        |
| `conversations-list`                   | List AI conversations                                         |
| `conversation-detail`                  | Get AI conversation with messages                             |
| `credit-controls-get`                  | Get AI credit controls                                        |
| `credit-controls-update`               | Update AI credit controls                                     |
| `credit-controls-users-list`           | List individual users' AI credit limits                       |
| `credit-controls-users-update`         | Set individual users' AI credit limits                        |
| `credit-controls-entity-groups-list`   | List individual entity groups' AI credit limits               |
| `credit-controls-entity-groups-update` | Set individual entity groups' AI credit limits                |
| `credit-usage-users-read`              | Read individual users' AI credit usage                        |
| `credit-usage-entity-groups-read`      | Read individual entity groups' AI credit usage                |

`job-feedback-submit` records the same thumbs up or thumbs down, and optional comment, that a user can give in the Omni chat UI or Slack. The job must have finished. Feedback is append-only and no command reads it back.

```bash wrap theme={null}
# Answer a question about your data
omni ai generate-query --body '{"modelId":"MODEL_ID","prompt":"how many active users","executeQuery":true}'

# Search the Omni docs
omni ai search-omni-docs --body '{"query":"how do I..."}'

# View help for job-status command, including arguments and flag details
omni ai job-status --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# AI Eval commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/ai-eval

Reference for the omni ai-eval command group: manage eval prompt sets and runs.

Manage eval prompt sets and runs used to score AI quality against curated prompt suites. See the [AI API documentation](/api/ai) for more information.

```bash theme={null}
omni ai-eval <command>
```

| Command                 | Description                         |
| ----------------------- | ----------------------------------- |
| `prompt-sets-list`      | List eval prompt sets               |
| `prompt-sets-create`    | Create an eval prompt set           |
| `prompt-sets-get`       | Get an eval prompt set              |
| `prompt-sets-update`    | Update an eval prompt set           |
| `prompt-sets-archive`   | Archive an eval prompt set          |
| `prompt-sets-unarchive` | Restore an archived eval prompt set |
| `runs-list`             | List eval runs                      |
| `runs-create`           | Start an eval run                   |
| `runs-get`              | Get an eval run                     |
| `runs-cancel`           | Cancel an eval run                  |
| `runs-archive`          | Archive an eval run                 |
| `runs-unarchive`        | Restore an archived eval run        |

```bash wrap theme={null}
# Start an eval run against a prompt set
omni ai-eval runs-create --body '{"promptSetId":"<promptSetId>"}'

# View help for prompt-sets-create, including arguments and flag details
omni ai-eval prompt-sets-create --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# AI model suggestions commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/ai-model-suggestions

Reference for the omni ai-model-suggestions command group: generate and manage AI model suggestions.

Generate, list, schedule, and manage AI-generated suggested improvements to a model. See the [AI API documentation](/api/ai) for more information.

```bash theme={null}
omni ai-model-suggestions <command>
```

| Command                              | Description                     |
| ------------------------------------ | ------------------------------- |
| `model-suggestions-list`             | List model suggestions          |
| `model-suggestions-generate`         | Generate model suggestions      |
| `model-suggestions-ignore`           | Ignore a suggestion             |
| `model-suggestions-restore`          | Restore a suggestion            |
| `model-suggestions-delete`           | Delete a suggestion             |
| `model-suggestions-run-latest`       | Get the latest generation run   |
| `model-suggestions-run-get`          | Get a generation run            |
| `model-suggestions-schedule-enable`  | Enable the suggestion schedule  |
| `model-suggestions-schedule-disable` | Disable the suggestion schedule |

```bash wrap theme={null}
# Generate suggestions for a model
omni ai-model-suggestions model-suggestions-generate <model-id>

# View help for model-suggestions-list, including arguments and flag details
omni ai-model-suggestions model-suggestions-list --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# AI routines commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/ai-routines

Reference for the omni ai-routines command group: manage AI routines.

Create and manage [AI routines](/ai/routines) — scheduled prompts that run through the Omni Agent and deliver the result by email or Slack. See the [AI Routines API documentation](/api/ai-routines) for more information.

```bash theme={null}
omni ai-routines <command>
```

| Command           | Description       |
| ----------------- | ----------------- |
| `routines-list`   | List routines     |
| `routine-create`  | Create a routine  |
| `routine-get`     | Get a routine     |
| `routine-update`  | Update a routine  |
| `routine-delete`  | Delete a routine  |
| `routine-trigger` | Run a routine now |

```bash wrap theme={null}
# Run a routine now
omni ai-routines routine-trigger <routine-id>

# Print the create request body's shape and an example
omni ai-routines routine-create --schema

# View help for routine-create, including arguments and flag details
omni ai-routines routine-create --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# API tokens commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/api-tokens

Reference for the omni api-tokens command group: manage organization API tokens.

List, inspect, enable or disable, and delete organization [API tokens](/api/authentication). Requires organization admin permissions.

```bash theme={null}
omni api-tokens <command>
```

| Command           | Description                    |
| ----------------- | ------------------------------ |
| `api-keys-list`   | List API tokens                |
| `api-keys-get`    | Get API token                  |
| `api-keys-update` | Enable or disable an API token |
| `api-keys-delete` | Revoke an API token            |

```bash wrap theme={null}
# List API tokens in the organization
omni api-tokens api-keys-list

# Disable a token
omni api-tokens api-keys-update <id> --body '{"enabled":false}'

# View help for api-keys-delete command, including arguments and flag details
omni api-tokens api-keys-delete --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Connections commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/connections

Reference for the omni connections command group: database connections, dbt configuration, and schema refresh schedules.

Manage [database connections](/api/connections), [dbt configurations](/api/dbt), [schema refresh schedules](/api/schema-refresh-schedules), and [connection environments](/api/connection-environments).

```bash theme={null}
omni connections <command>
```

| Command                          | Description                      |
| -------------------------------- | -------------------------------- |
| `get`                            | Get a connection                 |
| `list`                           | List connections                 |
| `create`                         | Create a connection              |
| `update`                         | Update a connection              |
| `delete`                         | Delete a connection              |
| `connection-environments-create` | Create connection environments   |
| `connection-environments-update` | Update a connection environment  |
| `connection-environments-delete` | Delete a connection environment  |
| `dbt-get`                        | Get dbt configuration            |
| `dbt-delete`                     | Delete dbt configuration         |
| `dbt-update`                     | Update dbt configuration         |
| `dbt-rotate-signing-key`         | Rotate dbt commit signing key    |
| `dbt-environments-create`        | Create dbt environment           |
| `dbt-environments-update`        | Update dbt environment           |
| `dbt-environments-list`          | List dbt environments            |
| `dbt-environments-delete`        | Delete dbt environment           |
| `schedules-create`               | Create schema refresh schedule   |
| `schedules-delete`               | Delete a schema refresh schedule |
| `schedules-get`                  | Get a schema refresh schedule    |
| `schedules-list`                 | List schema refresh schedules    |
| `schedules-update`               | Update a schema refresh schedule |

```bash wrap theme={null}
# View all connections
omni connections list

# Create a connection environment
omni connections connection-environments-create --body '{"baseConnectionId": "<baseConnectionId>","environmentConnectionIds": "<environmentConnectionId>"}'

# View help for create command, including arguments and flag details
omni connections create --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Content commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/content

Reference for the omni content command group: list and search content.

List and search content in your organization. See the [Content API documentation](/api/content) for more information.

```bash theme={null}
omni content list
```

| Command  | Description                                       |
| -------- | ------------------------------------------------- |
| `list`   | List all content (dashboards, workbooks, folders) |
| `search` | Search dashboards                                 |

```bash wrap theme={null}
# Search dashboards by keyword
omni content search --q "revenue"
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Dashboards commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/dashboards

Reference for the omni dashboards command group: download dashboards and manage dashboard filters.

[Download dashboards](/api/dashboard-downloads) and manage [dashboard filters](/api/dashboard-filters).

```bash theme={null}
omni dashboards <command>
```

| Command           | Description                   |
| ----------------- | ----------------------------- |
| `download`        | Initiate a dashboard download |
| `download-file`   | Get a download file           |
| `download-status` | Get download job status       |
| `get-filters`     | Get dashboard filters         |
| `update-filters`  | Update dashboard filters      |

```bash theme={null}
# Download dashboard
omni dashboards download <dashboardid>

# View help for update-filters command, including arguments and flag details
omni dashboards update-filters --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Documents commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/documents

Reference for the omni documents command group, including the v2 draft/publish and app content commands.

Create, manage, and configure [documents](/api/documents), including [permissions](/api/document-permissions), drafts, [labels](/api/document-labels), [favorites](/api/document-favorites), and [app](/visualize-present/apps) content.

```bash theme={null}
omni documents <command>
```

| Command                      | Description                           |
| ---------------------------- | ------------------------------------- |
| `list`                       | List documents                        |
| `create`                     | Create a document                     |
| `get`                        | Get a document                        |
| `delete`                     | Delete a document                     |
| `get-queries`                | List document queries                 |
| `move`                       | Move a document                       |
| `upgrade-layout`             | Upgrade dashboard layout              |
| `create-draft`               | Create a document draft               |
| `list-drafts`                | List document drafts                  |
| `discard-draft`              | Discard a document draft              |
| `duplicate`                  | Duplicate a document                  |
| `get-permissions`            | Get document permissions              |
| `update-permission-settings` | Update document permission settings   |
| `add-permits`                | Add document permits                  |
| `update-permits`             | Update document permits               |
| `revoke-permits`             | Revoke document permits               |
| `access-list`                | List document access principals       |
| `add-favorite`               | Add document to favorites             |
| `remove-favorite`            | Remove document from favorites        |
| `list-favorites`             | List users who favorited the document |
| `bulk-update-labels`         | Bulk update document labels           |
| `add-label`                  | Add label to a document               |
| `remove-label`               | Remove label from a document          |

```bash wrap theme={null}
# List documents
omni documents list

# Search favorites for a document
omni documents list-favorites <identifier>

# View help for duplicate command, including arguments and flag details
omni documents duplicate --help
```

<Note>
  `omni documents update` (rename) and `omni documents put` (full replace) no longer exist. The API endpoints behind them were removed, so the commands were dropped from the CLI in v1.2.2. Use the `v2` commands below for renaming and editing content. `omni documents transfer-ownership` is still available but deprecated; grant the `OWNER` permission role with `add-permits` instead.
</Note>

## Document content (v2)

The `v2` commands manage a document's content (tiles, queries, dashboard layout) through an explicit draft/publish workflow. They replace the removed `update` and `put` commands.

| Command                        | Description                        |
| ------------------------------ | ---------------------------------- |
| `v2-create`                    | Create document                    |
| `v2-get`                       | Read document state                |
| `v2-get-draft`                 | Read draft state                   |
| `v2-patch-draft`               | Create draft and patch document    |
| `v2-patch-draft-by-identifier` | Patch draft                        |
| `v2-publish-draft`             | Publish draft                      |
| `v2-update-identifier`         | Rename document identifier         |
| `v2-bind-query-model`          | Bind a tile to a query model       |
| `v2-unbind-query-model`        | Unbind a tile from its query model |
| `v2-remove-dashboard`          | Remove dashboard from document     |

```bash wrap theme={null}
# Patch a draft (creates one if none exists), then publish it
omni documents v2-patch-draft <identifier> --body '{"name":"New name"}'
omni documents v2-publish-draft <identifier>

# View help for v2-patch-draft, including arguments and flag details
omni documents v2-patch-draft --help
```

## App content (v2)

The app commands read and write the HTML and settings of a document's [app](/visualize-present/apps). A document holds an app or a dashboard, never both, and a workbook-only document holds neither.

<Warning>
  The app commands are in alpha. These API routes can change shape without a deprecation cycle. The other document commands, and [apps](/visualize-present/apps) themselves, are stable.
</Warning>

Every write is draft-scoped: a published app is not addressable for writing, so edit a draft and then publish it with `v2-publish-draft`. Commands that act on a named draft take the draft identifier as an argument; the `-auto-draft` commands create or reuse the document's main draft in the same call, so you don't have to track one.

| Command                   | Description                                                                                         |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| `v2-get-app`              | Read the published app content                                                                      |
| `v2-get-draft-app`        | Read the app content on a named draft                                                               |
| `v2-get-main-draft-app`   | Read the app content on the main draft                                                              |
| `v2-put-app`              | Replace the app content on a named draft                                                            |
| `v2-put-app-auto-draft`   | Create or reuse the main draft, then replace the app content. Creates the app if the draft has none |
| `v2-patch-app`            | Edit the app content on a named draft                                                               |
| `v2-patch-app-auto-draft` | Create or reuse the main draft, then edit the app content. Requires an existing app                 |
| `v2-remove-app`           | Remove the app from a named draft. Idempotent                                                       |

`v2-put-app` sends the full HTML body. `v2-patch-app` sends `htmlEdits` instead: 1 to 20 edit objects applied in order, each with a required `search` string, a required `replace` string, and an optional `replaceAll` boolean. Patches are all-or-nothing - an edit that matches zero times, or more than once without `replaceAll`, rejects the whole request and changes nothing.

The `patch` commands never create an app. If there's no app to edit, they return a `409`. To create the first app on a workbook-only document, use `v2-put-app` or `v2-put-app-auto-draft`.

App writes are last-write-wins, with no version precondition, and each write appends a revision to the app's history. HTML is capped at 2 MiB, so pass a full app body from a file with `--body @app.json` rather than inline. See [JSON requests and responses](/developers/cli/reference/json-requests-and-responses) for the other ways to supply a body.

Writes return a non-blocking warning for external script and stylesheet hosts outside your organization's [app policy](/administration/settings/app-policy). The write succeeds, but the render-time content security policy blocks the host in the browser until an organization admin allows it.

```bash wrap theme={null}
# Read the published app, then edit the main draft and publish it
omni documents v2-get-app <identifier>
omni documents v2-patch-app-auto-draft <identifier> --body '{"htmlEdits":[{"search":"Q2 revenue","replace":"Q3 revenue"}]}'
omni documents v2-publish-draft <identifier>

# View help for v2-put-app, including arguments and flag details
omni documents v2-put-app --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Embed commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/embed

Reference for the omni embed command group: generate embed SSO sessions.

Generate SSO sessions for [embedded Omni instances](/embed).

```bash wrap theme={null}
omni embed sso-generate-session
```

| Command                | Description                      |
| ---------------------- | -------------------------------- |
| `sso-generate-session` | Generate an embedded SSO session |

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Folders commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/folders

Reference for the omni folders command group: manage folders and folder permissions.

Manage [folders](/api/folders) and [folder permissions](/api/folder-permissions).

| Command                      | Description                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `list`                       | List folders                                                                      |
| `create`                     | Create a folder                                                                   |
| `delete`                     | Delete a folder                                                                   |
| `update`                     | Update a folder                                                                   |
| `get-permissions`            | Get folder permissions                                                            |
| `add-permissions`            | Add folder permissions                                                            |
| `update-permissions`         | Update folder permissions                                                         |
| `revoke-permissions`         | Revoke folder permissions                                                         |
| `update-permission-settings` | Set the role every organization member holds on a folder and everything inside it |
| `bulk-update-labels`         | Bulk update folder labels                                                         |

```bash wrap theme={null}
# List folders
omni folders list

# Create a folder
omni folders create --body '{"name":"Blob Sales"}'

# View help for revoke-permissions command, including arguments and flag details
omni folders revoke-permissions --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Command groups - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/index

How Omni CLI commands map to the API, and where to find each command group.

<Tip>
  View the current OpenAPI spec using the [API Explorer](/api/api-explorer#openapi-specification) in your instance.
</Tip>

## How CLI commands map to the API

Most CLI commands are auto-generated from the Omni OpenAPI spec. For the Omni CLI, this means:

* **API tags become command groups**. For example, the `documents` API tag corresponds to the `omni documents` command group.

* **Path parameters become positional arguments**, such as `documentId` in the following example:

  ```bash wrap theme={null}
  # API endpoint
  POST /api/documents/<documentId>/duplicate

  # CLI
  omni documents duplicate <documentid>
  ```

* **Query parameters become flags**, such as `userId` in the following example:

  ```bash wrap theme={null}
  # API endpoint
  POST /api/documents/<documentId>/duplicate?userId=<userId>

  # CLI
  omni documents duplicate <documentid> --userid <userid>
  ```

* **Request bodies, `--schema`, and the `--query` escape hatch** work the same way across every command. See [JSON requests and responses](/developers/cli/reference/json-requests-and-responses) for the full details and examples.

The CLI sends a User-Agent header of the form `omni-cli/1.2.2` on every request, so you can tell its traffic apart from other API clients in your logs.

Run `omni <group> --help` to see all commands in a group or `omni <group> <command> --help` for command-specific argument and flag details.

## Command groups

| Group                                                                 | Description                                                                                |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [AI](/developers/cli/commands/ai)                                     | Query generation, jobs, conversations, credit controls                                     |
| [AI Eval](/developers/cli/commands/ai-eval)                           | Eval prompt sets and runs                                                                  |
| [AI model suggestions](/developers/cli/commands/ai-model-suggestions) | Generate, schedule, and manage suggested model improvements                                |
| [AI routines](/developers/cli/commands/ai-routines)                   | Scheduled prompts that run through the Omni Agent                                          |
| [API tokens](/developers/cli/commands/api-tokens)                     | Organization API tokens                                                                    |
| [Connections](/developers/cli/commands/connections)                   | Database connections, connection environments, dbt configuration, schema refresh schedules |
| [Content](/developers/cli/commands/content)                           | List and search content                                                                    |
| [Dashboards](/developers/cli/commands/dashboards)                     | Dashboard downloads and filters                                                            |
| [Documents](/developers/cli/commands/documents)                       | Documents, drafts, permissions, labels, favorites, v2 content and app editing              |
| [Embed](/developers/cli/commands/embed)                               | Embedded SSO sessions                                                                      |
| [Folders](/developers/cli/commands/folders)                           | Folders and folder permissions                                                             |
| [Labels](/developers/cli/commands/labels)                             | Content labels                                                                             |
| [Models](/developers/cli/commands/models)                             | Models, views, fields, topics, branches, Git, dbt                                          |
| [Query](/developers/cli/commands/query)                               | Run and monitor query execution                                                            |
| [Schedules](/developers/cli/commands/schedules)                       | Delivery schedules and recipients                                                          |
| [SCIM](/developers/cli/commands/scim)                                 | SCIM user and group provisioning                                                           |
| [Unstable](/developers/cli/commands/unstable)                         | Preview commands that may change without notice                                            |
| [Uploads](/developers/cli/commands/uploads)                           | CSV and Excel file uploads                                                                 |
| [User attributes](/developers/cli/commands/user-attributes)           | User attribute definitions                                                                 |
| [Users](/developers/cli/commands/users)                               | User and group model roles, email-only users, user attribute values                        |
| [Whoami](/developers/cli/commands/whoami)                             | The authenticated caller's identity and permissions                                        |
| [Config & utility](/developers/cli/commands/utility)                  | `omni config`, `omni agent-help`, `omni completion`, `omni update`                         |


# Labels commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/labels

Reference for the omni labels command group: create and manage content labels.

Create and manage [content labels](/api/labels).

```bash wrap theme={null}
omni labels <command>
```

| Command  | Description         |
| -------- | ------------------- |
| `list`   | List all labels     |
| `create` | Create a label      |
| `get`    | Get a label by name |
| `update` | Update a label      |
| `delete` | Delete a label      |

```bash wrap theme={null}
# Create a label
omni labels create --body '{"name":"important","color":"#0366d6"}'

# Get a label by name
omni labels get <name>

# View help for delete command, including arguments and flag details
omni labels delete --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Models commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/models

Reference for the omni models command group: models, views, fields, topics, branches, and Git configuration.

Manage models, views, fields, topics, branches, [git configuration](/api/model-git-configuration), and YAML. See the [Model API documentation](/api/models) for more information.

```bash wrap theme={null}
omni models <command>
```

<Warning>
  `delete` moves the model to the trash together with the workbooks, dashboards, and child extension models built on it, and requires Connection Admin. To delete a branch instead, use `delete-branch`.

  `git-rotate-webhook-secret` returns the new secret only in its response, so save it before moving on. The old secret stops validating immediately, so webhook deliveries fail signature verification until you set the new value in your git provider. Models that share a git repository share one secret.
</Warning>

| Command                     | Description                                                                      |
| --------------------------- | -------------------------------------------------------------------------------- |
| `list`                      | List models                                                                      |
| `create`                    | Create a model                                                                   |
| `update`                    | Update model                                                                     |
| `delete`                    | Move a shared or shared extension model to the trash, with its dependent content |
| `model-ai-agent-actions`    | Get model AI agent actions                                                       |
| `create-branch`             | Create a branch of a model                                                       |
| `get-views`                 | Get model views                                                                  |
| `get-schemas`               | List available schemas for a model                                               |
| `update-view`               | Update a view                                                                    |
| `delete-view`               | Delete a view                                                                    |
| `create-field`              | Create a field                                                                   |
| `update-field`              | Update a field                                                                   |
| `delete-field`              | Delete a field                                                                   |
| `list-topics`               | List topics                                                                      |
| `get-topic`                 | Get a topic                                                                      |
| `update-topic`              | Update a topic                                                                   |
| `delete-topic`              | Delete a topic                                                                   |
| `refresh`                   | Refresh model schema                                                             |
| `jobs-get-status`           | Get schema refresh or dbt sync job status                                        |
| `validate`                  | Validate a model                                                                 |
| `migrate`                   | Migrate a model                                                                  |
| `delete-branch`             | Delete a branch                                                                  |
| `branch-dbt`                | Set branch dbt environment                                                       |
| `branch-dbt-get`            | Read branch dbt environment                                                      |
| `dbt-sync`                  | Trigger a dbt metadata sync for a branch                                         |
| `dbt-exposures`             | Get dbt exposures                                                                |
| `merge-branch`              | Merge a branch                                                                   |
| `cache-reset`               | Reset cache for policy                                                           |
| `git-get`                   | Get git configuration                                                            |
| `git-create`                | Create git configuration                                                         |
| `git-update`                | Update git configuration                                                         |
| `git-delete`                | Delete git configuration                                                         |
| `git-sync`                  | Sync model with git                                                              |
| `git-rotate-signing-key`    | Rotate commit signing key                                                        |
| `git-rotate-webhook-secret` | Rotate the pull request webhook signing secret                                   |
| `commit`                    | Commit branch to git                                                             |
| `content-validator-get`     | Validate content references                                                      |
| `content-validator-replace` | Replace content references                                                       |
| `yaml-get`                  | Get model YAML                                                                   |
| `yaml-create`               | Update model YAML                                                                |
| `yaml-delete`               | Delete a model YAML file                                                         |

```bash wrap theme={null}
# List models (including IDs)
omni models list --compact

# Create a branch of a model
omni models create-branch <model-id> --name "add-new-columns"

# View help for yaml-create command, including arguments and flag details
omni models yaml-create --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Query commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/query

Reference for the omni query command group: run and monitor queries.

Run and monitor query execution. See the [Query API documentation](/api/queries) for more information.

```bash theme={null}
omni query <command>
```

| Command | Description                     |
| ------- | ------------------------------- |
| `run`   | Execute a semantic query        |
| `wait`  | Wait for query jobs to complete |

```bash wrap theme={null}
# Run a semantic query
omni query run --body '{"modelId":"MODEL_ID","query":{"fields":["view_name/field_name"],"limit":100}}'

# View help for wait command, including arguments and flag details
omni query wait --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Schedules commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/schedules

Reference for the omni schedules command group: delivery schedules and recipients.

Manage delivery [schedules](/api/schedules) and [recipients](/api/schedule-recipients).

```bash wrap theme={null}
omni schedules <command>
```

| Command              | Description                 |
| -------------------- | --------------------------- |
| `list`               | List schedules              |
| `create`             | Create a schedule           |
| `get`                | Get a schedule              |
| `update`             | Update a schedule           |
| `delete`             | Delete a schedule           |
| `recipients-get`     | Get schedule recipients     |
| `add-recipients`     | Add schedule recipients     |
| `remove-recipients`  | Remove schedule recipients  |
| `pause`              | Pause a schedule            |
| `resume`             | Resume a schedule           |
| `trigger`            | Trigger a schedule          |
| `transfer-ownership` | Transfer schedule ownership |

```bash wrap theme={null}
# Pause a schedule
omni schedules pause <schedule-id>

# View help for transfer-ownership command, including arguments and flag details
omni schedules transfer-ownership --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# SCIM commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/scim

Reference for the omni scim command group: SCIM user and group provisioning.

SCIM user and group provisioning, including embed users. See the [Users API](/api/users) and [User groups API documentation](/api/user-groups) for more information.

```bash wrap theme={null}
omni scim <command>
```

| Command              | Description          |
| -------------------- | -------------------- |
| `users-list`         | List SCIM users      |
| `users-create`       | Create a SCIM user   |
| `users-get`          | Get a SCIM user      |
| `users-replace`      | Replace a SCIM user  |
| `users-update`       | Update a SCIM user   |
| `users-delete`       | Delete a SCIM user   |
| `embed-users-list`   | List embed users     |
| `embed-users-get`    | Get an embed user    |
| `embed-users-delete` | Delete an embed user |
| `groups-list`        | List SCIM groups     |
| `groups-create`      | Create a SCIM group  |
| `groups-get`         | Get a SCIM group     |
| `groups-replace`     | Replace a SCIM group |
| `groups-update`      | Update a SCIM group  |
| `groups-delete`      | Delete a SCIM group  |

```bash wrap theme={null}
# List maximum of 10 groups
omni scim groups-list --count "10"

# View help for users-create command, including arguments and flag details
omni scim users-create --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Unstable commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/unstable

Reference for the omni unstable command group: preview commands that may change without notice.

Preview commands that may change without notice.

```bash wrap theme={null}
omni unstable <command>
```

| Command            | Description       |
| ------------------ | ----------------- |
| `documents-export` | Export a document |
| `documents-import` | Import a document |

```bash wrap theme={null}
# View help for documents-export command, including arguments and flag details
omni unstable documents-export --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Uploads commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/uploads

Reference for the omni uploads command group: manage CSV and Excel file uploads.

Manage CSV and Excel file uploads. See the [Uploads API documentation](/api/uploads) for more information.

```bash wrap theme={null}
omni uploads <command>
```

| Command        | Description              |
| -------------- | ------------------------ |
| `list`         | List uploads             |
| `create`       | Upload a CSV file        |
| `replace-data` | Replace an upload's data |
| `delete`       | Delete an upload         |

```bash wrap theme={null}
# List uploads with 'country' in file name
omni uploads list --searchterm "country"

# View help for create command, including arguments and flag details
omni uploads create --help
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# User attributes commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/user-attributes

Reference for the omni user-attributes command group: view user attribute definitions.

View user attribute definitions. See the [User attributes API documentation](/api/user-attributes) for more information.

```bash wrap theme={null}
omni user-attributes list
```

| Command | Description                         |
| ------- | ----------------------------------- |
| `list`  | List all user attribute definitions |

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Users commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/users

Reference for the omni users command group: manage user and group model roles, email-only users, and user attribute values.

Manage [user](/api/user-model-roles) and [group model roles](/api/user-group-model-roles), and [email-only users](/api/users/list-email-only-users).

```bash wrap theme={null}
omni users <command>
```

| Command                         | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `get-model-roles`               | Get user model roles                               |
| `assign-model-role`             | Assign a model role to a user                      |
| `list-email-only`               | List email-only users                              |
| `create-email-only`             | Create or update an email-only user                |
| `create-email-only-bulk`        | Create email-only users in bulk                    |
| `set-attributes`                | Set Omni user attribute values on an existing user |
| `user-groups-get-model-roles`   | Get user group model roles                         |
| `user-groups-assign-model-role` | Assign a model role to a user group                |

```bash wrap theme={null}
# Create an email-only user
omni users create-email-only --body '{"email":"blob.ross@blobsrus.com"}'

# View help for user-groups-assign-model-role command, including arguments and flag details
omni users user-groups-assign-model-role --help
```

## omni users set-attributes

Sets [user attribute](/administration/users/attributes) values on an existing user via a SCIM PATCH, changing only the attributes you name. Identify the user by SCIM user ID or by email (any value containing `@` is resolved to an ID via a SCIM lookup first).

```bash wrap theme={null}
# Set string attributes by user ID
omni users set-attributes <user-id> --attr region=us-east --attr team=growth

# Identify the user by email instead, and clear an attribute
omni users set-attributes user@example.com --attr region=

# Set numeric or multi-value (array) attributes with --attr-json
omni users set-attributes user@example.com --attr-json '{"level":3,"regions":["us","eu"]}'
```

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Config and utility commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/utility

Manage CLI configuration profiles, and the agent-help, completion, and update utility commands.

Manage CLI configuration profiles, and run the `agent-help`, `completion`, and `update` utility commands. None of them need an authenticated profile.

## omni config init

Interactively create a new configuration profile. Prompts for a profile name, API endpoint, and authentication method. See [CLI authentication](/developers/cli/authentication) for more details about OAuth and API token authentication.

```bash theme={null}
omni config init
```

You can authenticate with OAuth or an API token:

* **OAuth** opens a browser-based login flow. Approving the verified **Omni CLI** application creates a user-scoped credential for the profile.
* **API token** stores the token in the profile. You can also set `OMNI_API_TOKEN` or pass `--token` to override the profile token.

## omni config login

Authenticate a profile with browser-based OAuth. If you don't provide a profile name, the CLI uses the default profile.

```bash theme={null}
omni config login
omni config login <profile>
```

## omni config logout

Clear OAuth tokens from a profile. If you don't provide a profile name, the CLI uses the default profile.

```bash theme={null}
omni config logout
omni config logout <profile>
```

## omni config show

Display the current configuration. Tokens are redacted in the output.

```bash theme={null}
omni config show
```

## omni config use

Switch the default profile.

```bash theme={null}
omni config use <profile>
```

## omni config list

List configured profiles.

```bash theme={null}
omni config list
```

## omni config rename

Rename a profile.

```bash theme={null}
omni config rename <old_name> <new_name>
```

## omni config delete

Delete a profile.

```bash theme={null}
omni config delete <profile>
```

## omni config set-format

Set the profile's default output format, overriding the built-in `auto` default. Format must be one of `json`, `human`, `auto`.

See [output formats](/developers/cli/reference/output-formats) for more information.

```bash theme={null}
omni config set-format human
```

## omni agent-help

Print a concise usage guide formatted for AI agents.

```bash theme={null}
omni agent-help
```

## omni completion

Generate a shell autocompletion script for `bash`, `fish`, `powershell`, or `zsh`.

```bash theme={null}
omni completion zsh
```

Run `omni completion <shell> --help` for that shell's install instructions.

## omni update check

Check whether a newer Omni CLI release is available. `check` is the only `omni update` subcommand - the CLI doesn't upgrade itself.

```bash theme={null}
omni update check
omni update check --format json --compact
```

The command always contacts the release endpoint and prints human-readable output by default; add `--format json` for a machine-readable answer. It reports the current and latest versions, the release URL, and the upgrade command for your install method. On failure it writes the standard JSON error envelope to `stderr` and exits non-zero.

See [installing the Omni CLI](/developers/cli/install#staying-up-to-date) for how to upgrade.

## Automatic update notices

The CLI also checks in the background and prints a notice on `stderr` after a successful command. The notice never touches `stdout`, so pipelines are unaffected.

The check is throttled to one successful check every 24 hours across every process on the machine, coordinated through a lock file next to `update.json` in your OS user cache directory. A failed or cancelled attempt backs off for 15 minutes instead of retrying on the next command.

Notices are suppressed for:

* Output that isn't human format, including `--format json`, `--schema` requests, and `omni config show`
* Non-interactive invocations, where `stdout` or `stderr` isn't a terminal
* The `omni update` and `omni completion` command groups
* The `CI` and `OMNI_NO_UPDATE_NOTIFIER` environment variables, when either is set
* Builds that aren't a tagged release

The CLI detects a Homebrew install from the binary path and points those users at `brew upgrade omni`. Because the formula can lag the release, Homebrew users aren't notified about a release in its first 24 hours. Windows users are pointed at the release downloads, because `install.sh` doesn't run there.

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Whoami commands - Omni CLI
Source: https://docs.omni.co/developers/cli/commands/whoami

Reference for the omni whoami command group: check the authenticated caller's identity and permissions.

Discover the authenticated caller's own identity, API key scope, organization role, and resolved per-model permissions, without attempting an action. Useful for verifying a profile or token before scripting against it. See the [Who Am I API documentation](/api/who-am-i) for more information.

```bash theme={null}
omni whoami whoami
```

| Command  | Description                                   |
| -------- | --------------------------------------------- |
| `whoami` | Get current identity and permissions (whoami) |

<Note>
  Every command in this group also accepts the [global flags](/developers/cli/reference/global-flags), including `--token`, `--profile`, `--format`, and `--compact`.
</Note>


# Omni CLI
Source: https://docs.omni.co/developers/cli/index

Manage your Omni instance from the terminal — query data, manage models, administer users, and automate workflows.

<Note>
  **Using a coding agent?** Paste this prompt into Claude Code, Cursor, Codex, or any coding agent and it will install the Omni CLI for you:

  ```text theme={null}
  Install the Omni CLI from https://github.com/exploreomni/cli
  ```
</Note>

The Omni CLI lets you manage your Omni instance from the terminal. Use it to query data, manage models and content, administer users and permissions, and automate workflows with scripts or CI/CD pipelines.

## What you can do

* Run queries against your semantic layer
* Manage models, views, fields, topics, and branches
* Create, update, and organize documents, dashboards, and folders
* Manage users, groups, permissions, and schedules
* Generate AI-powered queries from natural language
* Upload CSV and Excel files
* Automate any of the above with shell scripts or CI/CD

## Get started

<Columns>
  <Card title="Install" icon="download" href="/developers/cli/install">
    Install the CLI via Homebrew, an install script, or GitHub releases.
  </Card>

  <Card title="Authenticate" icon="key" href="/developers/cli/authentication">
    Connect using OAuth (recommended) or an API key.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/developers/cli/quickstart">
    Configure a profile and run your first commands.
  </Card>
</Columns>

<Tip>
  Once the CLI is installed, you can use [Omni's agent skills](/developers/agent-skills) to bring analytics capabilities directly into AI coding assistants like Claude Code, Cursor, and Codex.
</Tip>

## Output

By default, commands print human-readable output on a terminal and JSON when piped or redirected. Errors always go to `stderr` as JSON.

Override the default with:

* `--format json` — force JSON output even on a terminal
* `--compact` — print non-indented JSON, useful for piping to tools like `jq`

See [output formats](/developers/cli/reference/output-formats) for details.

## Available commands

See the [Commands reference](/developers/cli/commands) for the complete list of CLI commands.

## Related

* [Omni REST API reference](/api)
* [Agent skills](/developers/agent-skills)
* [CLI commands reference](/developers/cli/commands)

## Contributing

Contributions to the Omni CLI are welcome. Open a pull request or file an issue in the [GitHub repository](https://github.com/exploreomni/cli).


# Installation - Omni CLI
Source: https://docs.omni.co/developers/cli/install

Install the Omni CLI on macOS, Linux, or Windows.

## Prerequisites

* A supported OS:
  * macOS (amd64, arm64)
  * Linux (amd64, arm64)
  * Windows (amd64)
* A terminal with permission to install binaries on your `PATH`

## Homebrew (macOS, Linux) (preferred)

If you use Homebrew, install the CLI with:

```bash theme={null}
brew tap exploreomni/tap
brew install omni
```

## Install script (macOS, Linux)

Run the following to download the latest release, verify the SHA-256 checksum, and install the `omni` binary to `/usr/local/bin` (or `~/.local/bin` if `/usr/local/bin` is not writable):

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/exploreomni/cli/main/install.sh | sh
```

## GitHub releases (macOS, Linux, Windows)

Pre-built binaries for macOS, Linux, and Windows are available in the CLI repository on the [Releases page](https://github.com/exploreomni/cli/releases). Download the archive for your platform, extract it, and place the `omni` binary somewhere on your `PATH`.

| Platform | Architectures |
| -------- | ------------- |
| macOS    | amd64, arm64  |
| Linux    | amd64, arm64  |
| Windows  | amd64         |

## Build from source

```bash theme={null}
git clone https://github.com/exploreomni/cli.git
cd cli
make build
```

The binary is written to `./bin/omni`.

## Staying up to date

In an interactive terminal, the CLI checks for a newer release in the background and prints a notice after a command succeeds. Builds from source aren't checked, because they aren't tagged releases. Check explicitly with:

```bash theme={null}
omni update check
```

Upgrade the same way you installed: `brew upgrade omni`, re-running the install script, or downloading the new archive from the [Releases page](https://github.com/exploreomni/cli/releases). See [update notices](/developers/cli/commands/utility#update-notices) for how the automatic check behaves and how to turn it off.

## Troubleshooting

### `omni: command not found`

The binary is likely installed outside your current `PATH`.

* If installed to `~/.local/bin`, add it to your shell profile.
* Restart your terminal, then run `omni --help`.

### Permission denied when installing

If you do not have write access to `/usr/local/bin`, use the install script. It automatically falls back to `~/.local/bin`.

### Homebrew cannot find `omni`

Re-run the tap command, then install again:

```bash theme={null}
brew tap exploreomni/tap
brew install omni
```

## Next steps

* Follow the [CLI quickstart](/developers/cli/quickstart) to configure your profile and authenticate with OAuth or an API token
* Use the [commands reference](/developers/cli/commands) to explore available commands


# Quickstart - Omni CLI
Source: https://docs.omni.co/developers/cli/quickstart

Configure the Omni CLI and run your first commands.

This guide installs the Omni CLI, sets up a profile, authenticates, and runs your first commands.

## Requirements

To follow the steps in this guide, you'll need an Omni account. The CLI can authenticate with OAuth (recommended) or an API key; OAuth requires an Organization Admin to have enabled Personal Access Tokens first. See [CLI authentication](/developers/cli/authentication) for details on both methods.

## Steps

<Steps>
  <Step title="Install the CLI">
    See the [CLI installation guide](/developers/cli/install).
  </Step>

  <Step title="Configure a profile">
    After you install the CLI, run:

    ```bash theme={null}
    omni config init
    ```

    This creates a profile with a name, an API endpoint, and an authentication method. You can create multiple profiles for different organizations or environments.
  </Step>

  <Step title="Authenticate">
    Choose one of the following authentication methods:

    <Tabs>
      <Tab title="OAuth (recommended)" icon="trophy">
        Run the following command and authorize in your browser:

        ```bash theme={null}
        omni config login
        ```
      </Tab>

      <Tab title="API key" icon="key">
        Either enter your API token during `config init`, or set the environment variable:

        ```bash theme={null}
        export OMNI_API_TOKEN=omni_osk_...
        ```
      </Tab>
    </Tabs>

    See [CLI authentication](/developers/cli/authentication) for more details on both methods.
  </Step>

  <Step title="Run your first commands">
    ```bash theme={null}
    omni whoami whoami
    omni models list
    omni documents list
    omni --help
    ```

    * `omni whoami whoami` (yes, `whoami` twice: it's the `whoami` command group's own `whoami` subcommand) confirms your identity, key scope, and permissions without changing anything. It's a good first call after authenticating.
    * `omni models list` lists the models you can query.
    * `omni documents list` lists the workbooks and dashboards you can access.
    * `omni --help` lists every available command group.
  </Step>
</Steps>

## Next steps

* Install [agent skills](/developers/agent-skills)
* Learn about [Omni APIs](/api)


# Environment variables - Omni CLI
Source: https://docs.omni.co/developers/cli/reference/environment-variables

Environment variables the Omni CLI reads, and how they interact with flags and the config file.

The Omni CLI reads the following environment variables:

| Variable                                       | Description                                                                                                                                                                             |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OMNI_API_TOKEN`                               | API token. Overrides the active profile's token; overridden by `--token`.                                                                                                               |
| `OMNI_BASE_URL`                                | API base URL. Overrides the active profile's endpoint; overridden by `--base-url`.                                                                                                      |
| `OMNI_OUTPUT_FORMAT`                           | Default output format (`json`, `human`, or `auto`). Overrides the config file's default; overridden by `--format`/`-o`. See [output formats](/developers/cli/reference/output-formats). |
| `OMNI_CONFIG_PATH`                             | Overrides the full path to the config file. Takes precedence over `OMNI_CONFIG_DIR`.                                                                                                    |
| `OMNI_CONFIG_DIR`                              | Overrides the config directory (the config file lives at `<dir>/config.json`). Takes precedence over `XDG_CONFIG_HOME`.                                                                 |
| `XDG_CONFIG_HOME`                              | Used to locate the config directory (`<XDG_CONFIG_HOME>/omni-cli`) on Unix when `OMNI_CONFIG_DIR` isn't set. Follows the same convention as the GitHub CLI; has no effect on Windows.   |
| `OMNI_NO_UPDATE_NOTIFIER`                      | Set to any value to disable the automatic [update notice](/developers/cli/commands/utility#update-notices). `omni update check` still works.                                            |
| `CI`                                           | Set to any value to skip the automatic [update notice](/developers/cli/commands/utility#update-notices). Most CI providers set this for you.                                            |
| `OMNI_CLI_DANGEROUSLY_ALLOW_INSECURE_REQUESTS` | Bypasses the HTTPS and Omni-domain checks the CLI otherwise enforces before sending a token or OAuth credential.                                                                        |

<Warning>
  `OMNI_CLI_DANGEROUSLY_ALLOW_INSECURE_REQUESTS` disables the checks that protect your API token and OAuth credential in transit. Only set it against a trusted local or test endpoint, never in a real profile pointed at your Omni organization.
</Warning>

See [authentication](/developers/cli/authentication) for how `OMNI_API_TOKEN` fits into OAuth vs. API key authentication. See [CLI configuration](/developers/cli/commands/utility) for the config file these variables override.


# Errors and exit codes - Omni CLI
Source: https://docs.omni.co/developers/cli/reference/errors-and-exit-codes

How the Omni CLI signals success and failure to scripts, and where error detail goes.

The Omni CLI signals success or failure with two exit codes:

| Exit code | Description                                                                                                                                                       |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`       | The command succeeded.                                                                                                                                            |
| `1`       | The command failed: an API error, an [authentication or config-resolution error](/developers/cli/reference/environment-variables), or an unrecognized subcommand. |

You can't branch on the exit code to tell failure types apart. An unrecognized subcommand, such as a typo like `omni document list`, counts as a failure too, even though an invalid invocation can otherwise look like a successful `--help` print. Anything other than `0` means the command didn't complete successfully, which is enough to script against:

```bash theme={null}
if ! omni documents get "$id" --compact > out.json; then
  echo "fetch failed" >&2
  exit 1
fi
```

## Where the error detail goes

On failure, the CLI writes nothing to `stdout`, even a partial response, and writes exactly one error document to `stderr`. See [JSON requests and responses](/developers/cli/reference/json-requests-and-responses#errors) for its exact shape in `--format json` versus `--format human`.


# Global flags - Omni CLI
Source: https://docs.omni.co/developers/cli/reference/global-flags

Flags available on every Omni CLI command.

These flags are available on all commands:

| Flag              | Description                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `--help`, `-h`    | View help                                                                                            |
| `--token TOKEN`   | API token (overrides environment variable and config profile)                                        |
| `--base-url URL`  | API base URL (overrides config profile)                                                              |
| `--profile NAME`  | Config profile to use                                                                                |
| `--compact`       | Non-indented JSON output (useful for piping to `jq`)                                                 |
| `--format`, `-o`  | Output format: `json`, `human`, or `auto` (default `auto`: human-readable on a TTY, JSON when piped) |
| `--version`, `-v` | Print the CLI version                                                                                |


# JSON requests and responses - Omni CLI
Source: https://docs.omni.co/developers/cli/reference/json-requests-and-responses

The shape of request bodies, response payloads, and error output for Omni CLI commands.

Every Omni CLI command that sends or receives data uses the same JSON conventions, whatever the command group. This page covers how to pass a request body, what a successful response looks like, what the CLI writes when a request fails, and how to reach a query parameter the CLI has no flag for.

## Request bodies

Pass a request body with `--body`, in one of three forms:

* An inline JSON string: `--body '{"name":"Blob Sales"}'`
* A file path prefixed with `@`: `--body @request.json`
* `-` to read from stdin: `--body -`

The CLI validates the body as JSON before sending it, so a malformed payload fails locally instead of round-tripping to the API first. Simple bodies can also be set field-by-field with a command's promoted flags instead of `--body` (shown in that command's `--help` output). The two approaches can't be combined on the same call.

<Tip>
  Run any command with `--schema` to print its arguments, flags, request body shape, and response shape without making an API call. For example:

  ```bash theme={null}
  omni documents duplicate --schema
  ```
</Tip>

## Response payloads

A successful response (`--format json`, the default when output is piped) is the API's JSON body, unmodified, and `--compact` prints it non-indented, which is easier to pipe into `jq` or other tools. List endpoints return one of two shapes:

```json theme={null}
// Paginated list
{ "records": [ /* ... */ ], "pageInfo": { "hasMore": true, "cursor": "abc123" } }

// Non-paginated list, resource-named
{ "connections": [ /* ... */ ] }
```

A single-resource endpoint (get, create, update, delete) returns that resource's JSON object directly, with no wrapper.

See [output formats](/developers/cli/reference/output-formats) for how `--format human` renders these same payloads as tables and key-value summaries instead.

## Errors

A failed request writes nothing to `stdout`, even a partial response body, and writes exactly one JSON document to `stderr`:

```json theme={null}
{
  "error": "<human-readable detail, extracted from the upstream error body when possible>",
  "status": 404,
  "body": { "...": "the raw upstream error body, omitted if there wasn't one" }
}
```

In `--format human`, the same failure prints as a single line instead: `Error: <detail> (HTTP <status>)`. See [errors and exit codes](/developers/cli/reference/errors-and-exit-codes) for what a failure means for the process's exit code.

## Query escape hatch

If the CLI's generated flags for a command don't cover a query parameter the API supports (for example, one added to the API after this CLI version was built), add it with the `--query` escape hatch instead. It's repeatable, for multiple parameters:

```bash theme={null}
omni documents list --query "includeArchived=true" --query "labelId=lbl_123"
```

Required query parameters that aren't supplied, whether by a named flag or `--query`, cause the CLI to fail before sending a request, rather than letting the API reject an incomplete call.

<Note>
  A list command's pagination flags (a cursor, a page size, or both) aren't named consistently across every command. Check that command's own `--help` output for the exact flag name.
</Note>


# Output formats - Omni CLI
Source: https://docs.omni.co/developers/cli/reference/output-formats

How the Omni CLI chooses between human-readable and JSON output, and how to control it.

By default (`auto`), commands print human-readable tables and key-value summaries when connected to a terminal, and compact JSON when output is piped or redirected. Pass `--format` (or `-o`) to force one:

```bash theme={null}
omni models list --format human   # a table, even when piped
omni models list --format json    # JSON, even on a TTY
```

Set a profile's default with [`omni config set-format`](/developers/cli/commands/utility#set-format) so you don't have to pass `--format` every time. `--compact` (non-indented JSON) still applies in `json` mode.


# Managing AI credits for embed entity groups
Source: https://docs.omni.co/embed/admin/ai-credits

Set default and per-group credit limits for embed entity groups.

Embed entity groups are automatically created groups that correspond to embed entities, defined with the `entity` parameter in embed URL requests. You can set AI credit limits for these groups to control how much AI usage is allowed for users within each entity. This is useful when embedding Omni for multiple customers or tenants and you want to manage AI consumption on a per-entity basis.

## How embed entity group limits work

Along with [organization-level][org-limits] and [user-level][user-limits] AI credit controls, embed entity group controls allow you to limit AI credit consumption at the entity group level.

You can set group-specific limits and a default that applies to all entity groups, allowing you to control how many credits specific groups can consume. For example, you can set a higher limit for groups with more contracted usage and let other groups use the entity group default.

## Requirements

To manage AI credit limits for embed entity groups, you'll need:

* **Organization Admin** permissions
* The **Embed** feature enabled in your Omni instance

## Setting an embed entity group default

An embed entity group default applies to all entity groups. When set, the limit will act as the default for any group that doesn't have a [specific limit](#per-group-limits).

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **AI Hub > General**.
    2. Click the **Credits** tab.
    3. In the **Embed entity settings** section, enter the number of credits in the default limit field, or leave it empty to allow unlimited credits by default.
    4. Click **Save**.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update AI credit limits](/api/ai-credit-controls/update-ai-credit-controls) endpoint and include the `entityGroupDefaultCredits` parameter in the request body:

    ```http theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "downgradeCredits": 800,
      "shutoffCredits": 1200,
      "userDefaultCredits": 100,
      "entityGroupDefaultCredits": 100
    }
    '
    ```
  </Tab>
</Tabs>

## Setting per-group credit limits

Each embed entity group has its own detail page where you can configure a credit limit specific to that group. When set:

* The group-level limit will override the [embed entity group default](#embed-entity-default)
* An entity group user's usage will count against [their individual user limit (if set)][user-limits] and their entity group's limit

To configure a credit limit for an embed entity group:

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. Navigate to **AI Hub > General**.
    2. Click the **Credit usage** tab.
    3. Click the **By entity** toggle to display a list of entities.
    4. In the row for the entity group, click the **Edit limit** button.
    5. In the dialog that displays, configure the entity's credit limit:
       * **To set a cap**, enter a whole number (ex: `40`) in the **Credit limit** field
       * **To allow unrestricted usage**, click the **Unlimited** toggle
       * **To reset to the [embed entity group default](#embed-entity-default)**, click **Reset to default**
    6. Click **Save**.

    You can also set a credit limit for an entity in their [group settings](/embed/admin/entities#settings).
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Set individual entity groups' AI credit limits](/api/ai-credit-controls/set-individual-entity-groups-ai-credit-limits) endpoint:

    ```http wrap theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls/entity-groups \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "entityGroups": [
        {
          "entity": "blobsrus",
          "creditLimit": 50
        }
      ]
    }
    '
    ```
  </Tab>

  <Tab title="Embed" icon="chart-column">
    Set the limit via the [`entityAiCreditLimit` URL parameter](/embed/setup/url-parameters/entityAiCreditLimit) when logging in the embed user:

    ```markdown theme={null}
    entityAiCreditLimit=50
    ```

    <Note>
      Use `entityAiCreditLimit=unlimited` to explicitly remove the cap, or omit the parameter to fall back to the [embed entity group default](#embed-entity-default).
    </Note>
  </Tab>
</Tabs>

## Monitoring entity group credit usage

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    To view entity group credit usage in the Omni UI:

    1. Navigate to **AI Hub > General**.
    2. Click the **Credit usage** tab.
    3. Click the **By entity** toggle to switch to the entity group view.
  </Tab>

  <Tab title="API" icon="cloud">
    To get an entity group's usage for the current billing period, use the [Read individual entity groups' AI credit limits](/api/ai-credit-usage/read-individual-entity-groups-ai-credit-usage) endpoint and include the entity in the request body's `entities` parameter:

    ```http wrap theme={null}
    curl --request POST \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-usage/entity-groups \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "entities": [
        "blobsrus"
      ]
    }
    '
    ```
  </Tab>
</Tabs>

## Next steps

* [Managing AI credit usage][ai-controls] — Learn about AI credits, organization-level and user-level controls, and monitoring tools
* [Managing embed users](/embed/admin/users) — View, manage, and impersonate users in your embedded Omni application

[ai-controls]: /ai/settings/usage

[org-limits]: /ai/settings/usage#organization-level-credit-controls

[user-limits]: /ai/settings/usage#user-level-credit-controls


# Managing embed entity groups
Source: https://docs.omni.co/embed/admin/entities

View and manage embed entity groups in your embedded Omni application.

<Note>
  **Organization Admin** permissions are required to manage entity groups.
</Note>

Embed entities are used to associate individual [embed users](/embed/admin/users) with a larger group. Unlike standard Omni user groups, [embed entities are provisioned programmatically](/embed/setup/url-parameters/entity). The **Settings > Groups > Embed** tab lets Organization Admins view and manage entity groups.

## Viewing embed entity groups

The **Embed** groups tab displays the following information about each entity group:

* **Name** - The name of the entity
* **Description** - A description, if one is defined
* **Label** - A label, if one is defined
* **Members** - The total number of users in the entity
* **Group ID** - The unique identifier for the entity in your system

## Managing embed entity group settings

To update an entity's information:

1. In **Settings > Groups > Embed tab**, click an entity.
2. Click the **Settings** tab.
3. Update the **Name**, **Label**, and **Description** fields.
4. Click **Save**.

To update an entity's [AI credit limit](/embed/admin/ai-credits):

1. In **Settings > Groups > Embed tab**, click an entity.
2. Click the **Settings** tab.
3. Scroll to the **AI settings** section.
4. Click the **Edit** button.
5. In the dialog that displays, configure the entity's credit limit:
   * **To set a cap**, enter a whole number (ex: `40`) in the **Credit limit** field
   * **To allow unrestricted usage**, click the **Unlimited** toggle
   * **To reset to the [embed entity group default](/embed/admin/ai-credits#embed-entity-default)**, click **Reset to default**
6. Click **Save**.


# Embed administration
Source: https://docs.omni.co/embed/admin/index

Manage embed secrets, security, users, entities, and sessions for your organization.

<Note>
  **Organization Admin** permissions are required to manage embed settings.
</Note>

Embed administration covers the settings that control how Omni runs inside your application: the secrets that sign your embed URLs, the security restrictions applied to embedded content, and the embed users, entities, and sessions your application creates.

<Columns>
  <Card title="Secrets" icon="key" href="/embed/admin/secrets">
    Create, view, edit, and delete embed secrets
  </Card>

  <Card title="Content security" icon="shield" href="/embed/admin/security">
    Control security and access restrictions for embedded content
  </Card>

  <Card title="Sessions" icon="clock" href="/embed/admin/sessions">
    View and delete Omni embed user sessions
  </Card>

  <Card title="Users" icon="user" href="/embed/admin/users">
    View, manage, and impersonate embed users
  </Card>

  <Card title="Entities" icon="users" href="/embed/admin/entities">
    View and manage embed entity groups
  </Card>

  <Card title="AI credits" icon="robot" href="/embed/admin/ai-credits">
    Define AI credit limits for embed entity groups and monitor usage
  </Card>

  <Card title="Integrations" icon="engine" href="/embed/admin/integrations">
    Configure third-party integrations like FullStory and LogRocket
  </Card>
</Columns>


# Configuring embed integrations
Source: https://docs.omni.co/embed/admin/integrations

Configure third-party integrations like FullStory and LogRocket for your embedded Omni instance.

<Note>
  Reach out to Omni support to have this feature enabled.
</Note>

The **Settings > Embed > Admin** tab allows you to configure third-party integrations for your embedded Omni instance. These integrations enable advanced monitoring, session recording, and analytics capabilities for your embedded content.

When an integration is configured:

* The integration's tracking script is loaded when users access your embedded Omni content
* Session data and user interactions are sent to the configured integration service

## Supported integrations

Omni supports the following embed integrations:

* **FullStory** - Session recording and analytics platform that captures user interactions
* **LogRocket** - Session replay and analytics tool for debugging and understanding user behavior

## Requirements

To configure embed integrations, you'll need:

* **Organization Admin** permissions
* To have the **Embed integrations** feature enabled in your Omni instance
* Valid credentials for the integration service you want to configure

## Configuring an integration

To configure a new embed integration:

<Steps>
  <Step title="Set up your embedding application">
    Complete the setup for your integration. Click a tab to view instructions for a specific integration.

    <AccordionGroup>
      <Accordion title="FullStory">
        In order for FullStory to include an Omni iframe in session recordings, the embedding application needs to do the following:

        * Initiate FullStory
        * Send an `integration:enable` event with `payload.name "fullstory"`

        ```javascript expandable wrap theme={null}
        // Using FullStory sdk
        import { FullStory, init } from '@fullstory/browser';

        export default function Index() {
          const [url1]: string = useLoaderData();
          const [omniReady, setOmniReady] = useState(false)

          // Listen for events from Omni.
          useEffect(() => {
            const listener = async (event: MessageEvent) => {
              switch (event.data.name) {
                // When a page:changed event is emitted from Omni, we can assume the Omni iframe is loaded
                // and ready to receive events from the parent page.
                case "page:changed": {
                  setOmniReady(true);
                  break;
                }
              }
            };
            window.addEventListener("message", listener);
          }, []);

          // Send integration:enable event to Omni when ready and initialize FullStory.
          useEffect(() => {
            if (omniReady) {
              // Send integration:enable event to Omni via postMessage to iframe.
              document
                .querySelector("iframe")
                ?.contentWindow?.postMessage(
                  {
                    name: 'integration:enable',
                    payload: { name: 'fullstory' }, // Payload must include name: 'fullstory'
                  },
                  '*'
                );

              // Initialize FullStory
              init({ orgId: '[YOUR_FULLSTORY_ORG_ID]' }, () => {
                // Note: Unlike LogRocket, FullStory requires the parent application
                // handle identification.
                FullStory('setIdentity', {
                  properties: {
                    displayName: '[YOUR_TRACKED_USERS_NAME]',
                  },
                  uid: '[YOUR_TRACKED_USERS_UID]',
                  })
              });
            }
          }, [omniReady]);

          return (
            <div
              style={{
                fontFamily: "system-ui, sans-serif",
                lineHeight: "1.8",
                width: "100%",
                height: "100%",
              }}
            >
              <iframe src={url1} width={"100%"} height={"800px"} />
            </div>
          );
        }
        ```
      </Accordion>

      <Accordion title="LogRocket">
        <Note>
          Omni automatically identifies embed users in LogRocket using their associated external ID, name, and email.
        </Note>

        In order for LogRocket to include an Omni iframe in session recordings, the embedding application needs to do the following:

        * Initiate LogRocket
        * Send an `integration:enable` event with `payload.name "logrocket"`

        ```javascript expandable wrap theme={null}
        // Import LogRocket sdk
        import LogRocket from "logrocket";

        export default function Index() {
          // Embed URL from server
          const [url1]: string = useLoaderData();
          const [omniReady, setOmniReady] = useState(false)

          // Add Omni event listener.
          useEffect(() => {
            const listener = async (event: MessageEvent) => {
              switch (event.data.name) {
                // When a page:changed event is emitted from Omni, we can assume the Omni iframe is loaded
                // and ready to receive events from the parent page.
                case "page:changed": {
                  setOmniReady(true);
                  break;
                }
              }
            };
            window.addEventListener("message", listener);
          }, []);

          // Send integration:enable event to Omni when ready and initiate LogRocket.
          useEffect(() => {
            // Wait for the Omni iframe to load before sending the `integration:enable` event.
            if (omniReady) {
              document
                .querySelector("iframe")
                ?.contentWindow?.postMessage(
                  {
                    name: "integration:enable",
                    payload: { name: 'logrocket', parentDomain: "[YOUR_PARENT_APPLICATION_DOMAIN]" }, // standard payload for enabling LogRocket
                  },
                  '*'
                );

              // Initiate LogRocket
              // Note: The mergeIframes and childDomains parameters are necessary to
              // make sure Omni iframes are included in session.
              LogRocket.init('[YOUR_LOGROCKET_APP_ID]', {
                mergeIframes: true,
                childDomains: ["[YOUR_OMNI_EMBED_DOMAIN]"]
              });
            }
          }, [omniReady]);

          return (
            <div
              style={{
                fontFamily: "system-ui, sans-serif",
                lineHeight: "1.8",
                width: "100%",
                height: "100%",
              }}
            >
              <iframe src={url1} width={"100%"} height={"800px"} />
            </div>
          );
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Configure the integration in Omni">
    1. Navigate to **Settings > Embed > Admin** in your Omni instance.
    2. Scroll to the **Integrations** section.
    3. Enter the required information for the integration:

       * **FullStory** - Enter your FullStory organization ID in the **Org ID** field
       * **LogRocket** - Enter your LogRocket app ID in the **App ID** field
    4. Click **Save** to apply the configuration.
  </Step>
</Steps>

Once configured, the integration will be active for all users accessing your embedded Omni instance.

## Removing an integration

<Note>
  Removing an integration will disable it for all new embed sessions. Existing sessions may continue to send data to the integration until the session expires.
</Note>

To remove an integration configuration:

1. Navigate to **Settings > Embed > Admin** in your Omni instance.
2. Scroll to the **Integrations** section.
3. Click the **Clear** button for the integration.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Embed integrations not visible in Omni">
    Embed integrations are a feature that must be enabled by Omni support. Reach out to support to request access.
  </Accordion>

  <Accordion title="Visualizations not rendering in FullStory">
    Support for [canvas rendering](https://help.fullstory.com/hc/en-us/articles/360020623094-Does-Fullstory-work-with-my-complex-site#h_01HMWCNWPDKH2M67SWXTPSZJYF), which is required to render Omni visualizations, is limited and may require a paid FullStory plan.
  </Accordion>
</AccordionGroup>

## Next steps

* [Manage embed secrets](/embed/admin/secrets)
* [View and impersonate embed users](/embed/admin/users)
* [View embed sessions](/embed/admin/sessions)


# Managing embed secrets
Source: https://docs.omni.co/embed/admin/secrets

Create, view, edit, and delete embed secrets for your organization.

Embed secrets are used to sign and authenticate embed URLs, ensuring that only authorized users can access your embedded content. Omni supports creating multiple secrets, which allows you to safely rotate and use different secrets for separate environments.

## Requirements

To manage embed secrets, you'll need:

* **Organization Admin** permissions
* The **Embed** feature enabled in your Omni instance

## Viewing embed secrets

Navigate to **Settings > Embed > Admin** to view embed secrets in your organization:

<Frame>
  <img alt="Embed secrets table in the Omni UI" />
</Frame>

From here you can [create](#create), [rename](#rename), [rotate](#rotate), and [delete](#delete) secrets.

## Creating secrets

To create a new embed secret:

1. Navigate to **Settings > Embed > Admin** in your Omni instance.
2. Click the **Add Secret** button below the secrets table.
3. In the dialog that appears:
   * A 32-character secret key is automatically generated for you
   * Enter a descriptive **Name** to identify the secret's purpose (e.g., "Production", "Staging", or "Partner Integration")

     <Tip>
       Use descriptive names for your secrets to make them easier to identify and manage, especially when rotating secrets or managing multiple environments.
     </Tip>
4. Click **Add secret** to save the new secret.

The new secret will appear in the secrets table and can be used immediately for signing embed URLs.

## Renaming secrets

<Note>
  Only the secret's **Name** can be edited - the secret key value itself cannot be changed. If you need a new secret key, [create a new secret](#create) instead.
</Note>

To rename an embed secret:

1. Navigate to **Settings > Embed > Admin**.
2. Click the **Edit** button in the **Actions** column for the secret you want to modify.
3. Update the **Name** field in the dialog.
4. Click **Save** to apply your changes.

## Rotating secrets

Because Omni allows multiple active secrets at the same time, you can rotate a secret without disrupting active embed sessions:

1. Create a new secret in **Settings > Embed > Admin**.
2. Update your applications to sign embed URLs with the new secret. Both the old and new secret will continue to authenticate embed URLs during this phase.
3. Verify that all environments are signing with the new secret and that no traffic is still using the old one.
4. Delete the old secret to immediately invalidate any URLs still signed with it.

<Warning>
  Skipping the verification step can break in-flight embed sessions signed with the old secret. Deleting a secret immediately invalidates every URL signed with it.
</Warning>

## Deleting secrets

To delete an embed secret:

1. Navigate to **Settings > Embed > Admin**.
2. Click the **Delete** button in the **Actions** column for the secret you want to remove.
3. Confirm the deletion in the dialog that appears.

<Warning>
  Deleting a secret will immediately invalidate all embed URLs signed with that secret. Any existing embed sessions or URLs using the deleted secret will no longer work and will receive `403 (Forbidden)` errors.

  Before deleting a secret, ensure you've updated all your applications to use a different secret to avoid disrupting access to embedded content.
</Warning>

## Next steps

* [Set up embed with standard SSO](/embed/setup/standard-sso)
* [Set up embed with 2-step SSO](/embed/setup/two-step-sso)
* [View embed URL parameters](/embed/setup/url-parameters)


# Configuring security and access settings for embedded content
Source: https://docs.omni.co/embed/admin/security

Control security and access restrictions for embedded content.

<Note>
  **Organization Admin** permissions are required to manage embed security settings.
</Note>

Embed security settings control where your embedded content can be displayed, how long embed sessions last, and what embed users can do within embedded content. These settings, accessed in **Settings > Embed > Admin**, apply to all embedded content in your organization.

## Session length

The **Session length** setting defines how long an embed session lasts. By default, using a valid embed URL creates an embed session that lasts 24 hours. See [Embed sessions](/embed/admin/sessions) for more information.

## Disable right-click in embedded presentations

When enabled, right-click context menus are disabled in embedded presentations to prevent users from accessing browser developer tools or copying content.

## Show AI credit usage on profile

When enabled, embed users can see their monthly AI credit usage (and [their credit limit](/ai/settings/usage#user-level-credit-controls), if one is set) on their [profile page](/administration/users/your-account). See [Managing AI credit usage](/ai/settings/usage#user-level-credit-controls) for more information about user-level credit limits.

## Allowed Frame Ancestors

Defines the domains where Omni embedded content renders, ensuring embedded content is only visible on domains within your control.

Separate domains by spaces or new lines. Each domain must be valid according to the frame ancestor specification. See the [MDN Frame Ancestors documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) for more information.

<CodeGroup>
  ```text One domain per line theme={null}
  omni.blobsrus.com
  *.blobsrus.com
  ```

  ```text Space-separated theme={null}
  omni.blobsrus.com *.blobsrus.com
  ```
</CodeGroup>


# Managing user sessions
Source: https://docs.omni.co/embed/admin/sessions

View and delete Omni embed user sessions.

An embed session is created each time a user visits a valid [embed SSO URL](/embed/setup). Sessions last for the [length configured](/embed/limitations#session-length) in your Omni instance's **Embed** settings, after which the URL that created them will no longer display content. The **Settings > Embed > Sessions** tab lets Organization Admins manage embed sessions for their organization.

## Requirements

To manage embed sessions, you'll need:

* **Organization Admin** permissions
* The **Embed** feature enabled in your Omni instance

## Accessing sessions

To access embed sessions, navigate to **Settings > Embed** and click the **Sessions** tab. On this page, you can view session details that include:

* **External ID** - The unique identifier for the embed user
* **Host** - The hostname extracted from the session URL, useful for distinguishing between sessions from different domains
* **Name** - The display name of the embed user
* **Created At** - When the session was created
* **Expires At** - When the session will expire

## Filtering sessions

Use the search bar above the table to filter sessions based on user name.

## Deleting sessions

<Note>
  When a session is expired or deleted, the embed URL used to create the session will no longer display content.
</Note>

To manually delete a session:

1. Click the <Icon icon="ellipsis-vertical" /> icon to the right of the session to open the options menu.
2. Click **Delete session**.


# Managing embed users
Source: https://docs.omni.co/embed/admin/users

View, manage, and impersonate users in your embedded Omni application.

<Note>
  **Organization Admin** permissions are required to manage embed users.
</Note>

Embed users are users created within and granted access to an embedded instance of Omni. Unlike standard Omni users who sign in directly, embed users are provisioned programmatically and interact with Omni through your embedded application. The **Settings > Users > Embed** tab lets Organization Admins view, manage, and impersonate these users.

## Viewing embed users

The **Embed** users tab displays the following about each embed user:

* **External ID** - The unique identifier for the user in your system
* **Host** - The domain extracted from the user's email address
* **Embed Entity** (if present) - The [entity](/embed/admin/entities) associated with the embed user
* **Last Login** - The time the user last logged in to Omni. This will always be **Never** for embed users, as they don't log into an Omni instance.

## Managing embed users

Hover over the user you want to manage and click the **Manage** button that appears. This will open the user's profile, where you can manage their [AI credit limit](/ai/settings/usage#individual-user-limit), [user attributes](/administration/users/attributes), [group memberships](/administration/users/groups), and [model access](/administration/users/permissions).

## Impersonating embed users

Just like standard Omni users, Organization Admins can [impersonate embed users](/administration/users/impersonate). This feature is useful for testing or troubleshooting user permissions, such as Access Grants or content visibility.


# Embedding Omni best practices
Source: https://docs.omni.co/embed/best-practices

Learn how to develop a secure, enjoyable embedded Omni experience for your users.

## User creation

### Use unique emails per embed user

Email addresses in embed are used to resolve delivery recipients and apply [user attributes](/administration/users/attributes). Each embed user must have a unique email to ensure deliveries reach the intended recipient with the expected attributes applied.

* **Never mix internal and embed user emails.** If you must use the same base email, use the `+` modifier - for example, `blob@example.com` for the internal user and `blob+omniembed@example.com` for the embed user.
* **Never reuse the same email across different** `externalId `**values.** Each embed user should have a unique email to ensure deliveries reach the intended recipient.
* **Include the [`email`](/embed/setup/url-parameters/email) parameter when generating the embed session.** Without it, email deliveries cannot be mapped back to the embed user and Omni will create a separate email-only user instead.

### Create unique embed users when embed users access data in multiple entities

If a physical user in your application has access to data across multiple entities, provision a separate embed user for each entity rather than reusing a single embed user across all of them.

An embed user's attributes reflect their most recent embed session. Each new session overwrites the previous attributes. If the same embed user is used across entities, whichever entity was accessed most recently determines what attributes that user holds.

For example, a physical user who accesses both `acme` and `globex` should have two embed users:

| Physical user                               | Entity | `externalId`  | Email                     |
| ------------------------------------------- | ------ | ------------- | ------------------------- |
| [user@yourapp.com](mailto:user@yourapp.com) | acme   | `user_acme`   | `user+acme@yourapp.com`   |
| [user@yourapp.com](mailto:user@yourapp.com) | globex | `user_globex` | `user+globex@yourapp.com` |

Each embed user gets the user attributes appropriate for its entity. When the user switches between entities in your application, your server generates a new embed URL using the corresponding embed user's `externalId` and attributes.

See [user attributes](/administration/users/attributes) and [access filters](/modeling/develop/data-access-control) for details on configuring per-entity row-level security.

## Data access management

### Define base connection roles

When generating embed requests, set the [`connectionRoles`](/embed/setup/url-parameters/connectionRoles) parameter to either **No Access** or **Viewer**. This sets the default level of access for the connection and ensures that access to data must be granted on an individual user basis.

### Send connection roles on every embed request

When a user creates an embed session, the [`connectionRoles`](/embed/setup/url-parameters/connectionRoles) on the latest request acts as the source of truth for that user's connection access. This means:

* A role can be **downgraded** by a later request (e.g. from **Restricted Querier** to **Viewer**).
* A role can be **removed** entirely if the later request doesn't mention the connection — either explicitly in `connectionRoles` or implicitly in the connection backing the requested [`contentPath`](/embed/setup/url-parameters/contentPath).

<Warning>
  If you embed multiple pieces of content on the same page (for example, a dashboard and a workbook in separate iframes), include an explicit `connectionRoles` object on every request. Each iframe generates its own embed login request, and a request that omits `connectionRoles` will overwrite the access granted by the others.
</Warning>

For example, imagine a page that embeds:

* A workbook backed by connection A, which requires at least **Restricted Querier** access
* A dashboard backed by connection B, which only requires **Viewer** access

If the dashboard's embed request only specifies `connectionRoles` for connection B, the user's role on connection A will be deleted as soon as that request resolves — and the workbook will lose access. To avoid this, send `connectionRoles` for both connection A and connection B on **both** the workbook and dashboard embed requests.

### Leverage user attributes to control data access

To ensure appropriate data access for users, best practice is to leverage [user attributes](/administration/users/attributes) to systematically filter data.

* **Access filters**, or row-level security, allow you to restrict the rows of data a user can access within a topic. Access filters apply the values assigned on a user attribute to the `WHERE` clause of every SQL query a user runs, filtering out to only the data designated to that user.
* **Access grants** define topic- and field-level permissions for users.

### Implement security for multi-tenant instances

<Warning>
  Segmenting data using hidden dashboard filters is not a secure practice.
</Warning>

Typically, companies choose one of the following strategies to set up multi-tenant customer data:

* **Row-level security** - If all of the data is inside one table, you can assign a user attribute per user and client and use it as an [access filter](/modeling/develop/data-access-control). Specifically make sure to set up a default access filter to control in Omni with [`default_topic_access_filters`](/modeling/models/default-topic-access-filters). Note that [input columns](/analyze-explore/input-columns) automatically enforce access filter fields in their mapping keys to prevent cross-tenant data leakage.
* **Schema level security** - If each client is in a separate, identical schema, then you can leverage [dynamic schemas](/modeling/models/dynamic-schemas).
* **Database level security** - If each client is in a separate database and the schemas are identical across databases, you can leverage [dynamic database environments](/connect-data/dynamic-environments).
* **Model-level isolation** - If each client needs a tailored view of the same base model, you can use [shared extension models](/modeling/develop/shared-extensions) to create tenant-specific extensions that inherit core logic while allowing per-client customizations.

## Modeling and content

### Build content on shared topics

Embedded dashboards won't render correctly if the content you want to embed meets **any** of the following criteria:

* Content contains fields not included in a topic in the shared model
* Content built on SQL
* Content that contains unpromoted changes to joins in the workbook's model

<Warning>
  To expose non-topic bound or SQL-based content, enable [**AccessBoost**](/share#boosting-permissions-with-accessboost) in the content's **Share** settings. **This has security implications**, as you may expose data that you don't want your embed users to access.
</Warning>

### Save content to the Shared hub

Along with the above criteria for building content on topics, embedded dashboards must be saved in your instance's **Shared** hub. Dashboards will not render correctly if they are saved in personal folders.

## Error handling

### Handle errors in your host application

Embedded content displays generic error messages to end users. Database-specific details, such as connection strings or warehouse error messages, are not exposed in the embedded UI.

To capture the underlying error information for debugging, listen for the [`error` embed event](/embed/events/error). The event payload includes the full error message, which you can log or use to build a custom error experience for your users.


# Embedding the Omni Agent
Source: https://docs.omni.co/embed/customization/ai-chat

Integrate a whitelabeled version of the Omni Agent directly into your embedded application.

The [Omni Agent](/ai/chat) can be embedded as a standalone page in your application, allowing your users to explore data outside of workbooks using the same AI-powered experience found in the native Omni app.

<img alt="" />

<Note>
  The [**Chat in navigation** setting](/ai/settings/features#chat-in-navigation) allows you to control whether the Omni Agent appears in the main [sidebar](/administration/settings/sidebar). For embedded scenarios, you can enable the **Chat** setting to allow workbook and dashboard AI functionality while disabling **Chat in navigation** to remove the standalone Omni Agent from the main sidebar.
</Note>

## How it works

The embedded Omni Agent uses the same [pickers and scoping behavior](/ai/chat#scoping-responses) as the native Omni app. When embedding, you can tailor the experience to include only the connections, models, and topics you specify.

<Note>
  When embedding content with [`mode=SINGLE_CONTENT`](/embed/setup/url-parameters/mode), [the chat](/ai/dashboard-assistant) uses an inline panel instead of the split-view interface. This prevents users from navigating away from the embedded content, keeping them scoped to the single-content frame.
</Note>

<Steps>
  <Step title="Define connection access">
    The first step is to decide which connections you want your users to have access to when using the Omni Agent. These connections will display in the **Connections** picker below the chatbox.

    Start by retrieving the connections' unique IDs. Later in this guide, you'll use the IDs to construct a `connectionRoles` parameter and configure the embed session. You can retrieve connection IDs using either of the following methods:

    <Tabs>
      <Tab title="Omni UI">
        1. In Omni, navigate to **Settings > Connections**.
        2. Click on the connection.
        3. At the top of the **Settings** tab, locate the **Connection ID** field:

           <img alt="Highlighted Connection ID field in a MotherDuck connection's details page" />
      </Tab>

      <Tab title="API">
        To programmatically retrieve connection IDs, use the [List connections API](/api/connections/list-connections).

        If you want to retrieve a specific connection - such as a connection specific to a client - use the endpoint's filtering functionality. In this example, the request will retrieve a connection named `Blobs R Us`:

        ```shell wrap title="GET /api/v1/connections" theme={null}
        curl -X GET 'https://blobsrus.omniapp.co/api/v1/connections?name=Blobs+R+Us' \
        --H 'Authorization: Bearer <TOKEN>' \
        --H 'Content-Type: application/json'
        ```

        Valid requests to the API will return a `200 OK` status and a response body containing `connection` objects. Each object will contain the connection's unique `id`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Curate the topic list">
    Next, you'll curate the list of topics you want users to have access to in the topic picker. This is accomplished with the [`ai_chat_topics`](/modeling/models/ai-chat-topics) model parameter. This parameter accepts a list of topic names, which will limit access only to the specified topics.

    In Omni, navigate to the models associated with the connections from step 1. Add the `ai_chat_topics` parameter and specify the topics that users should have access to:

    ```yaml title="Example model file" theme={null}
    ai_chat_topics: [ Product Performance, Order Transactions]
    ```

    Refer to [Scoping AI chat responses](/ai/chat#scoping-responses) for details on how topic configuration affects the picker display and AI behavior.

    <Tip>
      You can add [sample queries](/modeling/develop/ai-optimization#add-example-queries-as-context) to accessible topics, which will display in the chat interface as clickable questions:

      <img alt="" />

      Refer to the [Optimizing models for AI guide](/modeling/develop/ai-optimization) for more information about curating topics for AI.
    </Tip>
  </Step>

  <Step title="Define embed parameters">
    The next step is to define the embed parameters to create the chat session for the user. Along with the [required parameters](/embed/setup/url-parameters#required-parameters) - `externalId`, `name`, and `nonce` - set the following parameters:

    * [`contentPath`](/embed/setup/url-parameters/contentPath) - Set to `/chat`
    * [`connectionRoles`](/embed/setup/url-parameters/connectionRoles) - Use the connection IDs from step 1 of this guide to build an object that specifies the connection roles available to the embed users. For example:

      ```json wrap theme={null}
      {  
        "c0f12353-4817-4398-bcc0-d501e6dd2f64":"RESTRICTED_QUERIER"
      }
      ```

    If you're using [standard SSO embed](/embed/setup/standard-sso) to create embed sessions, the embed URL you build might look like the following:

    ```shell wrap theme={null}
    https://omni.blobsrus.com/embed/login?&connectionRoles=%7B%22c0f12353-4817-4398-bcc0-d501e6dd2f64%22%3A%22RESTRICTED_QUERIER%22%7DcontentPath=%2Fchat&externalId=Blobs+R+Us&mode=SINGLE_CONTENT&name=Blobby&nonce=yRt9RbPRST1pKP0fv4hkZkOcyydnwmWX&signature=prfIqNKkUBYlXiAdXLe_E__w19QbM_-6o3CIi4kkV1s
    ```

    <Tip>
      To enable voice mode, add the `microphone` permission to your iframe's `allow` attribute. Browsers will block microphone access by default without this permission.

      ```html theme={null}
      <iframe src="https://omni.blobsrus.com/embed/login?..." allow="microphone"></iframe>
      ```
    </Tip>
  </Step>

  <Step title="Apply your branding">
    After you've successfully configured and created an embed session, the last step is to apply your branding styles. While this last step is **optional**, it allows you to make the Omni Agent your own and blend it seamlessly with your application.

    Navigate to **AI Hub > General** and then click the [**Branding** tab](/ai/settings/branding).

    <img alt="" />

    Use the settings to configure how you want the Omni Agent to look and then click **Save**.
  </Step>
</Steps>

## Next steps

* [Implement AI credit controls](/ai/settings/usage) to manage your users' credit consumption
* Define AI credit limits for [embed entity groups](/embed/admin/ai-credits) to manage credit usage for individual entities


# Create Mode for embedded analytics
Source: https://docs.omni.co/embed/customization/create-mode

Enable the full Omni experience - creating, sharing, and navigating content - for your embedded users.

Customers don’t just want to see data. They want to interact with it, explore it, and get their own insights, without waiting for a data team to make adjustments. With Create Mode for Omni embedding, you can allow your users to create, share, and navigate content as if they were in the native Omni app.

## Entities

Create mode uses an `entity` parameter to isolate embed customers from each other. This ensures that users can only see and share content with other users in their `entity`. Refer to the [Enabling create mode section](#enabling-create-mode) for an example.

When Omni detects a new entity value, a dedicated, shared folder and user group is automatically created for the entity. Only the entity that the folder was created for and admins on your Omni organization can access it. Refer to the [User roles & content permissions](#user-roles-and-content-permissions) for more information on controlling user access to content.

## Enabling Create Mode

To enable Create Mode for an embedded Omni instance, set the `mode` embed URL parameter to `APPLICATION` (`mode=APPLICATION`). For example:

```markdown wrap theme={null}
https://blobsrus.embed-omniapp.co/embed/login?contentPath=%2Fdashboards%2F12db1a0a&externalId=1234abcd&name=Blobby&nonce=OYZFNSulBHxivB9xBw7kAsv4aDu7zl4G&signature=kYnijvMXMBmVQ3wJ6mfmR132qOZZpnZlRi2uSvEjZYA&userAttributes=%7B%7D&entity=blobs_r_us&connectionRoles=%7B%22c0f12353-4817-4398-bcc0-d501e6dd2f64%22%3A%22RESTRICTED_QUERIER%22%7D&mode=APPLICATION&entityFolderContentRole=VIEWER&groups=%5B%5D
```

Refer to the [Embed parameters reference](/embed/setup/url-parameters) for more information about URL parameters. Refer to [step 1 of the Standard SSO setup guide](/embed/setup/standard-sso) for information about manually generating a signature.

## User roles and content permissions

Two parameters control how embed users can interact with content when in Create mode:

* **Connection role** (`connectionRoles`), which determines if a user can create content or only consume it
* **Entity folder content role** (`entityFolderContentRole`), which determines if a user can add or manage content for their entity

Refer to the following table for information about how these roles map and the permission sets they produce.

| Connection role    | Entity folder content role | Permissions                                                                                                                                  |
| ------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Viewer             | Viewer                     | <ul><li>View content</li></ul>                                                                                                               |
| Restricted querier | Viewer                     | <ul><li>Create content only in a user's private folder</li><li>Share content with other users in the entity</li></ul>                        |
| Restricted querier | Editor or Manager          | <ul><li>Create content in the **Shared** folder or a user's private folder</li><li>Share content to the entity's **Shared** folder</li></ul> |

## Entity folder and group labels

By default, the labels of an entity's generated folder and user group will be human-readable versions of the associated entity value. As an example, entity `"tottenham_hotspur"` would generate a folder and group labeled `Tottenham Hotspur` in the Omni UI.

If you'd like to customize the names of the generated entity group and folder, you can use the [`entityFolderLabel`](/embed/setup/url-parameters/entityFolderLabel) and [`entityGroupLabel`](/embed/setup/url-parameters/entityGroupLabel) parameters.

These parameters are useful if you want multiple entity groups and folders to have the same label for an entity A and B. For example, if you have two entities - `acme_marketing` and `acme_finance` - but want the generated groups and folders to both appear as `Acme` in the Omni UI, you can do so using the `entityFolderLabel` and `entityGroupLabel` parameters.

## Next steps

* Create a [custom sidebar and theme](/embed/customization/themes) for your embedded application


# Configuring email deliveries in embedded Omni
Source: https://docs.omni.co/embed/customization/deliveries

Allow users in your embedded Omni instance to schedule or set alerts on documents.

## Disabling deliveries

If needed, Organization Admins can disable this feature at an [instance-wide](/administration/content-permissions) or a [document](/share#controlling-document-interactivity) level.

## Customizing sender information

The **Customer email sender** feature allows you to customize the sender information for Omni delivery emails, including the sender's name, email domain, and reply-to address. Refer to [Whitelabeling sender addresses for email deliveries](/share/deliveries/email/whitelabel) for more information.

## Populating email suggestions

In order for email suggestions to be populated automatically for deliveries, the [`email` parameter](/embed/setup/url-parameters/email) needs to be included in the embed URL.


# Enabling iframe-restricted functionality for embedded instances
Source: https://docs.omni.co/embed/customization/iframes

Enable functionality for embedded content that iframes restrict by default.

By default, iframes restrict access to certain functionality that could pose a security risk, such as copying or using the microphone. However, you can allow your users to use these features by including them in your iframe declarations.

## Supported features

The following Omni features can currently be enabled through the `allow` parameter in iframe declarations:

| Parameter                             | Description                                                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [`clipboard-write`](#allow-clipboard) | Enables clipboard access, allowing users to copy data values from embedded Omni                                    |
| [`microphone`](#allow-microphone)     | Enables microphone access, allowing users to use the Omni Agent's voice mode feature                               |
| [`fullscreen`](#allow-fullscreen)     | Enables fullscreen viewing for dashboards and workbooks through the user's native browser fullscreen functionality |

## Allow copying in embed iframes

Access to the viewing device's clipboard is restricted by default. This means that when you click on a data value within Omni and select **Copy value**, the value will not be copied to your clipboard.

To allow clipboard access, add `allow="clipboard-write"` to your iframe declaration:

```html wrap theme={null}
<iframe src={omni-embed-url} allow="clipboard-write" />
```

<Note>
  When an embedded Omni instance contains an app that has its **Allow clipboard copy** setting enabled, the embedding iframe must include `allow="clipboard-write"` for clipboard operations inside that app to work. The `clipboard-write` permission delegates inward — if the outer iframe omits it, the grant isn't applied to the app's inner iframe, even when the app's setting is on.
</Note>

### Restrict copying by domain

To only allow copying from a specific domain, modify the `allow` clause to include the specific domain:

```html wrap theme={null}
<iframe src={omni-embed-url} allow="clipboard-write self https://acme.embed-omniapp.co/" />
```

## Allow Omni Agent voice mode in embed iframes

When using the Omni Agent's voice mode feature, microphone access will be blocked unless explicitly allowed. Adding `allow="microphone"` to your iframe declaration will enable voice mode:

```html wrap theme={null}
<iframe src={omni-embed-url} allow="microphone" />
```

## Allow full screen mode in embed iframes

Embedded dashboards, workbooks, and apps can request native browser fullscreen when a viewer uses the full screen toggle, hiding browser and OS chrome for a distraction-free presentation. To enable this functionality for embedded content, add `allow="fullscreen"`:

```html wrap theme={null}
<iframe src={omni-embed-url} allow="fullscreen" />
```

Without this attribute (or on iOS Safari, which does not support fullscreen viewing for embedded content), Omni falls back to a CSS-only overlay presentation. The overlay still provides a focused view within the available viewport, but browser and OS chrome remain visible.

<Tip>
  To build a custom fullscreen control in your parent application or stay in sync with fullscreen state changes, use the [`fullscreen:changed`](/embed/events/fullscreen-changed) event to listen for fullscreen transitions and the [`fullscreen:set`](/embed/events/fullscreen-set) event to programmatically control fullscreen mode. See the [`fullscreen:set` example](/embed/events/fullscreen-set#example) for a complete parent-controlled fullscreen implementation.
</Tip>

## Combining embed iframe permissions

A single `allow` attribute can include multiple permissions. For example, to enable both voice mode and value copying:

```html wrap theme={null}
<iframe src={omni-embed-url} allow="clipboard-write microphone" />
```


# Linking to other content in embedded Omni
Source: https://docs.omni.co/embed/customization/link-content

Add interactivity to your embedded Omni application by linking to other content.

The Markdown component can be used to build links to other Omni content, like other dashboards. These links work seamlessly within the app and don't require any complex iframe manipulation.

## Requirements

Setting the [`linkAccess`](/embed/setup/url-parameters/linkAccess) parameter to `__omni_link_access_open` is required to enable linking in an embed session.

## Creating basic HTML links

In the `href` value of an `<a>` HTML tag, set the relative path to the content you want to link to:

```markdown wrap title="Link to dashboards" theme={null}
## Dashboards

1. <a href="/dashboards/123abc">Product Dashboard</a>
2. <a href="/dashboards/789xyz">Sales Dashboard</a>
```

## Linking filters between dashboards

You can also link filters between dashboards using [Mustache references](/visualize-present/mustache-reference) to the filter values. This allows linking of dashboard and dashboard state across multiple dashboards.

For example, the following is a reference to a filter on `traffic_source`:

```html wrap title="Reference traffic_source filter" theme={null}
<a href="/dashboards/123abc?f--users.traffic_source={{filters.users.traffic_source.json}}">Product Dashboard</a>
```

## Opt out of link rewriting

Omni automatically rewrites dashboard links in an embed context to support intra-iframe linking, routing them through the `/embed/link` route to handle content permissions. To opt a link out of this auto-rewrite behavior, add the `NO-EMBED-LINK-REWRITE` query parameter to the URL.

This parameter works with both HTML anchor tags and standard markdown link syntax:

```html wrap title="HTML anchor tag without rewriting" theme={null}
<a href="https://customer.omniapp.co/dashboards/456def?NO-EMBED-LINK-REWRITE">Customer Dashboard</a>
```

```markdown wrap title="Markdown link without rewriting" theme={null}
[Customer Dashboard](https://customer.omniapp.co/dashboards/456def?NO-EMBED-LINK-REWRITE)
```

When this parameter is present:

* The link is not rewritten to use the `/embed/link` route
* The link opens in a new tab (`_blank`)
* The link is treated as a standard external link


# Applying custom themes and sidebars to embedded Omni
Source: https://docs.omni.co/embed/customization/themes

Create a seamless, cohesive analytics experience for your users with a custom theme and navigation sidebar.

You can customize your embedded Omni instance to match the look, feel, and navigation of your own application. Apply a custom theme to control colors, typography, and overall styling, and build a custom sidebar to control which pages and links your users see, so the experience matches your brand, not Omni's defaults.

Whether you’re going for subtle alignment or a fully bespoke look, combining a custom theme and sidebar helps create a seamless, cohesive experience for your users.

## Customizing the sidebar

Instead of Omni's [default list of pages](/content/navigate), you can add custom groups and items for specific content or external links, like a support site or internal wiki, then reorder and rename them. Omni's built-in groups always stay in the sidebar, but you can rename their items, change their icons, or reset them to defaults.

See [Customizing your organization's navigation sidebar](/administration/settings/sidebar) for more information.

## Customizing application themes

The **Styles** section, located in the [**Settings > Themes > Application tab**](/administration/themes/application), allows you to customize a limited number of application-level theme properties.

You can add custom logo and wordmark assets to your application theme to replace the default Omni branding. These custom assets are displayed in application mode embeds, where the default Omni branding is normally hidden behind a menu toggle.

See [Branding assets](/administration/themes/application#branding-assets) for more information.

## Customizing document themes

There are two ways to create and use custom document themes: [directly on a dashboard](/visualize-present/dashboards/theming) or through the URL.

<Check>
  To make your theme dynamic using some external logic, you can adjust the URL theme properties using the [`customTheme` parameter](/embed/setup/url-parameters/customTheme).
</Check>

### Page properties

| Property Name          | Description                                 | Accepts                                                                   |
| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| dashboard-background   | The background of the embedded dashboard.   | [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background) |
| dashboard-page-padding | The padding of the embedded dashboard page. | [padding](https://developer.mozilla.org/en-US/docs/Web/CSS/padding)       |

### Tile properties

| Property Name                        | Description                                                                                                                                          | Accepts                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| dashboard-tile-margin                | The spacing around tile elements on the embedded dashboard.                                                                                          | [padding](https://developer.mozilla.org/en-US/docs/Web/CSS/padding)             |
| dashboard-tile-background            | The background of the embedded dashboard's tiles.                                                                                                    | [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)       |
| dashboard-tile-shadow                | The box shadow of the embedded dashboard's tiles.                                                                                                    | [box-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow)       |
| dashboard-tile-text-body-color       | The text color of primary text in the embedded dashboard's tiles. Primary text refers to the tile title of most tiles or the single value tiles.     | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-tile-text-secondary-color  | The text color of secondary text in the embedded dashboard's tiles.                                                                                  | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-tile-border-color          | The border color of the embedded dashboard's tiles.                                                                                                  | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-tile-border-radius         | The border radius of the embedded dashboard's tiles.                                                                                                 | [border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) |
| dashboard-tile-border-style          | The border style of the embedded dashboard's tiles.                                                                                                  | [border-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style)   |
| dashboard-tile-border-width          | The border width of the embedded dashboard's tiles.                                                                                                  | [border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width)   |
| dashboard-tile-title-font-size       | The font size of the embedded dashboard tiles' titles.                                                                                               | [font-size](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size)         |
| dashboard-tile-title-font-weight     | The font weight of embedded dashboard tiles' titles.                                                                                                 | [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight)     |
| dashboard-tile-title-text-color      | The text color of title text in the embedded dashboard's tiles.                                                                                      | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-tile-title-font-family     | The font family of title text in the embedded dashboard's tiles. Pass a link to a remote woff2 file to use a custom font.                            | [woff2 url](#retrieving-woff2-file-links-from-google-fonts)                     |
| dashboard-tile-text-body-font-family | The font family of the body text in the embedded dashboard's tiles. Pass a link to a remote woff2 file to use a custom font.                         | [woff2 url](#retrieving-woff2-file-links-from-google-fonts)                     |
| dashboard-tile-text-code-font-family | The font family of a markdown `<code>` element in the embedded dashboard's markdown tiles. Pass a link to a remote woff2 file for custom font usage. | [woff2 url](#retrieving-woff2-file-links-from-google-fonts)                     |

#### Controls

Page-level controls like filters, field switchers, and period-over-period.

| Property Name                       | Description                                                               | Accepts                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| dashboard-control-background        | The background of filter controls in the embedded dashboard.              | [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)       |
| dashboard-control-radius            | The border radius of controls.                                            | [border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) |
| dashboard-control-border-color      | The border color of filter controls in the embedded dashboard.            | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-text-color        | The text color of filter controls in the embedded dashboard.              | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-placeholder-color | The text color of placeholder text inside controls.                       | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-label-color       | The text color of labels above filter controls in the embedded dashboard. | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-outline-color     | The outline color for controls when they have focus.                      | [outline-color](https://developer.mozilla.org/en-US/docs/Web/CSS/outline-color) |

### Control popover properties

Styles applied to control popovers and the inputs inside of them.

| Property Name                                  | Description                                                                   | Accepts                                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| dashboard-control-popover-background           | The background of filter control popovers in the embedded dashboard.          | [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)       |
| dashboard-control-popover-text-color           | The base text color in control popovers.                                      | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-popover-secondary-text-color | The secondary text color in control popovers.                                 | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-popover-link-color           | The color of links in control popovers.                                       | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-popover-divider-color        | The color of dividers in control popovers.                                    | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-control-popover-radius               | The border radius of control popovers.                                        | [border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) |
| dashboard-control-popover-border-color         | The border color of control popovers.                                         | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-background              | The background of filter inputs inside of the popover.                        | [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)       |
| dashboard-filter-input-radius                  | The border radius of filter inputs inside the popover.                        | [border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) |
| dashboard-filter-input-border-color            | The border color of filter inputs inside the popover.                         | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-text-color              | The text color of filter inputs inside the popover in the embedded dashboard. | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-placeholder-color       | The color of placeholder text inside filter inputs.                           | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-icon-color              | The color of icons inside filter inputs.                                      | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-outline-color           | The outline color of inputs when they have focus.                             | [outline-color](https://developer.mozilla.org/en-US/docs/Web/CSS/outline-color) |
| dashboard-filter-input-accent-color            | The color of checkbox, radio, and toggle inputs.                              | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-accent-invert-color     | The invert color of elements in checkbox and radio inputs.                    | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-token-color             | The background color of tokens in multi-select inputs.                        | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-filter-input-token-text-color        | The text color of tokens in multi-select inputs.                              | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |

### Button properties

| Property Name                                  | Description                                                                                                         | Accepts                                                                         |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| dashboard-key-color                            | The key color of the embedded dashboard, used on filter **Update** buttons and other key elements.                  | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-key-text-color                       | The key text color of the embedded dashboard, used on the text of filter **Update** buttons and other key elements. | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-button-radius                        | The border radius of buttons in popover controls.                                                                   | [border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) |
| dashboard-button-transparent-text-color        | The text color of transparent buttons in filter control popovers.                                                   | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-button-transparent-interactive-color | The background color of transparent buttons in filter control popovers when the user hovers over the button.        | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |
| dashboard-menu-item-interactive-color          | The background color of menu items in filter control popovers when the user hovers over it.                         | [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)                 |

### Retrieving woff2 file links from Google Fonts

<Note>
  If you have a woff2 file link like this:

  `https://fonts.gstatic.com/s/libertinuskeyboard/v2/NaPEcYrQAP5Z2JsyIac0i2DYHaapaf43dru5tEg8zfg.woff2`

  You must wrap it with the css url function when used in Omni, like so:

  `url(https://fonts.gstatic.com/s/libertinuskeyboard/v2/NaPEcYrQAP5Z2JsyIac0i2DYHaapaf43dru5tEg8zfg.woff2)`
</Note>

Font family properties like `dashboard-tile-title-font-family` support links to a remote woff2 file. A typical use case is to link to a woff2 file from a Google Font. To grab the link to a Google Font woff2 file, perform the following steps:

1. Navigate to fonts.google.com and click on your font of choice. For this example, we’ll be using the “Yarndings 12” font.

<img alt="" />

2. That click should take you to a font specimen page. On that font specimen page, click the “Get font” button.

<img alt="" />

3. After pressing “Get font” you’ll be taken to a selection page. On that selection page, click the “Get embed code” button.

<img alt="" />

4. Go to the fonts.googleapis.com link that appears in the third \<link> element of the example embed code. Note that some Google Fonts allow you to customize font weight and font style in the left panel so feel free to filter down to the exact font styling you’d like.

<img alt="" />

5. Find the @font-face at-rule labeled “latin” and copy the src property url(...).

<img alt="" />

6. Pass that **`url(...)`** value into the appropriate customTheme property when generating your Omni SSO embed link.

```
customTheme={"dashboard-tile-title-font-family": "url(https://fonts.gstatic.com/s/yarndings12/v2/55xreyp2N8T5P2LJbZAlkY9s9pjNAWZEnA.woff2)"}
```

7. And voilà!

<img alt="" />


# Setting up custom domains for embed
Source: https://docs.omni.co/embed/customization/vanity-domains

Set up custom vanity domains for embedded Omni dashboards to enable first-party cookies and cohesive branding across content.

If you need to utilize first-party cookies or want to have cohesive branding across your content, custom vanity domains can be used for your embedded dashboards.

For example:

```typescript title="Vanity domain of analytics.blobsrus.com" theme={null}
const iframeUrl = await embedSsoDashboardCompressed({
  contentId: "miU0hL6z",
  externalId: "blobby@blobsrus.com",
  name: "Blobby",
  host: "analytics.blobsrus.com",
  secret: "abcdefghijklmnopqrstuvwxyz123456"
})
```

## Requirements

Custom domains are only available for embed use cases.

### Domain selection

The domain you select has a set of requirements:

* Only one vanity domain (or wildcard domain) is allowed per Omni instance.
* A vanity domain must have three or more parts. For example, `myapp.com` without `products` prepended will not be considered a valid vanity domain. Valid examples include `products.myapp.com` or `dev.products.myapp.com`.
* **You must use a new, dedicated subdomain:**
  * Omni needs to configure specific DNS records and SSL certificates for the domain.
  * The domain must be set up to proxy requests to Omni's infrastructure.
  * Existing endpoints serve different content and can't be repurposed for Omni embeds.
* **To support first-party cookies**, the top-level domain of the vanity must match the embedding page. For example, for an embedding page like `myapp.com`, the embedded vanity domain should be `omni.myapp.com`.

  However, if you provide an embedded vanity domain of `myapp.omni.com` in addition to an embedding page of `myapp.com`, you may still encounter third-party cookie limitations on some browsers like Safari or other iOS applications.

## Wildcard vanity domains

<Note>
  This feature is currently in beta. To have it enabled, contact Omni support. If you attempt to add a wildcard vanity domain and the feature isn't enabled, you'll receive a `Wildcard domains are not supported. Contact support to enable this feature.` error.
</Note>

Omni supports wildcard vanity domains (e.g., `*.omni.myapp.com`) for multi-tenant embedding scenarios. When using a wildcard domain:

* You must specify a specific host when generating embed URLs (e.g., `tenant1.omni.myapp.com`, `tenant2.omni.myapp.com`)
* The host must match the wildcard pattern configured for your organization
* When using the [URL builder](/embed/setup/test-urls), you'll need to provide a **Host** value that matches your wildcard domain pattern

```typescript title="Wildcard vanity domain of *.analytics.blobsrus.com" theme={null}
const iframeUrl = await embedSsoDashboardCompressed({
  contentId: "miU0hL6z",
  externalId: "blobby@blobsrus.com",
  name: "Blobby",
  host: "tenant1.analytics.blobsrus.com",
  secret: "abcdefghijklmnopqrstuvwxyz123456"
})
```

## Setup

<Note>
  **Organization Admin** permissions are required to configure custom (vanity) domains in Omni.
</Note>

<Steps>
  <Step title="Configure the domain in Omni">
    1. In Omni, navigate to **Settings > Embed**.
    2. In the **Vanity domain** field:
       * [**For wildcard domains**](#wildcard-vanity-domains), enter your wildcard domain with the `*.` prefix (e.g., `*.omni.myapp.com`)
       * **Otherwise**, enter your domain (e.g., `omni.myapp.com`)
    3. Click **Save** to apply the configuration.
  </Step>

  <Step title="Update your DNS configuration">
    1. Reach out to Omni support with the vanity domain you configured in step 1.
    2. Omni will provide DNS configuration details and ask that you update your DNS configuration.
    3. Notify Omni that your DNS update is complete.

    After Omni completes our internal setup and notifies you, your custom domain should be usable.
  </Step>
</Steps>

## Session validation

When users log into an embedded Omni instance through a vanity domain, Omni sets a JavaScript-accessible cookie named `__omni_embed_vanity_session`. This cookie allows you to check whether a valid session exists before initiating the login flow, enabling you to skip the server handshake when a session is already present.

### Cookie details

* **Cookie name**: `__omni_embed_vanity_session`
* **Accessibility**: JavaScript accessible
* **Max-Age**: Matches the actual Omni session cookie duration. Update through a session refresh call to maintain accuracy.
* **Domain scope**: Only available when your embedding page and vanity domain share the same parent domain. For example, if your embedding page is `app.myapp.com` and your vanity domain is `embed.myapp.com`, both share the parent domain `myapp.com`, so your page can read the cookie.

  However, if your embedding page is `app.example.com` and the vanity domain is `embed.myapp.com`, the cookie will not be accessible because the domains don't share a common parent. This cookie is not set on standard embed domains like `embed-omniapp.co`.

### Usage

You can check for the presence of this cookie before attempting to log in a user:

```javascript title="Check for existing session" theme={null}
function hasActiveSession() {
  return document.cookie.split('; ').some(cookie =>
    cookie.startsWith('__omni_embed_vanity_session=')
  );
}

// Skip login flow if session exists
if (hasActiveSession()) {
  // Load embedded content directly
  loadEmbeddedDashboard();
} else {
  // Initiate login flow
  performSSOHandshake();
}
```

### Limitations

In some cases, the `__omni_embed_vanity_session` cookie may be present even though the actual session has expired. If this occurs, the embedded Omni page will appear logged out. To handle this scenario, your application should be prepared to reinitiate the login flow when the embedded content indicates the user is not authenticated.

## Per-user OAuth support

Vanity domains enable per-user database OAuth for embed users, allowing each embedded user to authenticate with their own database credentials for Snowflake, BigQuery, and Databricks connections.

When using per-user OAuth with vanity-domain embeds, the OAuth popup redirects to your vanity domain origin instead of Omni's canonical origin. This keeps the popup in the same cookie partition as your embedded iframe, allowing the OAuth flow to complete successfully.

To use per-user OAuth with vanity-domain embeds, configure a vanity domain using the [steps above](#setup) and then follow the [OAuth setup guide](/connect-data/oauth) for your database.


# ai:chat-start embed event
Source: https://docs.omni.co/embed/events/ai-chat-start

Emitted by Omni when an AI chat session begins.

This event is emitted when:

* The `/chat` route loads in the embedded Omni application
* The workbook AI drawer is opened

Use this event to track when users start AI chat sessions or to trigger custom behaviors in your embedding application when AI features are accessed.

## Payload

```json theme={null}
{
  "chatSessionId": "string"
}
```

## Properties

<ParamField type="string">
  The unique identifier for the AI chat session that was started.
</ParamField>

## Example

```json theme={null}
{
  "chatSessionId": "chat-session-abc123"
}
```


# app:event embed event
Source: https://docs.omni.co/embed/events/app-event

Emitted by an embedded Omni app when its code calls omni.emit, so your page can react to what happens inside the app.

An [app](/visualize-present/apps) can send its own events to the page embedding Omni by calling `omni.emit(name, payload)` in the app's code. Each call arrives on your page as an `app:event` event.

Use this to react to something that happens inside the app — a row selection, a click on a call-to-action, or a state change your own product needs to know about.

The app author chooses the `name` and `payload`. Omni validates the size and rate of these events, but does not inspect or generate their content.

## Payload

```json theme={null}
{
  "name": "app:event",
  "payload": {
    "name": "string",
    "payload": "unknown"
  }
}
```

## Properties

<ParamField type="string">
  The event name the app passed to `omni.emit`. At most 128 characters.
</ParamField>

<ParamField type="unknown">
  The value the app passed to `omni.emit`. Must be JSON-serializable and at most 16,384 characters once serialized (about 16 KB). Optional — an app can emit a name with no payload.
</ParamField>

## Example

An app calls:

```javascript theme={null}
omni.emit('account-selected', { accountId: '8812', name: 'Blobs R Us' });
```

Your page receives:

```json theme={null}
{
  "name": "app:event",
  "payload": {
    "name": "account-selected",
    "payload": {
      "accountId": "8812",
      "name": "Blobs R Us"
    }
  }
}
```

Listening for it:

```javascript theme={null}
window.addEventListener('message', (event) => {
  if (event.data.name !== 'app:event') return;

  const { name, payload } = event.data.payload;
  if (name === 'account-selected') {
    showAccountDetail(payload.accountId);
  }
});
```

Refer to [Consuming events](/embed/events/consume) for the full listener setup, including origin checks.

## Limits

Omni drops an event without delivering it when:

* The event name is longer than 128 characters
* The serialized payload is longer than 16,384 characters
* The payload isn't JSON-serializable
* The app emits more than 20 events in 2 seconds

Because oversized events are dropped rather than truncated, send IDs and small summaries instead of whole result sets.

Outside of an embed, `omni.emit` does nothing, so an app that emits events is still safe to open directly in Omni.


# app:filter-changed embed event
Source: https://docs.omni.co/embed/events/app-filter-changed

Emitted by Omni when an embedded app changes the filters on one of its queries.

Omni emits `app:filter-changed` when an embedded [app](/visualize-present/apps) changes a filter on one of its queries after the app loads. An app changes filters through its own controls, which call `omni.query(name).setFilter()` and `.removeFilter()` in the app's code.

Use this to keep your own interface in sync with what someone has filtered to inside the app.

## Payload

```json theme={null}
{
  "name": "app:filter-changed",
  "payload": {
    "filters": {},
    "changed": []
  }
}
```

## Properties

<ParamField type="object">
  The complete set of filter overrides after the change, as an object of query name to field name to value. A query with no overrides is absent.
</ParamField>

<ParamField type="array">
  What differs from the previous state. One entry per changed field.

  <Expandable title="changed properties">
    <ParamField type="string">
      The name of the app query whose filter changed.
    </ParamField>

    <ParamField type="string">
      The fully-qualified field name the filter applies to.
    </ParamField>

    <ParamField type="string">
      The type of change:

      * `added` - A filter was set on a field that had none
      * `removed` - An existing filter was removed
      * `updated` - An existing filter's value changed
    </ParamField>

    <ParamField type="unknown">
      The previous filter value. Absent when `action` is `added`.
    </ParamField>

    <ParamField type="unknown">
      The new filter value. Absent when `action` is `removed`.
    </ParamField>
  </Expandable>
</ParamField>

## Example

Someone picks **Returned** in an app's status control, and the app calls `setFilter` on its `orders` query:

```json theme={null}
{
  "name": "app:filter-changed",
  "payload": {
    "filters": {
      "orders": {
        "order_items.status": "Returned"
      }
    },
    "changed": [
      {
        "queryName": "orders",
        "field": "order_items.status",
        "action": "updated",
        "prev": "Complete",
        "next": "Returned"
      }
    ]
  }
}
```

Values are the raw filter values the app passes to `setFilter` — a scalar, an array, or a filter object — so treat them as opaque unless you know what the app sends.

Refer to [Consuming events](/embed/events/consume) for the full listener setup, including origin checks.


# appearance:mode embed event
Source: https://docs.omni.co/embed/events/appearance-mode

Triggers a color scheme change of the embedded Omni session.

Use this event to programmatically control the appearance mode of your embedded Omni session and synchronize Omni's color scheme with your parent application's theme.

This event is useful when:

* You want to maintain visual consistency between your application and embedded Omni content
* Your application has a theme switcher and you need embedded content to match the selected theme
* You need to respond to system-level appearance changes and ensure embedded Omni follows suit

```json theme={null}
{
  "name": "appearance:mode",
  "payload": {
    "type": "dark" | "light" | "system"
  }
}
```

## Properties

<ParamField type="string">
  The appearance mode to apply. Accepts one of three values:

  * `dark` - Forces dark mode
  * `light` - Forces light mode
  * `system` - Uses the system's preferred color scheme
</ParamField>

## Example

Switch an embedded Omni session to dark mode:

```json theme={null}
{
  "name": "appearance:mode",
  "payload": {
    "type": "dark"
  }
}
```


# Consuming embed events sent by Omni
Source: https://docs.omni.co/embed/events/consume

Consume events emitted by Omni to trigger interactions in your application.

Using JavaScript events, you can trigger interactions in your application based on events in an Omni iframe.

## Event shape

Events emitted by Omni use the [`postMessage` protocol](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) and will have the following shape:

```typescript theme={null}
type EmbedEvent<Payload> = {
  payload: Payload
  description: string
  name: EmbedEventName
}
```

## Listening for events

Subscribe to events in the parent frame with the following:

```javascript expandable wrap theme={null}
const setFrameHeight = (height) => {
  // do the work to set the iframe element's height here
  // eg. `iframeElement.height = height`
}

const listener = (event) => {
  // Only accept messages from a known origin
  if (event.origin !== "https://example.embed-omniapp.co") return

  switch (event.data.name) {
    case 'size': {
      const { height } = event.data.payload
      height && setFrameHeight(height)
      break
    }
    case 'page:changed': {
      // Do something with the page:changed event, etc
    }
  }
}

// Must attach the event listener for messages.
window.addEventListener('message', listener)
```

## Supported events

Omni currently emits the following events:

| Event                                                                | Description                                                                                        |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`ai:chat-start`](/embed/events/ai-chat-start)                       | Emitted by Omni when an AI chat session begins.                                                    |
| [`app:event`](/embed/events/app-event)                               | Emitted by an embedded app when its code calls `omni.emit`.                                        |
| [`app:filter-changed`](/embed/events/app-filter-changed)             | Emitted by Omni when an embedded app changes the filters on one of its queries.                    |
| [`dashboard:download`](/embed/events/dashboard-download)             | Emitted by Omni when a user downloads an embedded dashboard.                                       |
| [`dashboard:filter-changed`](/embed/events/dashboard-filter-changed) | Emitted by Omni when a user adds, removes, or updates a filter on an embedded document.            |
| [`dashboard:filters`](/embed/events/dashboard-filters)               | Emitted by Omni when a user applies a filter to an embedded document.                              |
| [`dashboard:tile-download`](/embed/events/dashboard-tile-download)   | Emitted by Omni when a user downloads a given tile on a dashboard.                                 |
| [`dashboard:tile-drill`](/embed/events/dashboard-tile-drill)         | Emitted by Omni when a user performs a drill action on a dashboard tile.                           |
| [`error`](/embed/events/error)                                       | Emitted by Omni when a detectable error occurs on an embedded page.                                |
| [`fullscreen:changed`](/embed/events/fullscreen-changed)             | Emitted by Omni when the fullscreen state of an embedded dashboard or app changes.                 |
| [`navigation:home`](/embed/events/navigation-home)                   | Emitted by Omni when a user clicks the logo or home link in the navigation header.                 |
| [`page:changed`](/embed/events/page-changed)                         | Emitted by Omni when the URL of a page changes.                                                    |
| [`sidebar:open`](/embed/events/sidebar-open)                         | Emitted by Omni when a user clicks the mobile menu button.                                         |
| [`size`](/embed/events/size)                                         | Emitted by Omni to give the size of embedded content, allowing you to dynamically size the iframe. |
| [`status`](/embed/events/status)                                     | Emitted by Omni to indicate the status of the dashboard to the parent frame.                       |


# dashboard:download embed event
Source: https://docs.omni.co/embed/events/dashboard-download

Emitted by Omni when a user downloads an embedded dashboard.

## Payload

```json theme={null}
{
  "userId": "string",
  "dashboard": {
    "filters": {
      "filterName": {
        "filter": "filterObject",
        "asJsonUrlSearchParam": "string"
      }
    },
    "href": "string",
    "urlId": "string",
    "path": "string",
    "title": "string"
  },
  "format": "string"
}
```

## Properties

<ParamField type="string">
  ID of the user who downloaded the dashboard.
</ParamField>

<ParamField type="object">
  Information about the dashboard being downloaded.

  <Expandable title="dashboard properties">
    <ParamField type="object">
      Filters applied to the dashboard, keyed by filter name.

      <Expandable title="filters properties">
        <ParamField type="Filter">
          An object representing the filter.
        </ParamField>

        <ParamField type="string">
          Filter as a JSON URL search param that can be used in dashboard URLs.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Full URL of the dashboard.
    </ParamField>

    <ParamField type="string">
      ID of the dashboard used in the URL.
    </ParamField>

    <ParamField type="string">
      Path to the dashboard.
    </ParamField>

    <ParamField type="string">
      Title of the dashboard.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Download format. One of `pdf`, `csv`, or `xlsx`.
</ParamField>


# dashboard:filter-change-by-url-parameter embed event
Source: https://docs.omni.co/embed/events/dashboard-filter-change-by-url-parameter

Triggers the change of a filter value on an embedded dashboard.

<Note>
  This event can only be processed by dashboards. Sending this event to an iframe that contains a non-dashboard Omni URL will have no effect on the embedded page.
</Note>

Only filters included in the parameter are affected. Any existing filters that aren't included will retain their existing values.

```json theme={null}
{
  "name": "dashboard:filter-change-by-url-parameter",
  "payload": {
    "filterUrlParameter": "string"
  }
}
```

## Properties

<ParamField type="string">
  A filter specification object that defines the filter values to apply. Filter specifications are formatted as follows:

  ```
  f--<filter_id>={"values":["value1","value2", ...]}
  ```

  <Tip>
    You can retrieve values for this parameter by using Omni in a non-embedded context. Navigate to a dashboard with filters and change the filter values. The URL will change when new filter values are applied - use what's in the URL as the value for this parameter.
  </Tip>
</ParamField>

## Example

```json wrap theme={null}
{
  "name": "dashboard:filter-change-by-url-parameter",
  "payload": {
    "filterUrlParameter": "f--order_items.status=%7B"appliedLabels"%3A%7B%7D%2C"values"%3A%5B"Complete"%5D%7D"
  }
}
```


# dashboard:filter-changed embed event
Source: https://docs.omni.co/embed/events/dashboard-filter-changed

Emitted by Omni when a user adds, removes, or updates a filter on an embedded document.

## Payload

```json theme={null}
{
  "name": "dashboard:filter-changed",
  "payload": {
    "prev": {
      "filter": "OmniQueryFilter",
      "asJsonUrlSearchParam": "string",
    },
    "next": {
      "filter": "OmniQueryFilter",
      "asJsonUrlSearchParam": "string",
    },
    "action": "string",
    "urlId": "string",
  }
}
```

## Properties

<ParamField type="object">
  The previous state of the filter before the change.

  <Expandable title="prev properties">
    <ParamField type="OmniQueryFilter">
      An object representing the previous filter configuration.
    </ParamField>

    <ParamField type="string">
      The previous filter as a JSON URL search param that can be used in dashboard URLs.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  The new state of the filter after the change.

  <Expandable title="next properties">
    <ParamField type="OmniQueryFilter">
      An object representing the new filter configuration.
    </ParamField>

    <ParamField type="string">
      The new filter as a JSON URL search param that can be used in dashboard URLs.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The type of filter change:

  * `added` - A new filter was added
  * `removed` - An existing filter was removed
  * `updated` - An existing filter's value or configuration changed
</ParamField>

<ParamField type="string">
  The URL identifier for the dashboard where the filter was changed.
</ParamField>

## Example

```json wrap theme={null}
{
  "users.id": {
    "filter": {
      "is_negative": false,
      "kind": "EQUALS"
    },
    "asJsonUrlSearchParam": "f--users.id=%7B\"is_inclusive\"%3Afalse%2C\"is_negative\"%3Afalse%2C\"kind\"%3A\"EQUALS\"%2C\"type\"%3A\"number\"%2C\"values\"%3A%5B\"3\"%5D%7D"
  }
}
```


# dashboard:filters embed event
Source: https://docs.omni.co/embed/events/dashboard-filters

Emitted by Omni when a user applies a filter to an embedded document.

## Payload

```json theme={null}
{
  "<filterName>": {
    "filter": {
      "is_negative": false,
      "kind": "EQUALS"
    },
    "asJsonUrlSearchParam": "string"
  }
}
```

## Properties

<ParamField type="object">
  Filter object keyed by the filter name (e.g., `users.id`).

  <Expandable title="filter properties">
    <ParamField type="object">
      An object representing the filter configuration. Contains properties like `is_negative`, `kind`, and other filter-specific properties.
    </ParamField>

    <ParamField type="string">
      Filter as a JSON URL search param that can be used in dashboard URLs.
    </ParamField>
  </Expandable>
</ParamField>

## Example

```json wrap theme={null}
{
  "users.id": {
    "filter": {
      "is_negative": false,
      "kind": "EQUALS"
    },
    "asJsonUrlSearchParam": "f--users.id=%7B\"is_inclusive\"%3Afalse%2C\"is_negative\"%3Afalse%2C\"kind\"%3A\"EQUALS\"%2C\"type\"%3A\"number\"%2C\"values\"%3A%5B\"3\"%5D%7D"
  }
}
```


# dashboard:tile-download embed event
Source: https://docs.omni.co/embed/events/dashboard-tile-download

Emitted by Omni when a user downloads a given tile on a dashboard.

## Payload

```json theme={null}
{
  "userId": "string",
  "dashboard": {
    "filters": {
      "<filterName>": {
        "filter": "filterObject",
        "asJsonUrlSearchParam": "string"
      }
    },
    "href": "string",
    "urlId": "string",
    "path": "string",
    "title": "string"
  },
  "format": "string",
  "tile": {
    "id": "string",
    "title": "string",
    "appliedFilters": {
      "filterName": {
        "filter": "filterObject",
        "asJsonUrlSearchParam": "string"
      }
    }
  }
}
```

## Properties

<ParamField type="string">
  ID of the user who downloaded the tile.
</ParamField>

<ParamField type="object">
  Information about the dashboard containing the tile.

  <Expandable title="dashboard properties">
    <ParamField type="object">
      Filters applied to the dashboard, keyed by filter name.

      <Expandable title="filters properties">
        <ParamField type="Filter">
          An object representing the filter.
        </ParamField>

        <ParamField type="string">
          Filter as a JSON URL search param that can be used in dashboard URLs.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Full URL of the dashboard.
    </ParamField>

    <ParamField type="string">
      ID of the dashboard used in the URL.
    </ParamField>

    <ParamField type="string">
      Path to the dashboard.
    </ParamField>

    <ParamField type="string">
      Title of the dashboard.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Download format. One of `csv`, `xlsx`, or `png`.
</ParamField>

<ParamField type="object">
  Information about the downloaded tile.

  <Expandable title="tile properties">
    <ParamField type="string">
      ID of the tile.
    </ParamField>

    <ParamField type="string">
      Title of the tile.
    </ParamField>

    <ParamField type="object">
      Filters applied to the tile, keyed by filter name.

      <Expandable title="appliedFilters properties">
        <ParamField type="Filter">
          An object representing the filter.
        </ParamField>

        <ParamField type="string">
          Filter as a JSON URL search param that can be used in dashboard URLs.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>


# dashboard:tile-drill embed event
Source: https://docs.omni.co/embed/events/dashboard-tile-drill

Emitted by Omni when a user performs a drill action on a dashboard tile.

## Payload

```json theme={null}
{
  "userId": "string",
  "dashboard": {
    "filters": {
      "<filterName>": {
        "filter": "filterObject",
        "asJsonUrlSearchParam": "string"
      }
    },
    "href": "string",
    "urlId": "string",
    "path": "string",
    "title": "string"
  },
  "tile": {
    "id": "string",
    "title": "string",
    "appliedFilters": {
      "<filterName>": {
        "filter": "filterObject",
        "asJsonUrlSearchParam": "string"
      }
    }
  },
  "drill": {
    "field": "string",
    "fieldLabel": "string",
    "drillQueryLabel": "string",
    "rowToDrill": {
      "<fieldName>": "string | null"
    }
  }
}
```

## Properties

<ParamField type="string">
  ID of the user who performed the drill action.
</ParamField>

<ParamField type="object">
  Information about the dashboard containing the tile.

  <Expandable title="dashboard properties">
    <ParamField type="object">
      Filters applied to the dashboard, keyed by filter name.

      <Expandable title="filters properties">
        <ParamField type="object">
          An object representing the filter.
        </ParamField>

        <ParamField type="string">
          Filter as a JSON URL search param that can be used in dashboard URLs.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Full URL of the dashboard, including the drill path.
    </ParamField>

    <ParamField type="string">
      ID of the dashboard used in the URL.
    </ParamField>

    <ParamField type="string">
      Path to the dashboard drill.
    </ParamField>

    <ParamField type="string">
      Title of the dashboard.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Information about the tile where the drill action was performed.

  <Expandable title="tile properties">
    <ParamField type="string">
      ID of the tile.
    </ParamField>

    <ParamField type="string">
      Title of the tile.
    </ParamField>

    <ParamField type="object">
      Filters applied to the tile, keyed by filter name.

      <Expandable title="appliedFilters properties">
        <ParamField type="object">
          An object representing the filter.
        </ParamField>

        <ParamField type="string">
          Filter as a JSON URL search param that can be used in dashboard URLs.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Information about the drill action.

  <Expandable title="drill properties">
    <ParamField type="string">
      The name of the field being drilled into.
    </ParamField>

    <ParamField type="string">
      The display label for the field. This property is optional.
    </ParamField>

    <ParamField type="string">
      The label for the drill query. This property is optional.
    </ParamField>

    <ParamField type="object">
      The row data being drilled into, keyed by field name. Values may be `null` if the field value is not set.
    </ParamField>
  </Expandable>
</ParamField>


# error embed event
Source: https://docs.omni.co/embed/events/error

Emitted by Omni when a detectable error occurs on an embedded page.

## Error display behavior

Embedded content displays a generic error message to end users when a query runtime error occurs. Detailed error information, such as database connection details or warehouse-specific messages, is not shown in the embedded UI. The exact message depends on where the error appears:

* **Dashboard tiles, spreadsheet tiles, and drills** display "Something went wrong"
* **Workbook results pane** displays "Something went wrong" with the subtitle "There was an issue running this query. Contact your administrator."

This is automatic and requires no configuration. [Custom dashboard state messages](/visualize-present/dashboards/custom-state-message), if configured, are still displayed.

To capture the underlying error details, listen for the `error` event in your host application. The event payload includes the full error message, which you can log or use to build a custom error experience.

## Payload

```json theme={null}
{
  "href": "string",
  "message": "string"
}
```

## Properties

<ParamField type="string">
  The fully qualified URL, e.g., `https://blobsrus.omniapp.co/dashboards/123abc?f--users.email=someone@example.com`.
</ParamField>

<ParamField type="string">
  The full error message. This may contain details not shown to the embedded user, such as database or warehouse-specific information.
</ParamField>


# fullscreen:changed embed event
Source: https://docs.omni.co/embed/events/fullscreen-changed

Emitted by Omni when the fullscreen state of an embedded dashboard or app changes.

Omni emits this event whenever fullscreen mode is entered or exited through any mechanism: the menu item, keyboard shortcut, native `Esc` key exit, or unmount while fullscreen.

This event is emitted for both dashboards and apps. It does not fire on initial mount.

## Payload

```json theme={null}
{
  "name": "fullscreen:changed",
  "payload": {
    "isFullScreen": true
  }
}
```

## Properties

<ParamField type="boolean">
  Indicates whether the embedded content is currently in fullscreen mode.

  * `true` - Fullscreen mode is active
  * `false` - Fullscreen mode is not active
</ParamField>

## Example

```json theme={null}
{
  "name": "fullscreen:changed",
  "payload": {
    "isFullScreen": true
  }
}
```


# fullscreen:set embed event
Source: https://docs.omni.co/embed/events/fullscreen-set

Sets the fullscreen presentation state of the embedded Omni session.

Use this event to programmatically control the fullscreen state of your embedded Omni session and build custom fullscreen controls in the parent application.

This event is useful when:

* You want to build your own fullscreen button in the parent application
* You need to keep Omni's presentation state in sync with native browser fullscreen
* You want to provide a consistent fullscreen experience across your application

<Warning>
  The `postMessage` protocol does not carry user activation, so sending this event alone only applies Omni's CSS overlay presentation. To enable true browser fullscreen, call `iframeElement.requestFullscreen()` in your own click handler first, then post `fullscreen:set` to sync Omni's presentation styling.
</Warning>

```json theme={null}
{
  "name": "fullscreen:set",
  "payload": {
    "isFullScreen": true
  }
}
```

## Properties

<ParamField type="boolean">
  The fullscreen presentation state to apply. Accepts one of:

  * `true` - Activates fullscreen presentation mode
  * `false` - Deactivates fullscreen presentation mode
</ParamField>

## Example

This example demonstrates a parent-controlled fullscreen implementation that coordinates native browser fullscreen with Omni's presentation state:

```html theme={null}
<iframe id="omni" src="https://embed.example.omni.co/dashboards/abc123" allow="fullscreen" allowfullscreen></iframe>
<button id="fullscreen-btn">Full screen</button>

<script>
  const iframe = document.getElementById('omni')

  document.getElementById('fullscreen-btn').addEventListener('click', () => {
    // Native fullscreen needs the click's user activation, so the parent
    // requests it on the iframe element itself...
    iframe.requestFullscreen()
    // ...and tells Omni to apply its presentation styling.
    iframe.contentWindow.postMessage(
      { name: 'fullscreen:set', payload: { isFullScreen: true } },
      'https://embed.example.omni.co'
    )
  })

  // Keep the parent in sync however fullscreen was entered or exited
  // (Omni's own button, keyboard shortcut, Esc).
  window.addEventListener('message', ({ data }) => {
    if (data?.source === 'omni' && data.name === 'fullscreen:changed') {
      console.log('fullscreen:', data.payload.isFullScreen)
      if (!data.payload.isFullScreen && document.fullscreenElement) {
        document.exitFullscreen()
      }
    }
  })
</script>
```


# Embed events
Source: https://docs.omni.co/embed/events/index

Build interactive experiences in your embedded Omni application with JavaScript events.

Omni events make it easy to create interactive, integrated experiences when embedding Omni in your application:

* With just a few lines of JavaScript, [your app can listen](/embed/events/consume) for what users are doing inside embedded Omni content - like selecting filters, downloading content, or switching tabs - and respond in real time.

* You can also [send events back into Omni](/embed/events/send) to drive the experience from the outside, whether that’s updating filters in embedded content or navigating to a specific page.

* Omni's [table and Markdown visualizations](/embed/events/visualizations) can emit events on click with a little bit of configuration


# navigate embed event
Source: https://docs.omni.co/embed/events/navigate

Triggers a redirect to the path specified in the payload.

<Warning>
  Content and/or connection permissions are not automatically provided to the user during a `navigate` event. This means if you redirect a user to a dashboard or workbook, the user will need the appropriate content and/or connection permissions to view the content.
</Warning>

```json theme={null}
{
  "name": "navigate",
  "payload": {
    "path": "string"
  }
}
```

## Properties

<ParamField type="string">
  The path to redirect to.
</ParamField>

## Example

```json theme={null}
{
  "name": "navigate",
  "payload": {
    "path": "/dashboards/abcd1234"
  }
}
```


# navigation:home embed event
Source: https://docs.omni.co/embed/events/navigation-home

Emitted by Omni when a user clicks the logo or home link in the navigation header.

This event is emitted when users interact with the home navigation elements:

* Clicking the Omni logo
* Clicking the home link in the header

Use this event to track when users navigate to the home page or to trigger custom navigation behaviors in your embedding application.

## Payload

This event carries an empty payload and serves as a notification signal only.

```json theme={null}
{}
```

## Example

When a user clicks the logo or home link, Omni emits:

```json theme={null}
{
  "name": "navigation:home",
  "payload": {}
}
```


# page:changed embed event
Source: https://docs.omni.co/embed/events/page-changed

Emitted by Omni when the URL of a page changes.

This can be consumed by the embedding frame to generate shareable links.

## Payload

```json theme={null}
{
  "href": "string",
  "pathname": "string",
  "search": "string",
  "type": "string"
}
```

## Properties

<ParamField type="string">
  The fully qualified URL, e.g., `https://blobsrus.omniapp.co/dashboards/123abc?f--users.email=someone@example.com`.
</ParamField>

<ParamField type="string">
  The path of the URL (e.g., `/dashboards/123abc`).
</ParamField>

<ParamField type="string">
  Query params from the URL, e.g., `?f--users.email=someone@example.com`.
</ParamField>

<ParamField type="string">
  Type of page. One of `dashboard`, `workbook`, or `other`.
</ParamField>

## Example

```json wrap theme={null}
{
  "href": "https://blobsrus.omniapp.co/dashboards/123abc?f--users.email=someone@example.com",
  "pathname": "/dashboards/123abc",
  "search": "?f--users.email=someone@example.com",
  "type": "dashboard"
}
```


# Sending embed events to Omni
Source: https://docs.omni.co/embed/events/send

Trigger actions in an embedded Omni application by sending events into the Omni iframe.

You can send events into an Omni iframe to trigger actions in your embedded Omni application. Like emitted events, events sent to Omni should use the [`postMessage` protocol](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

## Event shape

Events sent to Omni are expected to have the following shape:

```typescript theme={null}
type EmbedEvent<Payload> = {
  payload: Payload
  name: EmbedEventName
}
```

The following is an example of a JavaScript event handler that sends a `navigate` embed event to an Omni iframe via `postmessage`:

```javascript wrap theme={null}
const handleNavigateButtonClick = (path) => {
  document.querySelector('iframe').contentWindow.postMessage(
    {
      name: "navigate",
      payload: { path },
    },
    "https://youromniorganization.embed-omniapp.co"
  );
};
```

## Supported events

The following events can be sent to an Omni iframe:

| Event                                                                                                | Description                                                          |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [`appearance:mode`](/embed/events/appearance-mode)                                                   | Triggers a color scheme change of the embedded Omni session.         |
| [`dashboard:filter-change-by-url-parameter`](/embed/events/dashboard-filter-change-by-url-parameter) | Triggers the change of a filter value on an embedded dashboard.      |
| [`fullscreen:set`](/embed/events/fullscreen-set)                                                     | Sets the fullscreen presentation state of the embedded Omni session. |
| [`navigate`](/embed/events/navigate)                                                                 | Triggers a redirect to the path specified in the payload.            |


# sidebar:open embed event
Source: https://docs.omni.co/embed/events/sidebar-open

Emitted by Omni when a user clicks the mobile menu button.

This event is emitted when users click the mobile menu button to open the [sidebar](/administration/settings/sidebar) navigation.

Use this event to track when users interact with mobile navigation or to trigger custom behaviors in your embedding application when the sidebar is accessed.

<Note>
  This event is informational only. The sidebar popover will still open within the embedded iframe regardless of how the parent application handles this event.
</Note>

## Payload

This event carries an empty payload and serves as a notification signal only.

```json theme={null}
{}
```

## Example

When a user clicks the mobile menu button, Omni emits:

```json theme={null}
{
  "name": "sidebar:open",
  "payload": {}
}
```


# size embed event
Source: https://docs.omni.co/embed/events/size

Emitted by Omni to give the size of embedded content, allowing you to dynamically size the iframe.

Omni emits the `size` event when a dashboard loads, and when an embedded [app](/visualize-present/apps) loads or resizes. This allows you to dynamically adjust the iframe height to fit the content.

The payload is the same for both, so an existing dashboard resize handler will size an app without changes.

An app only emits the event when it fills the whole frame, with no Omni header or navigation around it — which is what [`SINGLE_CONTENT`](/embed/setup/url-parameters/mode) mode gives you. An app shown with Omni's chrome doesn't emit it, because a size that excluded the chrome would make the host clip the page.

## Payload

```json theme={null}
{
  "width": number,
  "height": number
}
```

## Properties

<ParamField type="number">
  Width of the embedded content in the iframe.
</ParamField>

<ParamField type="number">
  Height of the embedded content in the iframe.
</ParamField>

## Example

```json theme={null}
{
  "width": 600,
  "height": 400
}
```


# status embed event
Source: https://docs.omni.co/embed/events/status

Emitted by Omni to indicate the status of the dashboard to the parent frame.

## Payload

```json theme={null}
{
  "status": "string",
  "dashboardId": "string"
}
```

## Properties

<ParamField type="string">
  Status of the dashboard in the iframe. One of `loading`, `running`, `done`, or `error`.
</ParamField>

<ParamField type="string">
  The identifier of the dashboard that emitted the status event. This allows embedded dashboard consumers to identify which dashboard is reporting its status.
</ParamField>

## Example

```json theme={null}
{
  "status": "loading",
  "dashboardId": "dashboard-123abc"
}
```


# Sending embed events from Omni visualizations
Source: https://docs.omni.co/embed/events/visualizations

Trigger actions in your application by emitting events from embedded Omni table and Markdown visualizations.

Omni's Markdown and table visualizations can be configured to emit events. These events can be observed by listeners in the parent frame to trigger certain actions, such as popping open custom drill modals or passing through certain data from Omni to the parent frame.

## Table visualizations

Events can be triggered on click in table visualizations.

<img alt="" />

1. Open the configuration options for a table visualization.
2. Next to a field, click the <Icon icon="caret-down" /> to open its configuration options.
3. Click the **Display** tab.
4. Set **Display as** to **Link**.
5. Set **URL** to **Embed event**.
6. Enter a name for the event.

## Markdown visualizations

You can also send events from Markdown visualizations. When clicked, a post message is sent from the iframe to the parent iframe.

Use a tag like the following, setting the event name and data, to accomplish this:

```html wrap theme={null}
<omni-message event-name="product-image-click" event-data="{{products.name.raw}},{{products.retail_price.raw}},{{products.sku.raw}}">
```


# Embedding Omni in external applications
Source: https://docs.omni.co/embed/index

Embed Omni dashboards and analytics in external applications with row-level permissions, SSO, and full theme customization.

External embedding enables delivering data to users outside of the business, living in other applications. Reporting can be mapped to row level permissions, allowing many users to access identical reports filtered to only their own data.

Using embedded Omni content, you could create:

* Simple, interactive dashboards for high-level summaries
* Short-lived workbooks to give their users deeper access to their data
* More robust data applications

All these use cases leverage the same base technology: creating an authorized Omni URL that you'll use in an iframe. The URL contains the content you want to share, the ID of the user in your system, and the attributes you want that user to have. You'll then sign the URL with a secret key provided by Omni.

## See it in action

* Follow along [on Youtube](https://www.youtube.com/watch?v=4XRgDRv9SRM) as we build a data product, going from analysis to dashboard to stylized app in 30 minutes

* Check out the **Analytics** tab in your Omni instance! This is an example of embedded content in [Create mode](/embed/customization/create-mode) that shows information about the usage of your Omni instance. **Note**: This feature is only available to Organization Admins.


# Embedding limitations
Source: https://docs.omni.co/embed/limitations

Understand current limitations of Omni embedding, including session length, supported browsers, content types, and feature gaps.

## Session length

Currently, using a valid embed URL will create an embed session that can be configured to last between 0-576 hours. That embed session will be unusable after the configured expiry. Visiting a new, valid embed SSO URL at any time will create a new session.

## Chrome incognito

Using Chrome in Incognito mode requires allowing third-party cookies. These can be found under **Chrome > Settings... > Privacy and Security > Third-party cookies**. Enable the **Allow third-party cookies** option.

## Default iframe restrictions

By default, iframes restrict access to certain functionality that could post a security risk, such as copying or using the mircophone. However, you can allow your users to use these features by including them in your iframe declarations. See [Enabling iframe-restricted functionality for embedded instances](/embed/customization/iframes) for more information.

## Keyboard shortcuts

[Keyboard shortcuts](/getting-started/keyboard-shortcuts) are not currently supported in embedded Omni instances.

## Safari, mobile Safari, and mobile iOS Chrome

Omni uses cookies to manage authentication sessions. When embedded in iframes, browsers like Safari treat these as third-party cookies and block them by default, which prevents access to Omni content.

How you handle this depends on which Safari version your users have and whether you've configured a vanity domain.

### Safari 26.2 and newer - Automatic handling

Safari 26.2+ supports CHIPS (Cookies Having Independent Partitioned State), which allows embedded content to authenticate automatically without requiring user action. Omni detects CHIPS support and handles authentication seamlessly.

This automatic experience works in:

* Safari 26.2+ on macOS
* Safari 26.2+ on iOS and iPadOS

### Safari 26.1 and older - Manual handshake

Older Safari versions require a multi-step handshake that prompts users to explicitly allow third-party cookies:

1. When the embedded dashboard loads, a `Cookies are not permitted` message appears with a button to visit the Omni instance directly.
2. After visiting Omni in a non-embedded context, the user returns to the embedded page.
3. Safari prompts the user to allow access to "use cookies and website data". Clicking **Allow** displays the embedded dashboard.

Users typically only need to complete this process once, though Safari may occasionally prompt them again.

### Vanity domains - Alternative approach

Configuring a [vanity domain](/embed/customization/vanity-domains) allows Omni cookies to originate from your embedding domain, making them first-party cookies. This eliminates Safari's third-party cookie restrictions entirely across all Safari versions.

Vanity domains require infrastructure setup but provide a consistent experience regardless of browser version or privacy settings.

<Note>
  Vanity domain embeds continue to use the Storage Access API handshake flow even on Safari 26.2+, as CHIPS partitioned cookies do not support custom domain attributes.
</Note>

## Per-user database OAuth

[Per-user OAuth for database connections](/connect-data/oauth) is only supported with [vanity-domain embeds](/embed/customization/vanity-domains).

When using per-user OAuth, Omni opens a popup for database authentication. This popup must share the same cookie partition as the embedded iframe to complete the OAuth flow. Default embed domains (`embed-*`) use a different registrable domain than your embedding page, which places them in separate cookie partitions and prevents the OAuth flow from completing.

Vanity domains solve this by using your own subdomain (e.g., `omni.myapp.com` embedded in `myapp.com`), keeping both the iframe and popup in the same cookie partition.


# Embedding Omni quickstart
Source: https://docs.omni.co/embed/quickstart

Get up and running with your embedded Omni application.

<Note>
  **Organization Admin** permissions are required to follow the steps in this guide.
</Note>

<Steps>
  <Step title="Contact Omni support">
    First, reach out to Omni support to have the **Embed** feature enabled for your instance.
  </Step>

  <Step title="Set up session generation">
    You have two options when it comes to generating embedded user sessions:

    1. [**Standard SSO**](/embed/setup/standard-sso): Generate and use a single URL to create an embed user and session. This is the simplest way to embed Omni for your external users.
    2. [**2-step SSO**](/embed/setup/two-step-sso): First, send a `POST` request to generate the embed user and session. Then, generate and use a URL to authenticate into the session. This requires more setup, but has a few advantages over the standard SSO embed experience:

       * **Sensitive user data**: If using the `userAttributes` parameter with sensitive user data, you may prefer creating SSO embed users and sessions via `POST` request for added security.
       * **URL length**: While generally unlikely, there is more risk of standard SSO embed URLs exceeding a browser's URL character limit. 2-step login URLs are more compact and thus have no risk of hitting the limit.

    Follow the guide for your preferred approach to complete the implementation.

    <Warning>
      While Omni is where permissions and content are managed, the application where the content is embedded should dynamically map users to the right underlying data. Refer to the [Embedding best practices](/embed/best-practices) to make sure Omni is set up correctly before you begin developing.
    </Warning>
  </Step>

  <Step title="Customize your application">
    Once you successfully set up your embed infrastructure, you can:

    * Change your application's look and feel with [custom theming](/embed/customization/themes)
    * Add interactivity with [events](/embed/events)
    * Implement [vanity domains](/embed/customization/vanity-domains) for a fully whitelabeled experience
  </Step>
</Steps>


# Customizing embed users and sessions with URL parameters
Source: https://docs.omni.co/embed/setup/customize

Customize embed users and sessions with Omni embed parameters.

For example, you can use embed URL parameters to:

* Specify user content roles
* Assign connection and model roles to users
* Control the look and theme of your embedded application
* Apply user attributes to users

## Providing parameters

How parameters are provided depends on the type of SSO setup your embed implementation uses:

* [**In standard SSO embed**](/embed/setup/standard-sso), parameters are passed as URL query parameters:

  ```markdown wrap theme={null}
  https://omni.blobsrus.com/embed/login?contentPath=%2Fmy&externalId=artiste1322&name=Blob+Ross&nonce=7RR6BdkQ8FgXf2FHABLFhWTebflsWya2&signature=VwmHh5ygv35i0Zc8mTiT6ugRnzqwBLfEP83ZDh6pfVE&entity=Happy+Trees&connectionRoles=%7B%7D&entityFolderContentRole=EDITOR&preserveEntityFolderContentRole=false
  ```

* [**In 2-step SSO embed**](/embed/setup/two-step-sso), the majority of these parameters are included as a JSON payload in the `POST /generate-session` request:

  ```json wrap title="POST /api/unstable/embed/sso/generate-session" theme={null}
  curl -X POST 'https://omni.blobsrus.com/api/unstable/embed/sso/generate-session' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contentPath": "/my",
    "externalId": "artiste1322",
    "name": "Blob Ross",
    "entity": "Happy Trees",
    "entityFolderContentRole": "EDITOR"
  }'
  ```

## Available parameters

Refer to the [Embed URL parameters reference](/embed/setup/url-parameters) for a complete list of parameters and examples.


# Generating embedded user sessions
Source: https://docs.omni.co/embed/setup/index

Set up your embedding infrastructure and generate user sessions.

You have two options when it comes to generating embedded user sessions:

## Easy: Standard SSO

With [**standard SSO**](/embed/setup/standard-sso), you generate and use a single URL to create an embed user and session. This is the simplest way to embed Omni for your external users.

## Advanced: 2-step SSO

With [**2-step SSO**](/embed/setup/two-step-sso), you start by sending a `POST` request to generate the embed user and session. Then, you'll generate and use a URL to authenticate into the session. This requires more setup, but has a few advantages over the standard SSO embed experience:

* **Sensitive user data**: If using the `userAttributes` parameter with sensitive user data, you may prefer creating SSO embed users and sessions via `POST` request for added security.
* **URL length**: While generally unlikely, there is more risk of standard SSO embed URLs exceeding a browser's URL character limit. 2-step login URLs are more compact and thus have no risk of hitting the limit.


# Embed standard SSO
Source: https://docs.omni.co/embed/setup/standard-sso/index

Set up standard SSO for Omni embedding by generating a signed URL that creates an embed user session with a single request.

With standard SSO, you generate and use a single URL to create an embed user and session. Omni embed URLs are signed with a secret key used only by your organization. When an Omni server receives the request, it verifies the signature using that secret. If the signature checks out, the request is honored.

Two signing formats are supported for standard SSO:

| Format                                                      | Status                         | Description                                                                                                                                                                                                       |
| ----------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**v1 (signed payload)**](/embed/setup/standard-sso/latest) | <Badge>latest</Badge>          | Every [parameter](/embed/setup/url-parameters) is included inside a single `payload` query parameter that the signature covers as a whole. If generating with the SDK, requires `@omni-co/embed` v1.0.0 or later. |
| [**v0 (legacy)**](/embed/setup/standard-sso/v0-legacy)      | <Badge>v1 (deprecated)</Badge> | Each parameter is sent as its own query parameter alongside a `signature`. Deprecated: unsupported after October 1, 2026, and removed by January 1, 2027.                                                         |

Both formats are accepted at `/embed/login`, so existing integrations will continue to work. Use v1 for new integrations, and plan to migrate existing ones.

<Warning>
  Because embed URLs are signed using your Omni organization's embed secret, it is crucial that your embed URLs are generated server-side rather than client-side. From a security perspective, this protects your embed secret from being exposed to attackers.

  Also note that the Omni TypeScript SDK utilizes Node's `crypto` module, which is only available in Node environments. Attempting to use the Omni TypeScript SDK functions in a client-side context will likely lead to the SDK functions generating improperly signed embed URLs.
</Warning>


# Setting up embed standard SSO with the v1 signing payload format
Source: https://docs.omni.co/embed/setup/standard-sso/latest

Set up standard SSO for Omni embedding by generating a signed URL that creates an embed user session with a single request.

In this guide, you'll set up standard SSO for Omni embed using the v1 (latest) signing format. As the simplest way to embed Omni, this involves generating and using a single URL to create an embed user session.

<Note>
  **Migrating from v0?** See [Migrating to the v1 embed standard SSO signing format](/embed/setup/standard-sso/migrate-to-latest) to learn about what changed in v1 and how to migrate your code.
</Note>

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions
* To have the **Embed** feature enabled in your Omni instance

If you want to use the [Omni TypeScript SDK](https://www.npmjs.com/package/@omni-co/embed) to generate an embed URL, you'll need `@omni-co/embed` v1.0.0 or later:

```bash theme={null}
npm install @omni-co/embed
```

<Steps>
  <Step title="Generate an embed secret">
    1. Navigate to **Settings > Embed > Admin** in your Omni instance.
    2. Click the **Add Secret** button below the secrets table.
    3. In the dialog that appears:
       * A 32-character secret key is automatically generated for you
       * Enter a descriptive **Name** to identify the secret's purpose (e.g., "Production", "Staging", or "Partner Integration")

         <Tip>
           Use descriptive names for your secrets to make them easier to identify and manage, especially when rotating secrets or managing multiple environments.
         </Tip>
    4. Click **Add secret** to save the new secret.
  </Step>

  <Step title="Customize session length">
    <Note>
      This step is optional.
    </Note>

    In the [**Embed** settings](/embed/admin/security) of your Omni instance, you can also customize the length of embed sessions using the **Session Length** setting. In this field, enter the number of hours you want sessions to last and click **Change**.
  </Step>

  <Step title="Generate an embed URL">
    <Warning>
      Because embed URLs are signed using your Omni organization's embed secret, it is crucial that your embed URLs are generated server-side rather than client-side. From a security perspective, this protects your embed secret from being exposed to attackers.
    </Warning>

    Omni embed URLs are signed with a secret key used only by your organization. When an Omni server receives the request, it verifies the signature using that secret. If the signature checks out, the request is honored.

    There are three ways to generate a signed embed URL - the SDK (recommended), the API, or manually. **Click the tabs below to view instructions for each approach.**

    <Tabs>
      <Tab title="SDK (Recommended)" icon="trophy">
        Omni's [TypeScript SDK](https://www.npmjs.com/package/@omni-co/embed) is the recommended way to generate embed URLs. Each function returns a complete, signed login URL:

        ```typescript title="Generate a v1 signed embed URL" wrap theme={null}
        import { embedSsoDashboard } from "@omni-co/embed";

        const iframeUrl = await embedSsoDashboard({
          contentId: "123abc",
          externalId: "blob.ross@blobsrus.com",
          name: "Blob Ross",
          organizationName: "blobsrus",
          secret: process.env.OMNI_EMBED_SECRET,
          entity: "Blobs R Us",
          theme: "vibes",
          userAttributes: { planet: "blobine" },
        });
        ```

        <Note>
          The Omni TypeScript SDK utilizes Node's `crypto` module, which is only available in Node environments. Attempting to use Omni TypeScript SDK functions in a client-side context will likely lead to the SDK functions generating improperly signed embed URLs. Always generate embed URLs server-side.
        </Note>

        Every v1 payload carries an expiry. The SDK automatically sets the expiry to 24 hours from the moment the URL is minted. To choose a different lifetime, use the `expiresIn` parameter to define the new lifetime in seconds. The value must be positive and at most seven days (`604800` seconds):

        ```typescript title="Generate a URL that's valid for one hour" wrap highlight={12} theme={null}
        import { embedSsoDashboard } from "@omni-co/embed";

        const iframeUrl = await embedSsoDashboard({
          contentId: "123abc",
          externalId: "blob.ross@blobsrus.com",
          name: "Blob Ross",
          organizationName: "blobsrus",
          secret: process.env.OMNI_EMBED_SECRET,
          entity: "Blobs R Us",
          theme: "vibes",
          userAttributes: { planet: "blobine" },
          expiresIn: 3600,
        });
        ```

        See [URL expiry](/embed/setup/standard-sso/migrate-to-latest#url-expiry) for more information.
      </Tab>

      <Tab title="API" icon="cloud">
        While the TypeScript SDK is the preferred method for generating signed URLs, you may not be able to leverage it if your backend isn't running a JavaScript runtime. For other languages and environments, Omni offers a stateless API as an escape hatch:

        ```text wrap theme={null}
        https://<YOUR OMNI HOSTNAME>/embed/sso/generate-url
        ```

        The `/embed/sso/generate-url` endpoint only accepts `POST` requests. For `POST` operations, parameters are passed as a JSON object in the request body:

        ```bash wrap title="POST /embed/sso/generate-url" theme={null}
        curl -X POST https://blobsrus.omniapp.co/embed/sso/generate-url \
        -H 'Content-Type: application/json' \
        -d '{
          "contentPath": "/dashboards/12345678",
          "externalId": "abcd1234",
          "name": "Blob Ross",
          "secret": "12345678901234567890123456789012",
          "userAttributes": "%7B%22shop_id%22%3A%22123%22%7D"
        }'
        ```

        This endpoint returns a v1 signed URL for an embedded piece of content. Additionally:

        * The endpoint does not accept a signature parameter, as that is what's being generated.
        * The endpoint requires a `secret` parameter in the request body. The value should be the **Embed secret** you created in step 1.
        * The `nonce` parameter is optional. If not included, one will be automatically generated.
        * JSON-encoded parameter values in the request body (`userAttributes`, `connectionRoles`) should be URL encoded. This applies to the request body only - the endpoint handles payload encoding for the URL it returns. Refer to the [Embed parameters reference](/embed/setup/url-parameters) for a complete list of available parameters.
      </Tab>

      <Tab title="Manual" icon="hand">
        <Warning>
          The steps outlined in this section must be followed **exactly** to be successful.
        </Warning>

        Use these steps to generate a v1 signed URL if your backend can't run the TypeScript SDK and you'd rather not call the API:

        <Steps>
          <Step title="Build a JSON object">
            Build a JSON object containing your parameters. The following are required:

            ```markdown theme={null}
            loginUrl      // the full login URL, including scheme and host
            contentPath
            externalId
            name
            nonce
            exp           // expiry, as epoch seconds
            ```

            Any of the [optional parameters](/embed/setup/url-parameters) can be included alongside the above parameters. Omit parameters you aren't setting rather than sending them empty, and note that:

            * **`loginUrl` must exactly match the URL you send the request to.** Omni compares the two after verifying the signature.
            * **`exp` is the absolute expiry in epoch seconds**, following the JWT convention - seconds, not milliseconds. This value must be no more than seven days out. See [URL expiry](/embed/setup/standard-sso/migrate-to-latest#url-expiry) for more information.
            * **JSON-valued parameters are real JSON.** `userAttributes`, `connectionRoles`, `modelRoles`, `customTheme`, and `uiSettings` are objects, and `groups` is an array of strings. Don't stringify them first.
            * **`filterSearchParam` is a URI-encoded query fragment**, because that's what the parameter itself holds.

            For example:

            ```json wrap title="Example parameters" theme={null}
            {
              "loginUrl": "https://blobsrus.embed-omniapp.co/embed/login",
              "contentPath": "/dashboards/123abc",
              "externalId": "luke@example.com",
              "name": "Luke Skywalker",
              "nonce": "hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4",
              "exp": 1787684977,
              "entity": "Acme Corp",
              "theme": "vibes",
              "userAttributes": { "planet": "tatooine" }
            }
            ```
          </Step>

          <Step title="Serialize the object">
            Serialize the object to UTF-8 JSON, compress it with raw DEFLATE ([RFC 1951](https://datatracker.ietf.org/doc/html/rfc1951)), and base64url-encode the result. This encoded string is the `payload` parameter.

            The compression level doesn't matter; neither does the exact byte output of your DEFLATE implementation. Two languages compressing the same parameters will produce different `payload` strings - both are valid. Omni also accepts a zlib-wrapped ([RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)) payload, which is the default output of several standard libraries.

            The encoded `payload` string must be 64KB or smaller. A fully populated payload is well under 2KB, so if you hit this limit, a parameter - usually `userAttributes` - is carrying more than it should.
          </Step>

          <Step title="Sign the payload string">
            Sign the `payload` string - the base64url text itself, not the compressed bytes - using your secret key with an HMAC-SHA256 digest algorithm, encoded as a base64url string. This is the `signature` parameter.

            Padding is optional, and both the `-_` and `+/` alphabets are accepted, so the default output of most languages' base64url helpers will verify as-is. Refer to [the Base64 spec](https://datatracker.ietf.org/doc/html/rfc4648#page-7) for more information about base64url.
          </Step>

          <Step title="Append payload and signature to the login URL">
            Append `payload` and `signature` to the login URL as URL-encoded query parameters. No other parameters are included in the URL; everything else is carried inside the payload.

            ```python wrap expandable title="Python example" theme={null}
            import base64, hashlib, hmac, json, os, time, urllib.parse, zlib

            secret = os.environ["OMNI_EMBED_SECRET"]
            login_url = "https://blobsrus.embed-omniapp.co/embed/login"
            params = {
                "loginUrl": login_url,
                "contentPath": "/dashboards/123abc",
                "externalId": "luke@example.com",
                "name": "Luke Skywalker",
                "nonce": "hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4",
                # Expire in 24 hours. Epoch seconds, at most 7 days out.
                "exp": int(time.time()) + 24 * 60 * 60,
                "entity": "Acme Corp",
                "theme": "vibes",
                "userAttributes": {"planet": "tatooine"},
            }

            # Raw DEFLATE (RFC 1951): a negative wbits omits the zlib wrapper.
            compressor = zlib.compressobj(9, zlib.DEFLATED, -zlib.MAX_WBITS)
            compressed = compressor.compress(json.dumps(params).encode("utf-8"))
            compressed += compressor.flush()

            payload = base64.urlsafe_b64encode(compressed).decode("ascii")
            signature = base64.urlsafe_b64encode(
                hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).digest()
            ).decode("ascii")

            embed_url = login_url + "?" + urllib.parse.urlencode(
                {"payload": payload, "signature": signature}
            )
            ```
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Review the signed embed URL">
    A v1 login URL has the following form, where all parameters are carried inside the `payload` parameter:

    ```text wrap theme={null}
    https://<your-org-name>.embed-omniapp.co/embed/login?payload=<payload>&signature=<signature>
    ```

    For example, this is a signed embed URL for a `blobsrus` organization:

    ```shell wrap theme={null}
    https://blobsrus.embed-omniapp.co/embed/login?payload=HY7BboMwEER_JZozBSWgQn1q2lNamtJWzd02q4AwtmsvSVCUf6_I9Y3mzVxh3LG3v8FAoGP2UWSZMk7FMMWURkXtgxttL71PtcvuILtXkEA7y2S5kdxBIGtl7JSToY3ZepNLpZGALkzBSrNrIWCmgZ7pIkdvKNVuRAIrR4JAPQ20-hnmszQDhYU7q5eg2-fV_sj2sHnJm49d3b1_ffpzPb99N8Xf4VQsE5Z7niGw1SOtXl3wSMAd3cWnXlFEgilS2DKHXk1MEeIKb6QlhgBLdq63hNty10Osy6p8rIqnsrz9Aw&signature=c14FIQAVH7__vgWG5G3IF8_DF5qPSGx4CPFWqeMmfgc&sdk=%40omni-co%2Fembed%401.0.0-next.3
    ```

    <Note>
      SDK-generated URLs also carry an `sdk` parameter identifying the version that produced the URL. It isn't covered by the signature and isn't required - Omni uses it to understand which SDK versions are in use.
    </Note>
  </Step>

  <Step title="Test the URL with the Embed URL Builder">
    <Note>
      This step is optional.
    </Note>

    While the embed URL builder is primarily intended for internal embedding, you can use it to test the format of your [URL parameters](/embed/setup/url-parameters).

    1. First, you'll need your content's unique ID:

       <AccordionGroup>
         <Accordion title="Locate dashboard IDs">
           You can find the dashboard ID by:

           * **Opening the document settings**. Navigate to **File > Document settings** in the dashboard and then click **Settings**. The **Identifier** field contains the dashboard ID.
           * **Using the dashboard's URL**. The string after `/dashboards` is the dashboard's ID; for example:
             ```markdown wrap theme={null}
             https://blobsrus.omniapp.co/dashboards/12db1a0a
             ```
         </Accordion>

         <Accordion title="Locate workbook IDs">
           * **If the workbook is attached to a dashboard**, its content ID is the same as the dashboard
           * **If the workbook doesn't have a dashboard**, you can find the ID by navigating to **File > Document settings**, then clicking **Settings**. The **Identifier** field contains the document ID.

             **Note**: Embedding a workbook creates a copy of the workbook for that embed user so their changes are not reflected back into the application's production version of the workbook.
         </Accordion>
       </AccordionGroup>

    2. Navigate to **Admin > Embed > URL Builder tab**.

    3. Fill in the required fields, noted below:
       * **Content Path**
         * **For dashboards**: `/dashboards/<content_id>`
         * **For workbooks**: `/w/<content_id>`
         * **For apps**: `/apps/<content_id>`
       * **External ID** - Any alphanumeric value
       * **Name** - Any alphanumeric value

    4. Generate your URL and embed!
  </Step>
</Steps>


# Migrating to the v1 embed standard SSO signing format
Source: https://docs.omni.co/embed/setup/standard-sso/migrate-to-latest

Learn what changed in the v1 embed standard SSO signing format and how to update your code from v0.

The v1 signing format replaces the deprecated v0 format. The v0 format will be unsupported after October 1, 2026, and removed by January 1, 2027. Use this page to learn what changed in v1 and what to update in your code.

<Note>
  See the [v1 standard SSO guide](/embed/setup/standard-sso/latest) for step-by-step instructions on setting up standard SSO with the v1 format.
</Note>

## SDK functions

In [`@omni-co/embed`](https://www.npmjs.com/package/@omni-co/embed) v1.0.0 and later, the original function names now produce v1 URLs. The v0 builders are still exported, renamed with a `deprecated` prefix:

| v1 function                | v0 equivalent                        | Generates a URL for      |
| -------------------------- | ------------------------------------ | ------------------------ |
| `embedSsoDashboard`        | `deprecatedEmbedSsoDashboard`        | A dashboard              |
| `embedSsoWorkbook`         | `deprecatedEmbedSsoWorkbook`         | A workbook               |
| `embedSsoApp`              | `deprecatedEmbedSsoApp`              | An app                   |
| `embedSsoContentDiscovery` | `deprecatedEmbedSsoContentDiscovery` | A content discovery page |

Both formats are temporarily accepted at `/embed/login`.

The v1 functions accept the same parameters, with two differences:

* **JSON-valued parameters are passed as objects and arrays instead of pre-stringified strings.** See [JSON-valued parameters](#parameters) for more information.
* **`expiresIn` sets how long the generated URL stays valid.** The `deprecatedEmbedSso*` builders accept and ignore it, because v0 URLs have nowhere to carry an expiry. See [URL expiry](#url-expiry) for more information.

<Warning>
  Upgrading to v1.0.0 without changing your code will change the URLs you generate. Existing calls to `embedSsoDashboard` and its siblings keep working but will produce v1 URLs. Expect the new shape if anything on your side inspects, logs, or reconstructs these URLs.
</Warning>

## JSON-valued parameters

The [v1 SDK functions](#sdk-functions) accept the same parameters they did in v0, but parameters structured as JSON are now passed as objects and arrays instead of pre-stringified strings.

In v0, you needed to stringify and then URL encode parameters with JSON values. For example:

```json wrap v0 parameter example theme={null}
userAttributes=%7B%22country%22%3A%22Townsville%22%7D
```

In v1, you instead pass the JSON as-is:

```json wrap v1 parameter example theme={null}
userAttributes={"country":"Townsville"}
```

## New parameters

### exp (URL expiry)

Every v1 payload carries an `exp` parameter: the absolute moment the URL stops being valid, in epoch seconds, following the JWT convention.

* **If you use the SDK**, the SDK sets `exp` to 24 hours out by default. Use the `expiresIn` parameter to change the lifetime.
* **If you generate URLs manually**, set `exp` yourself as part of the payload. Set it no more than seven days out to match the ceiling the SDK enforces.

Because `exp` is included in the payload, the signature already covers it. There's no separate query parameter, and a URL's expiry can't be changed without re-signing.

When defining URL expiry, keep in mind that shorter expiries are better. Until the embed URL is redeemed, it's a bearer credential - anyone who has it can start the session it describes, and URLs leak through browser history, referer headers, screenshots, and proxy logs. Generate URLs on demand where you can, and only use a longer lifetime when needed, such as a URL that goes out in an email or gets built by a nightly job.

<Note>
  Omni currently requires `exp` to be present, but doesn't yet reject URLs whose expiry has passed. By October 2026, Omni will begin enforcing URL expiry and reject payloads that don't include an `exp` parameter. Migrate your code before then to avoid disruptions.
</Note>

## Removed parameters

The `domain` parameter was removed in v1.0.0. Use `host` instead.

## Next steps

* [Set up embed standard SSO with the v1 signed payload format](/embed/setup/standard-sso/latest)


# Embed standard SSO - Legacy v0 signing format
Source: https://docs.omni.co/embed/setup/standard-sso/v0-legacy

Reference for the deprecated v0 embed URL signing format, in which each parameter is sent as its own URL parameter alongside a signature.

<Warning>
  The v0 format is deprecated. It will be unsupported after October 1, 2026, and removed by January 1, 2027. Use the [v1 signed payload format](/embed/setup/standard-sso/latest) for new integrations, and [migrate existing ones](/embed/setup/standard-sso/migrate-to-latest) before then.
</Warning>

Use this guide as a reference for the legacy v0 embed URL signing format. In the v0 format, each [parameter](/embed/setup/url-parameters) is sent as its own URL query parameter, and the `signature` parameter covers the parameter values concatenated into a single newline-delimited string.

## Parameter encoding

JSON-valued parameters - [`userAttributes`](/embed/setup/url-parameters/userAttributes), [`connectionRoles`](/embed/setup/url-parameters/connectionRoles), [`modelRoles`](/embed/setup/url-parameters/modelRoles), [`customTheme`](/embed/setup/url-parameters/customTheme), [`uiSettings`](/embed/setup/url-parameters/uiSettings), and [`groups`](/embed/setup/url-parameters/groups) - must be stringified and then URL encoded, like every other parameter in the URL.

For example, this JSON-valued parameter:

```json wrap theme={null}
userAttributes={"country":"Townsville"}
```

Must be stringified and then URL encoded:

```markdown wrap theme={null}
userAttributes=%7B%22country%22%3A%22Townsville%22%7D
```

## Manually generate a v0 signed URL

To generate the signature:

<Steps>
  <Step>
    Concatenate the required properties, delimited by a newline character **in the exact order enumerated below**. **Note**: The properties are in alphabetical order, with the exception of the leading login URL:

    ```text theme={null}
    login URL
    contentPath
    externalId
    name
    nonce
    ```
  </Step>

  <Step>
    Concatenate the optional properties in alphabetical order, delimited by a newline character **in the exact order enumerated below**:

    ```markdown highlight={12} theme={null}
    accessBoost
    connectionRoles
    customTheme
    customThemeId
    email
    entity
    entityAiCreditLimit
    entityFolderContentRole
    entityFolderGroupContentRole
    entityFolderLabel
    entityGroupLabel
    filterSearchParam                 // must be URI encoded
    groups
    linkAccess
    mode
    modelRoles
    prefersDark
    preserveEntityFolderContentRole
    theme
    timezone
    uiSettings
    userAttributes
    ```

    **Do not include leading or trailing spaces. Include only a single newline between each part of the signature.**

    The following example includes optional parameters for custom theme, entity, filter search param, prefers dark, link access, theme, and user attributes:

    ```text wrap theme={null}
    https://example.embed-omniapp.co/embed/login
    /dashboards/123abc
    luke@example.com
    Luke Skywalker
    hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
    {"dashboard-background":"#00FF00","dashboard-tile-title-font-size":"1.5rem"}
    Acme Corp
    f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"USA"%5D%2C"is_negative"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%7D&f--inventory_items.cost=%7B"kind"%3A"GREATER_THAN"%2C"type"%3A"number"%2C"values"%3A%5B"20"%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D
    true
    __omni_link_access_open
    vibes
    {"planet": "tatooine"}
    ```

    Refer to the [Embed parameters reference](/embed/setup/url-parameters) for more information about available parameters.
  </Step>

  <Step>
    Sign the string using your secret key with an HMAC sha256 digest algorithm, encoded as a base64url string:

    ```javascript wrap title="Node.js example" theme={null}
    const hmac = crypto.createHmac("sha256", secret);
    hmac.update(data);
    return hmac.digest("base64url");
    ```

    Refer to [the Base64 spec](https://datatracker.ietf.org/doc/html/rfc4648#page-7) for more information about base64url.
  </Step>

  <Step>
    URL encode each parameter as part of a URL query string and attach the generated signature. The order of parameters is irrelevant when generating the login URL.

    ```shell wrap theme={null}
    https://blobsrus.embed-omniapp.co/embed/login?contentPath=%2Fembed%2Fdashboards%2F123abc&externalId=luke%40example.com&name=Luke%20Skywalker&nonce=hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4&entity=Acme+Corp&theme=vibes&userAttributes=%7B%22planet%22%3A%22tatooine%22%7D&filterSearchParam=f--order_items.status%3D%257B%22kind%22%253A%22EQUALS%22%252C%22type%22%253A%22string%22%252C%22topic%22%253A%22order_items%22%252C%22values%22%253A%255B%22Returned%22%255D%252C%22base_view%22%253A%22order_items%22%252C%22is_negative%22%253Afalse%257D&linkAccess=__omni_link_access_open&prefersDark=true&customTheme=%7B%22dashboard-background%22%3A%22%2300FF00%22%2C%22dashboard-tile-title-font-size%22%3A%221.5rem%22%7D&signature=rpf-YbMMTd2XzO_HRyP1E_RiYpQYqBkU-X9iUMplEz4
    ```
  </Step>
</Steps>

## Next steps

* [Setting up embed standard SSO with the v1 signed payload format](/embed/setup/standard-sso/latest)
* [Embed parameters reference](/embed/setup/url-parameters)


# Testing embed URL parameters with the URL builder
Source: https://docs.omni.co/embed/setup/test-urls

Use the embed URL builder to test and generate embed URLs for internal use.

The embed URL builder is a tool within Omni that helps you generate and test embed URLs. While primarily designed for internal embedding scenarios (such as embedding Omni in Notion), you can also use it to validate the format of your [URL parameters](/embed/setup/url-parameters).

## Requirements

To use the embed URL builder, you need:

* **Organization Admin** permissions
* The **Embed** feature enabled in your Omni instance
* An embed secret generated in **Settings > Embed > Admin**

## Using the URL builder

To generate an embed URL using the URL builder:

1. Navigate to **Settings > Embed > URL Builder** in your Omni instance.
2. Fill in the required fields:
   * [Content Path](/embed/setup/url-parameters/contentPath)
   * [External ID](/embed/setup/url-parameters/externalId)
   * [Name](/embed/setup/url-parameters/name)
3. Optionally, fill in any additional [URL parameters](/embed/setup/url-parameters) based on your embedding needs.
4. Click **Generate URL** to create your signed embed URL.
5. Use the generated URL to test your embed configuration.

### Wildcard vanity domains

If your organization has configured a wildcard [vanity domain](/embed/customization/vanity-domains) (e.g., `*.omni.example.com`), the URL builder will display a **Host** field. This field is required when using wildcard domains:

1. Enter a specific hostname that matches your wildcard pattern (e.g., `tenant1.omni.example.com`).
2. The hostname will be validated against your configured wildcard domain pattern.
3. Invalid hostnames that don't match the pattern will be rejected with an error message.

<Note>
  The **Host** field only appears when you have a wildcard vanity domain configured. For standard vanity domains, the host is already specified in your domain configuration.
</Note>

## Next steps

* Learn about all available [URL parameters](/embed/setup/url-parameters)
* Set up [custom vanity domains](/embed/customization/vanity-domains) for your embeds


# Setting up embed with 2-step SSO
Source: https://docs.omni.co/embed/setup/two-step-sso

Set up 2-step SSO for Omni embedding using a POST request to generate a session token, then redeem it via a login URL.

In this guide, we'll walk you through setting up **2-step SSO** for Omni embed. Rather than performing an SSO embed login via a single login URL, the 2-step login flow divides the process into 2 steps:

1. Generate an SSO embed user and session via `POST` request, returning a session token to be redeemed at a later time
2. Redeem the generated session token and redirect to the specified content via a login URL

<Tip>
  While the standard SSO embed experience is more straightforward, there a few reasons you might opt to use the 2-step SSO embed login flow over standard login URLs:

  * **Sensitive user data**: If using the `userAttributes` parameter with sensitive user data, you may prefer creating SSO embed users and sessions via `POST` request for added security.
  * **URL length**: While generally unlikely, there is more risk of standard SSO embed URLs exceeding a browser's URL character limit. 2-step login URLs are more compact and thus have no risk of hitting the limit.
</Tip>

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin** permissions
* To have the **Embed** feature enabled in your Omni instance

<Steps>
  <Step title="Generate an embed secret">
    1. Navigate to **Settings > Embed > Admin** in your Omni instance.
    2. Click the **Add Secret** button below the secrets table.
    3. In the dialog that appears:
       * A 32-character secret key is automatically generated for you
       * Enter a descriptive **Name** to identify the secret's purpose (e.g., "Production", "Staging", or "Partner Integration")

         <Tip>
           Use descriptive names for your secrets to make them easier to identify and manage, especially when rotating secrets or managing multiple environments.
         </Tip>
    4. Click **Add secret** to save the new secret.
  </Step>

  <Step title="Customize session length">
    <Note>
      This step is optional.
    </Note>

    In the **Embed** settings of your Omni instance, you can also customize the length of embed sessions using the **Session Length** setting. In this field, enter the number of hours you want sessions to last and click **Change**.
  </Step>

  <Step title="Generate an Omni API key">
    As with all other API endpoints, an `Authorization` header with an Omni API key as a `Bearer` token is necessary for authentication purposes. Refer to the [API docs](/api/authentication) for more information.
  </Step>

  <Step title="Generate the user and session">
    <Tip>
      You can also use the `createSessionToken` function in the [TypeScript SDK](https://www.npmjs.com/package/@omni-co/embed) to complete this step.
    </Tip>

    In this step, you'll generate the embed user and session. This is done by sending a `POST` request to the `/api/unstable/embed/sso/generate-session` endpoint. This will return a token that will be redeemed later.

    Most parameters listed in the [Embed parameters reference](/embed/setup/url-parameters) can be passed in the JSON body of the request. The only exceptions are:

    * [`theme`](/embed/setup/url-parameters/theme) and [`prefersDark`](/embed/setup/url-parameters/prefersDark), which can be set via URL parameters in the login URL, and
    * [`nonce`](/embed/setup/url-parameters/nonce), which isn't necessary at this step

    Like the standard SSO login flow, [`contentPath`](/embed/setup/url-parameters/contentPath), [`externalId`](/embed/setup/url-parameters/externalId), and [`name`](/embed/setup/url-parameters/name) are required.

    ```json wrap title="POST /api/unstable/embed/sso/generate-session" theme={null}
    curl -X POST 'https://test.blobsrus.com/api/unstable/embed/sso/generate-session' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{
      "contentPath": "/my",
      "externalId": "artiste1322",
      "name": "Blob Ross",
      "connectionRoles": {
        "abcd1234-abcd-efgh-ijkl-abcdef123456": "RESTRICTED_QUERIER"
      },
      "entity": "Happy Trees",
      "entityFolderContentRole": "EDITOR"
    }'
    ```

    Once a successful request is made, a few things will happen:

    * The endpoint will return a JSON payload with a single `sessionId` property. This `sessionId` will be used in the next step during session redemption.
    * An embed user will be upserted into your organization based on the request body's values.
    * An embed session will be created for this embed user with a 5 minute expiry. For security purposes, if the session isn't redeemed within 5 minutes of creation, the session will no longer be usable.
  </Step>

  <Step title="Generate the session redemption signature">
    <Note>
      If using the TypeScript SDK `redeemSessionToken` function, the signature will be automatically generated and included in the returned session redemption URL. This works the same on every SDK version - the [v1 signed payload format](/embed/setup/standard-sso/latest) applies only to standard SSO login URLs, not session redemption.
    </Note>

    Signatures are generated using the request URL and URL parameters. To generate the signature, the following steps must be followed exactly:

    1. Concatenate the required properties, delimited by a newline character in the exact order enumerated below. **Note**: The parameters are in alphabetical order, with the exception of the leading login URL:

       ```markdown theme={null}
       login URL
       nonce
       sessionId
       ```
    2. Concatenate the optional properties in alphabetical order, delimited by a newline character. **Omit any undefined properties**.

       ```markdown theme={null}
       prefersDark
       theme
       ```

       **Do not include leading or trailing spaces. Include only a single newline between each part of the signature.**

       The following example includes optional parameters for custom theme, entity, filter search param, prefers dark, link access, theme, and user attributes:

       ```shell wrap theme={null}
       https://example.embed-omniapp.co/embed/sso/redeem-session
       XxDcs01bnenbOyJTNAAUHheXRVFTVDOA
       abcd1234-abcd-efgh-ijkl-abcdef123456
       false
       vibes
       ```
    3. Sign the string using the **Embed secret** you created in step 1 with an HMAC sha256 digest algorithm, encoded as a base64url string. Refer to [this standard](https://datatracker.ietf.org/doc/html/rfc4648#page-7) for more information about base64url.

       ```javascript wrap title="Node.js example" theme={null}
       const hmac = crypto.createHmac("sha256", secret);
       hmac.update(data);
       return hmac.digest("base64url");
       ```
  </Step>

  <Step title="Redeem the session">
    <Tip>
      You can also use the `redeemSessionToken` function in the [TypeScript SDK](https://www.npmjs.com/package/@omni-co/embed) to complete this step.
    </Tip>

    With the `sessionId`, you can now create a 2-step session redemption URL. Like standard SSO embed login URLs, session redemption URLs should be passed into the `src` attribute of an `iframe` HTML element.

    In addition, 2-step SSO embed login URLs must be signed using the request host, a nonce, and other [URL parameters](/embed/setup/url-parameters). You'll use the signature you generated in the previous step to sign the embed login URL.

    * **Required URL parameters**:

      * Session ID (`sessionId`)
      * Nonce ([`nonce`](/embed/setup/url-parameters/nonce))
      * Signature (`signature`)

    * **Optional URL parameters**:

      * Prefers dark ([`prefersDark`](/embed/setup/url-parameters/prefersDark))
      * Theme ([`theme`](/embed/setup/url-parameters/theme))

    ```shell wrap title="Example URL" theme={null}
    https://test.embed-blobsrus.com/embed/sso/redeem-session?prefersDark=false&theme=vibes&nonce=XxDcs01bnenbOyJTNAAUHheXRVFTVDOA&sessionId=abcd1234-abcd-efgh-ijkl-abcdef123456&signature=7Gk9LmN2oP3QrStUvWxYzA1BcDeFgHiJkLmNoPqRsTu
    ```

    Once the URL is passed into an `iframe` and a successful session redemption request is made, the following will happen:

    * The associated embed session will update its expiry from 5 minutes to **24 hours**, or to the custom **Session Length** specified in the **Admin > Embed** section of your Omni organization.
    * The iframe will redirect to the [`contentPath`](/embed/setup/url-parameters/contentPath) specified during session generation.
  </Step>
</Steps>


# accessBoost
Source: https://docs.omni.co/embed/setup/url-parameters/accessBoost

Enables AccessBoost for the embedded dashboard.

If `true`, [AccessBoost](/share#access-warnings) will be enabled for the embedded dashboard.

In the **Embed URL Builder**, this is the **Access Boost** field.

## Requirements

Embed users can provision AccessBoost when both of the following organization settings are enabled:

* **AccessBoost** is enabled in **Settings > Content permissions**
* **Non-administrators can enable AccessBoost on content** is enabled in **Settings > Content permissions**

## Syntax

```markdown theme={null}
accessBoost=<boolean>
```

## Properties

<ParamField type="boolean">
  Set to `true` to enable AccessBoost, or `false` to disable it.
</ParamField>

## Examples

```markdown title="Enable AccessBoost" theme={null}
accessBoost=true
```


# connectionRoles
Source: https://docs.omni.co/embed/setup/url-parameters/connectionRoles

Specifies the level of access users will have to all models associated with a connection.

<Note>
  This parameter is not required to create valid embed requests, but Omni recommends setting it.
</Note>

An object of connection roles available for embed users, used to specify the level of access users will have to all models associated with the connection. To specify permissions for individual models, use the [`modelRoles`](/embed/setup/url-parameters/modelRoles) parameter.

## Syntax

```json theme={null}
connectionRoles={"<connection_id>":"<connection_role>", ...}
```

## Properties

<ParamField type="object">
  An object containing connection ID and role pairs, formatted as `"<connection_id>": "<connection_role>"`. `connection_role` values must be the name of a standard user role **or** the name of a [custom user role](/administration/users/custom-roles) that resolves to either a **Viewer** or **Restricted Querier**.

  * `RESTRICTED_QUERIER` - Can create new content and view workbooks and dashboards
  * `VIEWER` - Can only view dashboards
  * `<CUSTOM_ROLE_NAME>` - Abilities depend on the role's included permissions

  <Warning>
    Base access roles are not respected. Connection roles should be specified using this parameter or by setting group permissions on the connection in Omni and then assigning embed users to those [groups](/embed/setup/url-parameters/groups).
  </Warning>
</ParamField>

## Behavior

When a user creates an embed session, the `connectionRoles` value on the latest request acts as the source of truth for that user's connection access. This means:

* A role can be **downgraded** by a later request (e.g. from **Restricted Querier** to **Viewer**).
* A role can be **removed** entirely if the later request doesn't mention the connection — either explicitly in `connectionRoles` or implicitly in the connection backing the requested [`contentPath`](/embed/setup/url-parameters/contentPath).

To avoid unintentionally changing a user's access, include `connectionRoles` on every request.

## Examples

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    connectionRoles={"65b10d2a-473b-4486-92c8-0ba628c7d1cb":"RESTRICTED_QUERIER"}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    connectionRoles=%7B%2265b10d2a-473b-4486-92c8-0ba628c7d1cb%22%3A%22RESTRICTED_QUERIER%22%7D
    ```
  </Tab>
</Tabs>


# contentPath
Source: https://docs.omni.co/embed/setup/url-parameters/contentPath

Defines the starting page when the embed user logs into the iframe.

<Note>
  This parameter is **required** to create valid embed requests.
</Note>

In the **Embed URL Builder**, this is the **Content path** field.

## Syntax

```markdown theme={null}
contentPath=<encoded_path>
```

## Properties

<ParamField type="string">
  The URL-encoded path to the starting page. Click the following toggles to view examples for each of the pages you can use as a starting page.

  <Note>
    If the starting content path is a dashboard or app path, Omni provides a 24 hour `VIEWER` content permit to that content for that user.
  </Note>

  <AccordionGroup>
    <Accordion title="/dashboards/<dashboard-id>" description="Starts at a specified dashboard">
      ```markdown title="/dashboards/<dashboard-id>" theme={null}
      contentPath=%2Fdashboards%2Fa6908f35
      ```

      <img alt="" />
    </Accordion>

    <Accordion title="/apps/<app-id>" description="Starts at an app">
      Refer to [Embedding apps](/visualize-present/apps#embedding-apps) for details.

      ```markdown title="/apps/<app-id>" theme={null}
      contentPath=%2Fapps%2Fa6908f35
      ```
    </Accordion>

    <Accordion title="/w/<dashboard-id>/duplicate" description="Starts at a workbook">
      ```markdown title="/w/<dashboard-id>/duplicate" theme={null}
       contentPath=%2Fw%2Fa6908f35%2Fduplicate
      ```

      <img alt="" />
    </Accordion>

    <Accordion title="/apps/<app-id>" description="Starts at an app">
      ```markdown title="/apps/<app-id>" theme={null}
      contentPath=%2Fapps%2Fa6908f35
      ```
    </Accordion>

    <Accordion title="/chat" description="Starts at AI chat">
      In this example, a [`connectionRoles`](/embed/setup/url-parameters/connectionRoles) parameter was also provided to associate the chat with a specific connection (`MD2`) and its models:

      <img alt="" />
    </Accordion>

    <Accordion title="/my" description="Starts at the user's My Documents folder">
      ```markdown title="/my" theme={null}
       contentPath=%2Fmy
      ```

      <img alt="" />
    </Accordion>

    <Accordion title="/entity-folder" description="Starts at the folder associated with the user's entity">
      An `entity` parameter is required when `/entity-folder` is used as the `contentPath`.

      By default, the `entity` value will be used to create the entity folder. To provide a different name for the folder, use the [`entityFolderLabel`](/embed/setup/url-parameters/entityFolderLabel) parameter.

      <img alt="" />
    </Accordion>

    <Accordion title="/root" description="Starts at the Hub">
      <img alt="" />
    </Accordion>
  </AccordionGroup>
</ParamField>

## Examples

```markdown title="Dashboard path" theme={null}
contentPath=%2Fdashboards%2Fa6908f35
```

```markdown title="Workbook path" theme={null}
contentPath=%2Fw%2Fa6908f35%2Fduplicate
```

```markdown title="App path" theme={null}
contentPath=%2Fapps%2Fa6908f35
```

```markdown title="My Documents path" theme={null}
contentPath=%2Fmy
```


# customTheme
Source: https://docs.omni.co/embed/setup/url-parameters/customTheme

Defines custom theme properties for styling embedded dashboards.

Defines custom theme properties for styling embedded dashboards.

In the **Embed URL Builder**, this is the **Custom theme** field.

## Syntax

```json wrap theme={null}
customTheme={"<theme_property_1>":"<value>", "<theme_property_2>":"<value>"...}
```

## Properties

<ParamField type="object">
  An object containing theme properties and their values. Values must be a valid [theme property](/embed/customization/themes).
</ParamField>

## Examples

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    customTheme={"dashboard-background":"blue"}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    customTheme=%7B%22dashboard-background%22%3A%22blue%22%7D
    ```
  </Tab>
</Tabs>


# customThemeId
Source: https://docs.omni.co/embed/setup/url-parameters/customThemeId

Specifies the custom theme to use in the resulting embed session. Used to apply your own custom styles.

<Tip>
  To use a default Omni theme, use the [`theme`](/embed/setup/url-parameters/theme).
</Tip>

In the **Embed URL Builder**, this is the **Custom theme ID** field.

## Syntax

```markdown theme={null}
customThemeId=<theme_id>
```

## Properties

<ParamField type="string">
  A valid theme ID from your Omni instance.
</ParamField>

## Examples

```markdown wrap title="Example customThemeId" theme={null}
customThemeId=abcdefgh-ijkl-mnop-qrst-123456789123
```


# email
Source: https://docs.omni.co/embed/setup/url-parameters/email

Populates the from email for entity users when sharing content or sending deliveries.

In the **Embed URL Builder**, this is the **Email** field.

## Syntax

```markdown theme={null}
email=<encoded_email>
```

## Properties

<ParamField type="string">
  A valid email address for the embed user.
</ParamField>

## Examples

```markdown title="Example email" theme={null}
email=blobby17%40blobsrus.com
```

## Effect on email-only users

When this parameter is set, Omni checks for any existing [email-only users](/administration/users/email-only) with a matching email. If a match is found, Omni automatically transfers the email-only user's schedule recipients to the embed user and removes the email-only membership. This happens on embed login.

After the merge, [personalized deliveries](/share/deliveries/email#email-settings) use the embed user's attributes instead of the email-only user's defaults — which is important when [access filters](/modeling/topics/parameters/access-filters) are in use.

Set this parameter for any embed user who is also a delivery recipient. Without it, Omni creates a separate email-only user for that address with default attribute values.


# entity
Source: https://docs.omni.co/embed/setup/url-parameters/entity

Defines a user group identifier used to associate the resulting embed user with a larger group.

This parameter also creates the shared entity folder, using the name set in the value. Entity name has a 64 character limit.

In the **Embed URL Builder**, this is the **Embed entity** field.

## Syntax

```markdown theme={null}
entity=<entity_name>
```

## Properties

<ParamField type="string">
  An alphanumeric identifier for the user group.
</ParamField>

## Examples

```markdown title="Example entity" theme={null}
entity=Blobs+R+Us
```


# entityAiCreditLimit
Source: https://docs.omni.co/embed/setup/url-parameters/entityAiCreditLimit

Sets an AI credit limit for the embed user's entity group at login.

Sets an AI credit limit for the embed user's entity group at login.

## Requirements

An [`entity`](/embed/setup/url-parameters/entity) parameter must be provided in the generated URL for this parameter to have an effect. If `entityAiCreditLimit` is provided without an `entity`, the login will fail with a missing-entity error.

## Syntax

```markdown theme={null}
entityAiCreditLimit=<value>
```

## Properties

<ParamField type="number | string">
  Sets an AI credit limit for the entity group at login. Accepted values:

  * A whole number to set a credit cap (e.g., `40`)
  * The string `"unlimited"` to explicitly remove any credit cap
  * Omit the parameter to remove the override and fall back to the [organization's embed entity group default](/embed/admin/ai-credits#embed-entity-default)
</ParamField>

## Examples

<Tabs>
  <Tab title="Set a credit limit">
    Set `entityAiCreditLimit` to a number to cap the entity group's AI credit usage:

    ```markdown theme={null}
    entityAiCreditLimit=50
    ```
  </Tab>

  <Tab title="Unlimited credits">
    Set `entityAiCreditLimit` to `unlimited` to allow the entity group to use unlimited credits:

    ```markdown theme={null}
    entityAiCreditLimit=unlimited
    ```
  </Tab>

  <Tab title="Remove credit limit">
    To remove an entity group's credit limit override, omit the `entityAiCreditLimit` parameter from the embed URL. This will remove the group-specific setting and apply the [organization's embed entity group default](/embed/admin/ai-credits#embed-entity-default) instead.
  </Tab>
</Tabs>

## Next steps

* [Managing AI credits for embed entity groups](/embed/admin/ai-credits) — Learn about entity group credit limits, defaults, and monitoring
* [Managing AI credit usage](/ai/settings/usage) - Learn about organization and user-level credit limits defaults


# entityFolderContentRole
Source: https://docs.omni.co/embed/setup/url-parameters/entityFolderContentRole

Specifies the content role the embed user will be given to their shared entity folder.

In the **Embed URL Builder**, this is the **Entity folder content role** field.

## Syntax

```markdown theme={null}
entityFolderContentRole=<role>
```

## Properties

<ParamField type="string">
  The content role for the user. Value must be one of:

  * `VIEWER` - Can see content in the shared folder, but cannot save content into it
  * `EDITOR` - Can see and save content into the shared folder
  * `MANAGER` - Can see and save content into the shared folder and manage other users' permissions
  * `NO_ACCESS` - Cannot see content in the top-level shared folder. **Note**: It is still possible for the group to have access to subfolders by assigning content permits directly in the UI.
</ParamField>

## Examples

```markdown title="Example entityFolderContentRole" theme={null}
entityFolderContentRole=EDITOR
```


# entityFolderGroupContentRole
Source: https://docs.omni.co/embed/setup/url-parameters/entityFolderGroupContentRole

Specifies the content role the embed entity group will be given to their shared entity folder.

If unspecified, an entity group will have `VIEWER` access to their shared entity folder.

In the **Embed URL Builder**, this is the **Entity folder group content role** field.

## Syntax

```markdown theme={null}
entityFolderGroupContentRole=<role>
```

## Properties

<ParamField type="string">
  The content role for the entity group. Value must be one of:

  * `VIEWER` - Can see content in the shared folder, but cannot save content into it
  * `EDITOR` - Can see and save content into the shared folder
  * `MANAGER` - Can see and save content into the shared folder and manage other users' permissions
  * `NO_ACCESS` - Cannot see content in the top-level shared folder. Note that it is still possible for the group to have access to subfolders by assigning content permits directly in the UI.
</ParamField>

## Examples

```markdown title="Example entityFolderGroupContentRole" theme={null}
entityFolderGroupContentRole=MANAGER
```


# entityFolderLabel
Source: https://docs.omni.co/embed/setup/url-parameters/entityFolderLabel

Updates the embed user's associated entity folder label.

In the **Embed URL Builder**, this is the **Entity folder label** field.

## Requirements

An [`entity`](/embed/setup/url-parameters/entity) must be provided in the generated URL for this parameter to have an effect.

## Syntax

```markdown theme={null}
entityFolderLabel=<label>
```

## Properties

<ParamField type="string">
  A label for the entity folder. Maximum 64 characters.
</ParamField>

## Examples

```markdown title="Example entityFolderLabel" theme={null}
entityFolderLabel=Blob+Sales
```


# entityGroupLabel
Source: https://docs.omni.co/embed/setup/url-parameters/entityGroupLabel

Updates the embed user's associated entity group label.

In the **Embed URL Builder**, this is the **Entity group label** field.

## Requirements

An [`entity`](/embed/setup/url-parameters/entity) must be provided in the generated URL for this parameter to have an effect.

## Syntax

```markdown theme={null}
entityGroupLabel=<label>
```

## Properties

<ParamField type="string">
  A label for the entity group. Maximum 64 characters.
</ParamField>

## Examples

```markdown title="Group label of Blob Sales" theme={null}
entityGroupLabel=Blob+Sales
```


# externalId
Source: https://docs.omni.co/embed/setup/url-parameters/externalId

Creates a unique ID for the embed user.

<Note>
  This parameter is **required** to create valid embed requests.
</Note>

In the **Embed URL Builder**, this is the **External ID** field.

## Syntax

```markdown theme={null}
externalId=<unique_id>
```

## Properties

<ParamField type="string">
  A unique alphanumeric identifier for the embed user.
</ParamField>

## Examples

```markdown title="Example externalId" theme={null}
externalId=ohtani17
```


# filterSearchParam
Source: https://docs.omni.co/embed/setup/url-parameters/filterSearchParam

Specifies the filters to apply for the embedded content.

Specifies the filters to apply for the embedded content.

In the **Embed URL Builder**, this is the **Filter search param** field.

## Syntax

```json theme={null}
filterSearchParam=f--<filter_id>={"values":["value1","value2", ...]}
```

## Properties

<ParamField type="string">
  An object containing a filter specification for the embedded content. Filter specifications are formatted as follows:

  ```json theme={null}
  f--<filter_id>={"values":["value1","value2", ...]}
  ```

  <Tip>
    You can retrieve values for this parameter by using Omni in a non-embedded context. Navigate to a dashboard with filters and change the filter values. The URL will change when new filter values are applied - use what's in the URL as the value for this parameter.
  </Tip>
</ParamField>

## Examples

<Note>
  Unlike JSON-valued parameters, `filterSearchParam` holds a URI-encoded query fragment in both [signing formats](/embed/setup/standard-sso). In the[ v1 signed payload format](/embed/setup/standard-sso/latest), use the encoded string as the parameter's value inside the payload.
</Note>

The following example demonstrates what the URL encoded version of `f--rW8-IWVU={"values":["closed"]}` would be:

```markdown title="Example filter" theme={null}
filterSearchParam=f--rW8-IWVU=%7B%22values%22%3A%5B%22closed%22%5D%7D
```


# groups
Source: https://docs.omni.co/embed/setup/url-parameters/groups

Associates the resulting embed user with existing user groups in your Omni instance.

Associates the resulting embed user with existing user groups in your Omni instance.

In the **Embed URL Builder**, this is the **Groups** field.

## Syntax

```markdown theme={null}
groups=["<group_1>", "<group_2>", ...]
```

## Properties

<ParamField type="array">
  An array of user group names that exist in your Omni instance.
</ParamField>

## Examples

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    groups=["Blob Sales","Blob Marketing"]
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    groups=%5B%22Blob+Sales%22%2C%22Blob+Marketing%22%5D
    ```
  </Tab>
</Tabs>


# Embed URL parameters reference
Source: https://docs.omni.co/embed/setup/url-parameters/index

Create and customize user sessions by including URL parameters in your embed requests.

For example, you can use embed URL parameters to:

* Specify user content roles
* Assign connection and model roles to users
* Control the look and theme of your embedded application
* Apply user attributes to users

<Note>
  How these parameters are included in an embed URL depends on its [signing format](/embed/setup/standard-sso). In the [v1 signed payload format](/embed/setup/standard-sso/migrate-to-latest), all parameters are carried inside a single `payload` parameter, and JSON-valued parameters such as `userAttributes` stay as JSON instead of being stringified and URL encoded. In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), each parameter is sent as its own URL parameter.

  A v1 payload also carries an `exp` expiry that isn't listed below as it isn't something you set per session in the same way. See [URL expiry](/embed/setup/standard-sso/migrate-to-latest#url-expiry) for more information.
</Note>

## Required parameters

At a minimum, valid embed requests must contain all of the following parameters:

| Parameter                                              | Description                                                         |
| ------------------------------------------------------ | ------------------------------------------------------------------- |
| [contentPath](/embed/setup/url-parameters/contentPath) | Defines the starting page when the embed user logs into the iframe. |
| [externalId](/embed/setup/url-parameters/externalId)   | Creates a unique ID for the embed user.                             |
| [name](/embed/setup/url-parameters/name)               | Defines a non-unique name for the embed user's name property.       |
| [nonce](/embed/setup/url-parameters/nonce)             | A unique 32-character string that defines the embed login URL.      |

## Recommended parameters

The following parameters are strongly recommended, but not required, in embed requests.

| Parameter                                                      | Description                                                                               |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [connectionRoles](/embed/setup/url-parameters/connectionRoles) | Specifies the level of access users will have to all models associated with a connection. |

## Optional parameters

The following parameters are optional in embed requests.

| Parameter                                                                                      | Description                                                                                     |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [accessBoost](/embed/setup/url-parameters/accessBoost)                                         | Enables AccessBoost for the embedded dashboard.                                                 |
| [customTheme](/embed/setup/url-parameters/customTheme)                                         | Defines custom theme properties for styling embedded dashboards.                                |
| [customThemeId](/embed/setup/url-parameters/customThemeId)                                     | Defines a theme ID from your Omni instance to stylize embedded dashboards.                      |
| [email](/embed/setup/url-parameters/email)                                                     | Populates the from email for entity users when sharing content or sending deliveries.           |
| [entity](/embed/setup/url-parameters/entity)                                                   | Defines a user group identifier used to associate the resulting embed user with a larger group. |
| [entityAiCreditLimit](/embed/setup/url-parameters/entityAiCreditLimit)                         | Sets an AI credit limit for the embed user's entity group at login.                             |
| [entityFolderContentRole](/embed/setup/url-parameters/entityFolderContentRole)                 | Specifies the content role the embed user will be given to their shared entity folder.          |
| [entityFolderGroupContentRole](/embed/setup/url-parameters/entityFolderGroupContentRole)       | Specifies the content role the embed entity group will be given to their shared entity folder.  |
| [entityFolderLabel](/embed/setup/url-parameters/entityFolderLabel)                             | Updates the embed user's associated entity folder label.                                        |
| [entityGroupLabel](/embed/setup/url-parameters/entityGroupLabel)                               | Updates the embed user's associated entity group label.                                         |
| [filterSearchParam](/embed/setup/url-parameters/filterSearchParam)                             | Specifies the filters to apply for the embedded content.                                        |
| [groups](/embed/setup/url-parameters/groups)                                                   | Associates the resulting embed user with existing user groups in your Omni instance.            |
| [linkAccess](/embed/setup/url-parameters/linkAccess)                                           | Controls which Omni dashboards can be linked to from the embedded dashboard.                    |
| [mode](/embed/setup/url-parameters/mode)                                                       | Defines the type of access users will have to Omni in the iframe.                               |
| [modelRoles](/embed/setup/url-parameters/modelRoles)                                           | Defines the level of access users will have for individual models in a connection.              |
| [prefersDark](/embed/setup/url-parameters/prefersDark)                                         | Controls whether the resulting embed session has a light or dark mode appearance.               |
| [preserveEntityFolderContentRole](/embed/setup/url-parameters/preserveEntityFolderContentRole) | Retains the embed user's existing entity folder content role.                                   |
| [theme](/embed/setup/url-parameters/theme)                                                     | Customizes the styles of the resulting embed session with a built-in Omni application theme.    |
| [timezone](/embed/setup/url-parameters/timezone)                                               | Specifies a timezone override for query execution in the embedded session.                      |
| [uiSettings](/embed/setup/url-parameters/uiSettings)                                           | Controls general settings of the application in embed.                                          |
| [userAttributes](/embed/setup/url-parameters/userAttributes)                                   | Applies user attributes to the embed user.                                                      |


# linkAccess
Source: https://docs.omni.co/embed/setup/url-parameters/linkAccess

Controls which Omni dashboards can be linked to from the embedded dashboard.

In the **Embed URL Builder**, this is the **Link access** field.

## Syntax

```markdown theme={null}
linkAccess=<access_value>
```

## Properties

<ParamField type="string">
  Controls dashboard linking permissions. Value must be one of:

  * `__omni_link_access_open` - All links on the embedded dashboard are permissed and shown. **Use this option when using Markdown.**
  * `<list_of_dashboard_ids>` - Only permit specific dashboards to be shown
  * **Leave blank** to restrict all links to other Omni dashboards. **Note**: Links to anything other than an Omni dashboard will be shown regardless of the values specified in this parameter.
</ParamField>

## Examples

```markdown title="Show all links on embedded dashboard" theme={null}
linkAccess=__omni_link_access_open
```


# mode
Source: https://docs.omni.co/embed/setup/url-parameters/mode

Defines the type of access users will have to Omni in the iframe.

In the **Embed URL Builder**, this is the **Mode** field.

## Syntax

```markdown theme={null}
mode=<access_mode>
```

## Properties

<ParamField type="string">
  The access mode for the embed session. Value must be one of:

  * `APPLICATION` - Enables [Create Mode](/embed/customization/create-mode). Allows embed users to access the full content system and navigate through the Omni app in an iframe.
  * `SINGLE_CONTENT` - Only embeds an individual dashboard, workbook, or [app](/visualize-present/apps). No content navigation or app headers.

  <Note>
    When using `SINGLE_CONTENT` mode, [the chat](/ai/dashboard-assistant) opens in an inline panel rather than the split-view interface. This keeps users scoped to the embedded content and prevents navigation away from the single-content frame.
  </Note>

  <Warning>
    Avoid generating `SINGLE_CONTENT` and `APPLICATION` mode sessions for the same user at the same time. Omni expects all concurrent embed sessions for a given user to share a single mode, and mixing modes can result in inconsistent behavior. If your implementation requires both `SINGLE_CONTENT` and `APPLICATION` mode sessions to be active simultaneously, assign unique external IDs to each session to prevent session collisions.
  </Warning>
</ParamField>

## Examples

```markdown title="Enable Create Mode" theme={null}
mode=APPLICATION
```


# modelRoles
Source: https://docs.omni.co/embed/setup/url-parameters/modelRoles

Defines the level of access users will have for individual models in a connection.

Defines the level of access users will have for individual models in a connection.

In the **Embed URL Builder**, this is the **Model roles** field.

## Syntax

```markdown theme={null}
connectionRoles={"<connection_id>":"<connection_role>", ...}
```

## Properties

<ParamField type="object">
  An object containing model ID and role pairs, formatted as `"<model_id>: <model_role>"`. `model_role` values must the name of a standard user role **or** the name of a [custom user role](/administration/users/custom-roles) that resolves to either a **Viewer** or **Restricted Querier**.

  * `RESTRICTED_QUERIER` - Can create new content and view workbooks and dashboards based on the specified model
  * `VIEWER` - Can only view dashboards based on the specified model
  * `<CUSTOM_ROLE_NAME>` - Abilities depend on the role's included permissions

  <Note>
    Model roles must be equal to or more permissive than the associated [connection's base access role](/embed/setup/url-parameters/connectionRoles). For example, if the connection has a base access role of `RESTRICTED_QUERIER`, it will override a model with a `VIEWER` role.
  </Note>
</ParamField>

## Examples

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    modelRoles={"65b10d2a-473b-4486-92c8-0ba628c7d1cb":"RESTRICTED_QUERIER"}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    modelRoles=%7B%2265b10d2a-473b-4486-92c8-0ba628c7d1cb%22%3A%22RESTRICTED_QUERIER%22%7D
    ```
  </Tab>
</Tabs>


# name
Source: https://docs.omni.co/embed/setup/url-parameters/name

Defines a non-unique name for the embed user's name property.

<Note>
  This parameter is **required** to create valid embed requests.
</Note>

In the **Embed URL Builder**, this is the **Name** field.

## Syntax

```markdown theme={null}
name=<user_name>
```

## Properties

<ParamField type="string">
  The display name for the embed user.
</ParamField>

## Examples

```markdown title="Example name" theme={null}
name=Blob+Ross
```


# nonce
Source: https://docs.omni.co/embed/setup/url-parameters/nonce

A unique 32-character string that defines the embed login URL.

<Note>
  This parameter is **required** to create valid embed requests.
</Note>

This must be unique or the session will fail to load.

In the **Embed URL Builder**, this is the **Nonce** field.

<Tip>
  If using the SDK or `/embed/sso/generate-url` endpoint, `nonce` will be automatically added to the generated URLs if one is not provided.
</Tip>

## Syntax

```markdown theme={null}
nonce=<32_character_string>
```

## Properties

<ParamField type="string">
  A unique 32-character alphanumeric string.
</ParamField>

## Examples

```markdown title="Example nonce" theme={null}
nonce=abcdefghijklmnopqrstuvwxyz123456
```


# prefersDark
Source: https://docs.omni.co/embed/setup/url-parameters/prefersDark

Controls whether the resulting embed session has a light or dark mode appearance.

In the **Embed URL Builder**, this is the **Prefers dark** field.

## Syntax

```markdown theme={null}
prefersDark=<mode>
```

## Properties

<ParamField type="string">
  The appearance mode for the embed session. Value must be one of:

  * `true` - Enables dark mode
  * `false` - Enables light mode
  * `system` - Appearance uses system setting
</ParamField>

## Examples

```markdown title="Example prefersDark" theme={null}
prefersDark=false
```


# preserveEntityFolderContentRole
Source: https://docs.omni.co/embed/setup/url-parameters/preserveEntityFolderContentRole

Retains the embed user's existing entity folder content role.

If `true`, the embed user's existing entity folder content role is retained from the previous session. For example, if a user is promoted from `VIEWER` to `EDITOR` in one session, the next time they log in they will retain the `EDITOR` role instead of becoming a `VIEWER` again.

If set to `false` or not provided, Omni will use the latest embed login URL to determine the correct content role.

In the **Embed URL Builder**, this is the **Preserve entity folder content role** field.

## Syntax

```markdown theme={null}
preserveEntityFolderContentRole=<boolean>
```

## Properties

<ParamField type="boolean">
  Set to `true` to preserve the existing role, or `false` to use the role specified in the current URL.
</ParamField>

## Examples

```markdown title="Example preserveEntityFolderContentRole" theme={null}
preserveEntityFolderContentRole=true
```


# theme
Source: https://docs.omni.co/embed/setup/url-parameters/theme

Customizes the styles of the resulting embed session with a built-in Omni application theme.

<Tip>
  To use your own theme, use the [`customThemeId`](/embed/setup/url-parameters/customThemeId).
</Tip>

In the **Embed URL Builder**, this is the **Built-in theme** field.

## Syntax

```markdown theme={null}
theme=<theme_name>
```

## Properties

<ParamField type="string">
  The name of a built-in Omni theme. Value must be one of:

  * `vibes`
  * `dawn`
  * `breeze`
  * `blank`
</ParamField>

## Examples

```markdown title="Use vibes theme" theme={null}
theme=vibes
```


# timezone
Source: https://docs.omni.co/embed/setup/url-parameters/timezone

Specifies a timezone override for query execution in the embedded session.

In the **Embed URL Builder**, this is the **Timezone** field.

<Note>
  This parameter is URL-only and does not persist to the embed user's `omni_user_timezone` attribute. To persist the timezone attribute for a user, use the [`userAttributes`](/embed/setup/url-parameters/userAttributes) field instead.

  This parameter works the same way as the per-page timezone override feature in Omni. For more information about timezone conversion precedence, see [Timezones](/connect-data/timezones).
</Note>

## Syntax

```markdown theme={null}
timezone=<IANA_timezone>
```

## Properties

<ParamField type="string">
  The timezone to use for query execution. Value must be a valid IANA timezone string (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). Unsupported or invalid timezones are silently dropped.
</ParamField>

## Examples

```markdown title="Set timezone to Eastern Time" theme={null}
timezone=America/New_York
```

```markdown title="Set timezone to UTC" theme={null}
timezone=UTC
```


# uiSettings
Source: https://docs.omni.co/embed/setup/url-parameters/uiSettings

Controls general settings of the application in embed.

In the **Embed URL Builder**, this is the **UI Settings** field.

## Syntax

```json wrap theme={null}
uiSettings={"<string_property_name>":"<value>", "<boolean_property_name>":<value>, ...}
```

## Properties

<ParamField type="object">
  An object containing UI configuration settings.

  <Expandable title="uiSettings properties">
    <ParamField type="boolean">
      When `true`, context menus (the <Icon icon="ellipsis-vertical" /> icon and right-click menu) will be available on dashboard tiles. When `false`, context menus will be hidden.

      This setting is not applicable to classic dashboards.
    </ParamField>

    <ParamField type="boolean">
      When `true`, the `Generated <timestamp>` stamp is displayed in the dashboard footer. Omitted and unset keys will also resolve to `true`.

      When `false`, the timestamp is hidden.
    </ParamField>

    <ParamField type="string">
      Controls the display of folder path breadcrumbs in document title headers. This setting applies to [Create mode embeds](/embed/customization/create-mode) and affects workbooks and dashboards.

      Supported values:

      * `link` - Displays the folder path breadcrumb in the document title header as clickable links
      * `display` - Displays the folder path breadcrumb as visible text without hyperlinks, preventing navigation out of the embed
      * `none` - Hides the folder path breadcrumb entirely, including the personal-scope prefix (e.g., "X's Documents")
    </ParamField>

    <ParamField type="boolean">
      When `true`, the top header bar is displayed across the app. When `false`, the header bar is hidden. This setting applies to dashboard, workbook, and application pages.

      Supported in `@omni-co/embed` v1.0.0 and later.
    </ParamField>

    <ParamField type="boolean">
      When `true`, the [sidebar](/administration/settings/sidebar) and icon will display in the top-left corner of the app. When `false`, the panel and icon are hidden.
    </ParamField>

    <ParamField type="boolean">
      When `true`, the `Query ran <timestamp>` entry is displayed in a tile's context menu (both classic menu and advanced-layout context menu). Omitted and unset keys will also resolve to `true`.

      When `false`, this entry is hidden in the tile's context menu.

      <Warning>
        On non-classic dashboards, setting this property to `false` can hide the entire context menu button (<Icon icon="ellipsis-vertical" />) if no other menu actions are available to the viewer. The button may appear and disappear as viewers apply filters that change the available actions.
      </Warning>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Hide the top header bar

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    uiSettings={"showHeader": false}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    uiSettings=%7B%22showHeader%22%3A%20false%7D
    ```
  </Tab>
</Tabs>

### Hide sidebar panel

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    uiSettings={"showNavigation": false}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    uiSettings=%7B%22showNavigation%22%3A%20false%7D
    ```
  </Tab>
</Tabs>

### Hide dashboard tile context menu

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso), send the value as JSON:

    ```json v1 payload wrap theme={null}
    uiSettings={"dashboardChartContextMenu": false}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    uiSettings=%7B%22dashboardChartContextMenu%22%3A%20false%7D
    ```
  </Tab>
</Tabs>

### Hide dashboard timestamps

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso), send the value as JSON:

    ```json v1 payload wrap theme={null}
    uiSettings={"dashboardGeneratedAt": false, "tileRanTimestamp": false}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    uiSettings=%7B%22dashboardGeneratedAt%22%3A%20false%2C%20%22tileRanTimestamp%22%3A%20false%7D
    ```
  </Tab>
</Tabs>


# userAttributes
Source: https://docs.omni.co/embed/setup/url-parameters/userAttributes

Applies user attributes to the embed user.

Applies user attributes to the embed user.

In the **Embed URL Builder**, this is the **User attributes** field.

## Syntax

```json theme={null}
userAttributes={"<user_attribute_reference>": "<value>", ...}
```

## Properties

<ParamField type="object">
  An object containing [user attributes](/administration/users/attributes), specified as `"<user_attribute_reference>": "<value>"`.
</ParamField>

## Examples

### With and without encoding

<Tabs>
  <Tab title="v1 payload">
    In the [v1 signed payload format](/embed/setup/standard-sso/latest), send the value as JSON:

    ```json v1 payload wrap theme={null}
    userAttributes={"country":"Townsville", "associated_ids":[9,10,11], "omni_user_timezone":"America/New_York"}
    ```
  </Tab>

  <Tab title="v0 (legacy) payload">
    In the [legacy v0 format](/embed/setup/standard-sso/v0-legacy), stringify and URL encode the value before sending:

    ```markdown v0 (legacy) payload wrap theme={null}
    userAttributes=%7B%22country%22%3A%22Townsville%22%2C%20%22associated_ids%22%3A%5B9%2C10%2C11%5D%2C%20%22omni_user_timezone%22%3A%22America%2FNew_York%22%7D
    ```
  </Tab>
</Tabs>

### Manage AI credit limits

Use the [`omni_ai_credit_limit` user attribute](/administration/users/attributes#param-omni-ai-credit-limit-ai-credit-limit) to set [an individual user credit limit](/ai/settings/usage#individual-user-limit) for the user.

<Tabs>
  <Tab title="Set a credit limit">
    Set the `omni_ai_credit_limit` value to a number to limit the user to that number of credits:

    ```json v1 payload wrap theme={null}
    userAttributes={"omni_ai_credit_limit":40}
    ```
  </Tab>

  <Tab title="Unlimited credits">
    Set the `omni_ai_credit_limit` value to `unlimited` or `null` to allow the user to use unlimited credits:

    ```json v1 payload wrap theme={null}
    userAttributes={"omni_ai_credit_limit":"unlimited"}
    ```
  </Tab>

  <Tab title="Remove credit limit">
    To remove a user's credit limit, omit the `omni_ai_credit_limit` key from the `userAttributes` parameter. This will remove the user-specific setting and apply the [organization-level user default](/ai/settings/usage#per-user-default) instead.
  </Tab>
</Tabs>


# Omni Best Practices
Source: https://docs.omni.co/getting-started/best-practices

A checklist for building clean, performant, and user-friendly Omni environments.

This checklist covers best practices for keeping your model clean and your environment intuitive to navigate for your entire organization. It draws on experience across many implementations and provides a helpful starting point.

<Tip>
  Each section is split into **must haves** and **nice to haves**. If you have questions about anything not covered here, reach out to your Omni team.
</Tip>

## Housekeeping

**Must haves**

* There are documented standards for development
* The homepage is curated using [labels](/content/organize#label-options) set to display on the "Homepage"
* The ["Verified" label](/content/organize#label-options) is used to signal to users which content should be trusted
* The [Content Validator](/modeling/develop/content-validator) has no errors
* The [Git integration](/integrations/git) is set up for version control
* There is an internal Slack/Teams channel for analytics questions, or a clear process for getting help around data

**Nice to haves**

* Users have [favorited](/content/navigate) relevant content
* Unused content is regularly deleted

## Topic design

**Must haves**

* Topics are tidy and intuitive to use, with [topic descriptions](/modeling/topics/parameters/label) and [`ai_context`](/modeling/topics/parameters/ai-context) where applicable
* Topics are generally small to ensure both usability and performance
* Limited views are joined into each topic to keep them focused; use [`hidden`](/modeling/dimensions/parameters/hidden), [`ignored`](/modeling/dimensions/parameters/ignored), and [`field`](/modeling/topics/parameters/fields) parameters to limit displayed fields
* Topics are organized thematically using [`group_label`](/modeling/topics/parameters/group-label) on the field or topic level — avoid exposing raw schema naming
* Database columns, tables, and topics use language familiar to users with [`label`](/modeling/dimensions/parameters/label) and [`description`](/modeling/dimensions/parameters/description)
* Field names follow consistent naming conventions (e.g. not mixing `total_sales`, `sales_sum`, and `sales`)
* Boolean fields are named appropriately (e.g. `Is Returned` not `Returned`)
* No reference to date/time in time dimension groups to avoid "Date Date" field name issues
* Ratios use `measure1 / NULLIF(measure2, 0)` to handle zero denominators
* Value formats are used consistently across the model

**Nice to haves**

* For new topics not yet fully built out, create an initial set of measures using [point-and-click queries](/analyze-explore/point-click-queries) to avoid end users accidentally building from dimensions
* Use [`default_filters`](/modeling/topics/parameters/default-filters) or [`always_where_sql`](/modeling/topics/parameters/always-where-sql) to apply correct defaults and avoid querying excessive data volumes

Refer to [topic best practices](https://docs.omni.co/modeling/topics/best-practices) for more details on topic design.

## Dashboard design

**Must haves**

* Dashboards are built using curated topics rather than the ungoverned **All Views & Fields** mode
* Dashboards are intuitive to use with a small number of tiles (`<10` tiles per page)
* [AI summaries](/visualize-present/visualizations/types/ai-summary) and [Markdown visualizations](/visualize-present/visualizations/types/markdown) are used to make insights easier to read
* Axis labels are straightforward
* Filters have [default values](/visualize-present/dashboards/filters#default-values) to limit the size of queries run by default
* Deliveries are [scheduled](/share) on key dashboards
* The [color scheme](/visualize-present/dashboards/theming) works with both dark and light modes

**Nice to haves**

* Company branding and a consistent color scheme is applied; [Markdown visualizations](/showcase/visualizations/gradient-card) are used for custom headers and [data readouts](/showcase/visualizations/data-readout)
* [Links](/modeling/dimensions/parameters/links) create workflows between dashboards or jump to external applications

## Modeling

**Must haves**

* There are no model validation errors in the shared model
* Primary keys are unique and defined in all views
* The base table of topics is the most granular, joining out with [`many_to_one` or `one_to_one`](/modeling/topics/parameters/joins) joins; `inner`, `cross`, `one_to_many`, and `many_to_many` joins are generally not needed
* All assumed relationships have been validated and replaced with actual relationships (`assumed_many_to_one` → `many_to_one`)
* The relationships defined in the [relationships file](/modeling/relationships/index) are correct by checking the cardinality of the tables
* Omni [field references](/modeling/measures/parameters/sql) (`${field_name}`) are used over raw table/column names to prevent duplication in your code
* [`ignored_schemas`](/modeling/models/ignored-schemas), [`included_schemas`](/modeling/models/ignored-schemas), and [`ignored_views`](/modeling/models/ignored-views) are used to include only relevant schemas and tables
* Fields and logic reused across workbooks are added to the shared model; one-off fields live in the workbook model
* [`drill_fields`](/modeling/dimensions/parameters/drill-fields) and [`drill_queries`](/modeling/measures/parameters/drill-queries) are used to allow users to drill deeper; [`default_drill_fields`](/modeling/views/parameters/default-drill-fields) are defined for each view
* Shared logic lives in view/relationship files; topic files are reserved for use-case-specific overrides

**Nice to haves**

* Object names have consistent capitalization; for example: lowercase letters and underscores are used for all object names
* The modeling layer uses [view folders](https://docs.omni.co/modeling/views/parameters/folder) and topic [group\_label](https://docs.omni.co/modeling/topics/parameters/group-label) to keep the code organized

## Performance optimization

**Must haves**

* Where appropriate, [aggregate awareness](/analyze-explore/performance/aggregate-awareness) and rollups are used
* Heavy transformations (window functions, CTEs) happen in dbt or ETL — if applicable, see the [dbt integration](https://omni.co/blog/three-ways-to-use-our-dbt-integration)

## Security

**Must haves**

* Connections use restrictive [permissions](/administration/users/permissions) as the default (Viewer or Restricted Querier)
* [User groups](/administration/users/groups) are leveraged to make content access control easier to manage
* [User attributes](/administration/users/attributes) are used to manage access to topics and column/row-level security with [`access_filters`](/modeling/topics/parameters/access-filters) and [`access_grant`](/modeling/models/access-grants)

Refer to [permissions scenarios](https://docs.omni.co/administration/users/permissions-scenarios) to determine the most appropriate configuration for your access.

## Next steps

* Learn how to [create and configure topics](/modeling/topics/setup) in Omni
* Learn to [apply layout, visual, and filter patterns](/visualize-present/dashboards) to build effective dashboards
* Manage access control and content permissions in our [security and permissions docs](/administration/users/permissions)


# Omni for developers
Source: https://docs.omni.co/getting-started/developers

Query data, manage models, and automate Omni from your terminal, IDE, or AI tools — plus a video series on building your first Omni content and model.

## Build with Omni programmatically

Query data, manage models, administer users, and automate workflows — from your terminal, your IDE, or your favorite AI tools.

<CardGroup>
  <Card title="CLI" icon="terminal" href="/developers/cli">
    Query data, manage models and content, and automate workflows from the terminal or CI/CD.
  </Card>

  <Card title="MCP server" icon="robot" href="/ai/mcp">
    Connect Claude, Cursor, ChatGPT, and other AI tools to your Omni model for natural language querying.
  </Card>

  <Card title="REST API" icon="code" href="/api">
    Programmatically interact with your Omni instance over HTTP.
  </Card>
</CardGroup>

<Note>
  **Using a coding agent?** Paste this prompt into Claude Code, Cursor, Codex, or any coding agent and it will install the Omni CLI for you:

  ```text theme={null}
  Install the Omni CLI from https://github.com/exploreomni/cli
  ```
</Note>

## Set up Omni: from workbook to modeling

This five-part video series walks you through building your first content and models in Omni.

To follow the steps below, you'll need:

* An existing [database connection](/connect-data/setup)
* [Organization Admin](/administration/users/permissions) permissions

<Steps>
  <Step title="Create your first workbook analysis">
    <iframe title="Setup & First Analysis" />

    Get started by creating a brand new [workbook](/analyze-explore) in Omni, building out your first analysis, and creating your first table join.
  </Step>

  <Step title="Build a topic and create additional workbook content">
    <iframe title="Build a Topic & Create Content" />

    Next, learn how to build your first Omni topic. Then, explore different ways to create content in workbooks - through [point and click](/analyze-explore/point-click-queries), [Excel-like formulas](/analyze-explore/calculations), [SQL](/analyze-explore/sql), and [Omni's AI](/ai/queries).
  </Step>

  <Step title="Present your work on a dashboard">
    <iframe title="Build a Dashboard" />

    Present your analysis by building out a [dashboard](/visualize-present/dashboards) and customizing it with filters, text tiles, and more.
  </Step>

  <Step title="Understand Omni's semantic modeling layer">
    <iframe title="Semantic Model Workflow" />

    Learn about Omni's [architectural layers](/modeling), from the promotion of a workbook field to the shared model, to adding changes to a branch, to a tour of the model IDE.
  </Step>

  <Step title="Merge model changes in branches">
    <iframe title="Semantic Model Workflow (cont.)" />

    Building on Part 4, the last step is to merge your branch changes into the shared model. You'll also learn additional tools to help you build and manage your models, such as [schema refreshes](/modeling/develop/schema-refreshes) and [model version histories](/modeling/develop/history).
  </Step>
</Steps>


# Keyboard shortcuts
Source: https://docs.omni.co/getting-started/keyboard-shortcuts

A compiled list of shortcuts throughout the app.

<Note>
  Keyboard shortcuts are not currently supported in [embedded Omni instances](/embed).
</Note>

## Global shortcuts

These shortcuts can be used anywhere in the Omni app.

| Action                        | Mac             | Windows         |
| ----------------------------- | --------------- | --------------- |
| Open/close application search | `command` + `/` | `control` + `/` |

## Workbook shortcuts

These shortcuts apply in [workbooks](/analyze-explore).

| Action                                                                      | Mac                                  | Windows                           |
| --------------------------------------------------------------------------- | ------------------------------------ | --------------------------------- |
| New workbook tab                                                            | `option` + `T`                       | `alt` + `T`                       |
| Save workbook                                                               | `command` + `S`                      | `control` + `S`                   |
| Edit workbook (transition from View)                                        | `command` + `E`                      | `control` + `E`                   |
| Toggle between results table / chart                                        | `option` + `1`                       | `alt` + `1`                       |
| Toggle results / chart with options open                                    | `shift` + `option` + `1`             | `shift` + `alt` + `1`             |
| Toggle filters open / closed                                                | `option` + `2`                       | `alt` + `2`                       |
| Toggle SQL block open / closed                                              | `option` + `3`                       | `alt` + `3`                       |
| Toggle field picker open / closed                                           | `option` + `4`                       | `alt` + `4`                       |
| Toggle options config open / closed                                         | `option` + `5`                       | `alt` + `5`                       |
| Toggle [inspector panel](/analyze-explore/workbook-inspector) open / closed | `option` + `9`                       | `alt` + `9`                       |
| <Tooltip>Toggle chart to full screen mode</Tooltip>                         | `option` + `.`                       | `alt` + `.`                       |
| Toggle [Workbook Agent](/ai/queries)                                        | `option` + `command` + `8`           | `alt` + `control` + `8`           |
| Run query                                                                   | `command` + `Return`                 | `control` + `Enter`               |
| Run query w/o cache                                                         | `shift` + `command` + `Return`       | `shift` + `control` + `Enter`     |
| Clear query                                                                 | `command` + `K`                      | `control` + `K`                   |
| Clear field from query                                                      | `shift` + `command` + `K`            | `shift` + `control` + `K`         |
| Clear filters from query                                                    | `option` + `command` + `K`           | `alt` + `control` + `K`           |
| Clear query and switch model                                                | `shift` + `option` + `command` + `K` | `shift` + `alt` + `control` + `K` |
| Focus field search                                                          | `option` + `command` + `F`           | `alt` + `control` + `F`           |
| Collapse/expand all field list items                                        | `shift` + `option` + `command` + `F` | `shift` + `alt` + `control` + `F` |
| Duplicate tab                                                               | `command` + `D`                      | `control` + `D`                   |
| Next tab                                                                    | `command` + `option` + `down`        | `control` + `alt` + `down`        |
| Previous tab                                                                | `command` + `option` + `up`          | `control` + `alt` + `up`          |
| First tab                                                                   | `command` + `option` + `[`           | `control` + `alt` + `[`           |
| Last tab                                                                    | `command` + `option` + `]`           | `control` + `alt` + `]`           |
| Rename current tab                                                          | `option` + `command` + `R`           | `alt` + `control` + `R`           |

## Spreadsheet tabs shortcuts

These shortcuts apply when working with [spreadsheet tabs](/analyze-explore/spreadsheet-tabs) in workbooks.

| Action                  | Mac                       | Windows                   |
| ----------------------- | ------------------------- | ------------------------- |
| Delete row or column    | `command` + `-`           | `control` + `-`           |
| Insert row or column    | `command` + `+`           | `control` + `+`           |
| Bold                    | `command` + `B`           | `control` + `B`           |
| Italic                  | `command` + `I`           | `control` + `I`           |
| Underline               | `command` + `U`           | `control` + `U`           |
| Format as percentage    | `control` + `shift` + `5` | `control` + `shift` + `5` |
| Cycle formula reference | `F4`                      | `F4`                      |

## SQL editor autocomplete shortcuts

These shortcuts apply when working in the [SQL editor](/analyze-explore/sql) in a workbook.

| Action                              | Mac                 | Windows             |
| ----------------------------------- | ------------------- | ------------------- |
| Trigger autocomplete                | `control` + `space` | `control` + `space` |
| Accept suggestion                   | `tab`               | `tab`               |
| Accept suggestion or insert newline | `return`            | `Enter`             |
| Close autocomplete popup            | `esc`               | `esc`               |

## Dashboard shortcuts

These shortcuts apply when viewing or editing a [dashboard](/visualize-present/dashboards).

| Action                                | Mac                                     | Windows                                 |
| ------------------------------------- | --------------------------------------- | --------------------------------------- |
| Open/toggle properties panel          | `command` + `\`                         | `control` + `\`                         |
| Undo layout change                    | `command` + `Z`                         | `control` + `Z`                         |
| Redo layout change                    | `shift` + `command` + `Z`               | `shift` + `control` + `Z`               |
| Duplicate container or item           | Select container/item + `command` + `D` | Select container/item + `control` + `D` |
| Cycle zoom presets                    | `command` + `scroll`                    | `control` + `scroll`                    |
| Reset zoom to fit mode                | `alt` + `command` + `scroll`            | `alt` + `control` + `scroll`            |
| Reset dashboard filters               | `command` + `K`                         | `control` + `K`                         |
| Refresh dashboard                     | `command` + `return`                    | `control` + `enter`                     |
| Refresh dashboard without cache       | `shift` + `command` + `return`          | `shift` + `control` + `enter`           |
| <Tooltip>Toggle full screen</Tooltip> | `option` + `.`                          | `alt` + `.`                             |

## Table shortcuts

These shortcuts apply when interacting with tables in [workbooks](/analyze-explore/point-click-queries#interacting-with-tables) and [dashboard tiles](/visualize-present/dashboards/charts#interacting-with-table-tiles). All gestures require the visualization to be in table view.

### Selection

| Action                              | Mac                               | Windows                           |
| ----------------------------------- | --------------------------------- | --------------------------------- |
| Select all cells                    | `command` + `A`                   | `control` + `A`                   |
| Copy selected cells                 | `command` + `C`                   | `control` + `C`                   |
| Clear selection (keyboard)          | `escape`                          | `escape`                          |
| Move focused cell                   | `arrow` keys                      | `arrow` keys                      |
| Extend selection from anchor        | `shift` + `arrow` keys            | `shift` + `arrow` keys            |
| Select a cell                       | `click`                           | `click`                           |
| Select range from anchor to cell    | `shift` + `click`                 | `shift` + `click`                 |
| Add or remove cell from selection   | `command` + `click`               | `control` + `click`               |
| Select a rectangular region         | `click` and drag                  | `click` and drag                  |
| Select entire row                   | `click` row number                | `click` row number                |
| Extend selection through row        | `shift` + `click` row number      | `shift` + `click` row number      |
| Add or remove row from selection    | `command` + `click` row number    | `control` + `click` row number    |
| Select entire column                | `click` column header             | `click` column header             |
| Extend selection through column     | `shift` + `click` column header   | `shift` + `click` column header   |
| Add or remove column from selection | `command` + `click` column header | `control` + `click` column header |
| Clear selection (mouse)             | `click` outside table             | `click` outside table             |

When all cells are selected with `command`/`control` + `A`, column headers are included when copying.

### Editing and interaction (workbooks only)

These shortcuts are only available in workbook tables. Dashboard tables are read-only.

| Action                               | Mac                | Windows            |
| ------------------------------------ | ------------------ | ------------------ |
| Edit calculation cell or expand cell | `enter`            | `enter`            |
| Edit a calculation cell              | `double-click`     | `double-click`     |
| Open context menu                    | `right-click`      | `right-click`      |
| Reorder columns                      | Drag column header | Drag column header |

Column reordering is not available in pivot tables.

### Calculation editing (workbooks only)

These shortcuts apply when editing a [calculation](/analyze-explore/spreadsheet-tabs) in a workbook table.

| Action                      | Mac                      | Windows                  |
| --------------------------- | ------------------------ | ------------------------ |
| Save calculation            | `enter`                  | `enter`                  |
| Cancel and exit editor      | `escape`                 | `escape`                 |
| Insert cell range reference | `shift` + `click` a cell | `shift` + `click` a cell |

## Markdown editor shortcuts

These shortcuts are available when editing [text tiles](/visualize-present/dashboards/text-markdown) in a dashboard.

| Action         | Mac                       | Windows                   |
| -------------- | ------------------------- | ------------------------- |
| Bold           | `command` + `B`           | `control` + `B`           |
| Italic         | `command` + `I`           | `control` + `I`           |
| Blockquote     | `shift` + `command` + `.` | `shift` + `control` + `.` |
| Ordered list   | `shift` + `command` + `7` | `shift` + `control` + `7` |
| Unordered list | `shift` + `command` + `8` | `shift` + `control` + `8` |

## Model IDE shortcuts

These shortcuts apply when viewing or editing files in the [model IDE](/modeling).

| Action                                     | Mac                              | Windows                          |
| ------------------------------------------ | -------------------------------- | -------------------------------- |
| Save file                                  | `command` + `S`                  | `control` + `S`                  |
| Find / search                              | `option` + `command` + `F`       | `alt` + `control` + `F`          |
| Toggle file list open / closed             | `option` + `1`                   | `alt` + `1`                      |
| Toggle model validation list open / closed | `option` + `9`                   | `alt` + `9`                      |
| Toggle word wrap on / off                  | `option` + `Z`                   | `alt` + `Z`                      |
| Fold all sections in a file                | `command` + `K`, `command` + `0` | `control` + `K`, `control` + `0` |
| Unfold all sections in a file              | `command` + `K`, `command` + `J` | `control` + `K`, `control` + `J` |


# Onboarding to Omni as a Viewer
Source: https://docs.omni.co/getting-started/viewers

Intended for viewers, this six-part video series will help you get started with viewing dashboard content in Omni.

To follow the steps in this guide, you'll need:

* An Omni account
* [Viewer](/administration/users/permissions) permissions

<Steps>
  <Step title="Navigate the Omni platform">
    <iframe title="Navigating the Omni platform" />

    Learn how to [navigate the Omni platform](/content/navigate), including how to browse content, apply themes, and add content to your favorites.
  </Step>

  <Step title="Understand permissions">
    <iframe title="Understanding permissions" />

    What can you do in Omni as a Viewer? Learn about Omni's [connection](/connect-data/setup) and [content permissions](/share#content-access-permissions), how to share pre-built dashboards, and how to update dashboard permissions.
  </Step>

  <Step title="Discover what can be built in Omni">
    <iframe title="What can be built in Omni?" />

    See what can be built in Omni, with the goal of inspiring requests made of your builder teammates.
  </Step>

  <Step title="Troubleshoot 'Can't display chart' errors">
    <iframe title="Troubleshooting Can't display chart errors" />

    There may be times when you run into `Can't display chart` errors when viewing a dashboard. Learn what's happening and how to resolve it using Omni's [AccessBoost feature](/share#boosting-permissions-with-accessboost).
  </Step>

  <Step title="Filter on dashboards">
    <iframe title="Filtering on dashboards" />

    Filtering allows you to focus only on the data you care about. Learn about the power and flexibility of Omni dashboard filters.
  </Step>

  <Step title="Deliver and download results">
    <iframe title="Delivering & downloading results" />

    While Omni supports [downloading results](/visualize-present/dashboards/download) on a one-off basis, [deliveries and alerts](/share/deliveries) allow you to define where and when you want your data. In this video, you'll learn about your options for downloading results and how to set up Omni deliveries and alerts.
  </Step>
</Steps>


# Improving AI answer quality
Source: https://docs.omni.co/guides/ai/improve-ai-answer-quality

Learn practical steps to improve AI answer quality in Omni by optimizing data modeling, testing AI responses, and monitoring usage patterns.

<GuideSidebar />

<GuideTitle title="Improving AI answer quality" />

Making your datasets AI-ready doesn't require a massive overhaul. Most of the steps are things you're already doing to make data understandable to humans — now you're extending that same clarity to help the AI interpret it.

In this guide, we'll show you how to:

* **Model** your data with small changes
* **Test** and iterate quickly on the changes
* **Monitor** user behavior to identify improvements

## Structure your data like you would for humans

Good AI performance starts with solid, user-friendly data modeling. The goal is to make each dataset clear, focused, and include the most important context and logic - just like you would if you were handing it to a user in your company.

In Omni, that means building well-scoped [**topics**](/modeling/topics). A topic should represent a specific slice of your business logic and include just the fields, filters, and joins needed to answer common questions about that area.

Here’s what that looks like in practice:

* **Create subject-specific datasets.** Keep each dataset focused and scoped to a clear business purpose.
* **Add joins** so users (and the AI) know what tables are accessible.
* **Apply default filters** to remove noise (e.g. exclude deleted records).
* **Set appropriate permissions.** Omni’s AI always respects the user’s data permissions, so make sure row-, column-, or topic-level controls are in place if needed.
* **Hide extraneous fields** like unused columns or foreign keys.
* **Use good field labels.** This means:
  * **Instead of** `scheduled_task_id_count_distinct`, label it `“Number of Schedules”`
  * **Add field descriptions** or pull directly from your warehouse or [dbt](/integrations/dbt/syncing-dbt). These help the AI disambiguate fields.
* **Add** `all_values` for [dimensions](/modeling/dimensions/parameters/all-values) and [measures](/modeling/measures/parameters/all-values) that commonly appear in filters. This helps the AI map user-friendly input to the actual values in your data.

  For example, if someone asks for `“users in CA”` but the underlying value in the column is `California`, providing `all_values` ensures the AI knows they’re the same.
* **Define a short overview** of what the dataset is for - this is the `ai_context` parameter and it helps the AI choose the right dataset for each question.

## Test and tune the AI

Once your datasets are modeled well, the next step is to see how the AI performs in practice. Omni recommends collecting 10–20 real questions your users are already asking, and running them through the AI to see how it does.

The best place to do this is in the workbook with the [Workbook Agent](/ai/queries). This allows you to see exactly how the AI is formulating the answer (fields selected, filters applied, SQL), and adjust the answer/re-steer it as needed.

If the AI gets things wrong, you can immediately add some context to improve it, then try the question again. Take a look at some examples:

### Is it getting filter values wrong?

* **Example:** User asked for total orders in CA. AI applied a filter on State = ‘CA’, but the actual values in the database are full state names (e.g. ‘California’)
* **Solve:** Add `all_values` to the State field so it can match the user input to values in the database.

  <img alt="The Edit Field panel for the Users State field, showing sample values like California, Texas, and New York" />

### Is it confused between similar fields?

* **Example:** A user asks for “revenue,” and the AI picks the wrong field – maybe it chooses `total_revenue` instead of `net_revenue`.
* **Solve:** Add field [synonyms](/modeling/develop/ai-optimization#curate-views-and-fields) or a more explicit description to help guide selection. If you have duplicative or outdated fields, consider hiding or removing them to simplify the dataset.

  <img alt="The Edit Field panel for Sale Price Sum, showing synonyms set to revenue and total sales" />

### Is it picking the wrong dataset?

* **Example:** A user asks about product inventory, but the AI chooses a marketing dataset because of overlapping field names.
* **Solve:** Add more detail to the `ai_context` parameter on each topic, and include examples of real user questions to help the AI learn when each dataset should be used.

  ```yaml title="product usage topic context" wrap theme={null}
  ai_context: |-
    this topic contains data about our product usage. the core table is queries, which is the primary concept of usage in our business intelligence product. any question about 'usage' or 'queries' or 'activity' should use this topic
  ```

### Is there hidden nuance in your business language?

* **Example:** A user asks about “closed deals.” In your org, folks really mean deals that are both closed and won. But without that context, the AI is going to just filter on `closed=true`.
* **Solve:** Clarify how common business terms are used in your `ai_context`, so the AI can apply your team’s language correctly to the data.

  **Example**: *if asked about closed deals, most often the user means both closed and won.*

  ```yaml title="salesforce opportunity topic context" wrap theme={null}
  ai_context: |-
    we use a fiscal year at our company. when someone mentions 'quarter' or 'year', they typically mean the fiscal quarter or fiscal year

    if asked about closed deals, most often the user means both closed and won
  ```

<Tip>
  You can also use Omni’s built-in tools to help automate this tuning process. The [**Learn from conversation**](/ai/learn-from-conversation) feature can extrapolate business context, field definitions, synonyms, and more from an AI chat conversation. It’s a quick way to capture real user language and feed it back into your AI setup with minimal effort.
</Tip>

## Tune your AI model settings

Modeling and context improvements get you most of the way to good answers, but for complex questions or high-stakes workloads, you can tweak the model's settings. The model-level [`ai_settings`](/modeling/models/parameters/ai-settings) parameter lets you set the model tier, thinking level, and self-validation behavior for each AI task type.

For answer quality, the biggest lever is [`analyze_configuration.model`](/modeling/models/parameters/ai-settings/analyze-configuration) — setting it to `smartest` routes analytical queries to the most capable model for your [model provider](/ai/settings/model-providers).

Changing `analyze_configuration.thinking` to `high` gives the Omni Agent more reasoning budget per turn, and enabling [`validate_analysis`](/modeling/models/parameters/ai-settings/validate-analysis) has the agent self-check its work before users see the result.

For a walkthrough of how to combine these settings, see the [Max quality profile](/guides/ai/tuning-cost-quality#max-quality) in the cost-and-quality tuning guide.

<Note>
  **Heads up!** Upgrading these settings increases LLM token usage, so they're best reserved for models where answer quality matters more than cost.
</Note>

## Monitor what people are asking

Once you’re up and running, check your prompt logs in the [Analytics section](/administration/analytics) regularly. You’ll learn a lot by seeing how people interact with AI and where it struggles.

Look for:

* **Questions the AI couldn’t answer** - are there data gaps?
* **Repeated follow-ups or corrections** - is the topic or fields missing critical context?
* **Business terms people are using** - are there synonyms or preferences you should capture in your context?

<img alt="The Analytics session log showing AI conversation history with user prompts and session dates" />


# Tuning Omni AI for cost and quality
Source: https://docs.omni.co/guides/ai/tuning-cost-quality

Balance AI cost and quality for your organization by combining ai_settings parameters into profiles that fit your use cases.

<GuideSidebar />

<GuideTitle title="Tuning Omni AI for cost and quality" />

The behavior of Omni's Agent on a model is controlled by the [`ai_settings`](/modeling/models/parameters/ai-settings) parameter. Several of its sub-parameters compose into a spectrum between "cheap and fast" and "accurate but expensive" — which means you can deliberately tune a model for the workloads it actually serves, rather than accepting defaults everywhere.

This guide maps those knobs to three starting profiles — cost-optimized, balanced, and max-quality — that you can adopt directly or adapt to your organization.

## Requirements

To follow this guide, you'll need:

* **Connection Admin** or **Modeler** permissions on the model you want to work with
* An understanding of the parameters documented on the [`ai_settings` reference](/modeling/models/parameters/ai-settings)

## How AI settings affect cost

Every AI turn in Omni costs LLM tokens. Different `ai_settings` parameters affect token usage in different ways, and some affect cost more than others.

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Parameter</th>
      <th>Cost</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`analyze_configuration.model`][analyze-config]</td>
      <td>**High.** `smartest` is multiple times more expensive per LLM token than `standard`.</td>
    </tr>

    <tr>
      <td>[`analyze_configuration.thinking`][analyze-config]</td>
      <td>**High.** Each level adds reasoning LLM tokens to every turn; `high` on `analyze` compounds fastest.</td>
    </tr>

    <tr>
      <td>[`validate_analysis`][validate-analysis]</td>
      <td>**High.** Adds additional model turns per analytical turn, each at the analyze tier and thinking level.</td>
    </tr>

    <tr>
      <td>[`conversation_prune_length`][conversation-prune]</td>
      <td>**Medium. Claude/Anthropic models only.** Higher thresholds mean more LLM tokens billed per turn on long conversations.</td>
    </tr>

    <tr>
      <td>[`query_all_views_and_fields`][query-views-fields]</td>
      <td>**Low–medium.** A larger search surface means more views considered per query, which costs LLM tokens.</td>
    </tr>

    <tr>
      <td>[`build_configuration.*`][build-config]</td>
      <td>**Low in aggregate.** Model-building tasks run less often than analysis, though many iterative steps when creating a dashboard can spike usage.</td>
    </tr>

    <tr>
      <td>[`simple_summarize_configuration.*`][summarize-config]</td>
      <td>**Low per call, but high volume.** Keep at `fastest` / `none` unless you have a specific reason to upgrade.</td>
    </tr>
  </tbody>
</table>

## Tuning profiles

Each profile below is a recommended starting point — not a rigid recipe. You can mix parameters across profiles and override settings on specific models when individual use cases warrant it. See [Mix and override profiles](#mix-and-override-profiles) below.

| Profile                           | Best for                                                                                                                | Tradeoffs                                                                                           |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Cost-optimized](#cost-optimized) | High-volume AI usage, recurring questions against a well-curated topic set                                              | Smaller query surface, no query validation, earlier context pruning, no extended reasoning          |
| [Balanced](#balanced)             | Most organizations, most of the time. Mirrors Omni's default behavior.                                                  |                                                                                                     |
| [Max quality](#max-quality)       | Highly complex questions and datasets, optimizing for depth over speed, debugging accuracy issues with default settings | Potential for higher costs due to query validation and usage of `smartest` + high `thinking` models |

<Note>
  The [`conversation_prune_length`][conversation-prune] parameter is only supported for Claude/Anthropic models.
</Note>

### Cost-optimized

This profile is best for high-volume AI usage where per-query cost matters more than marginal accuracy, or models where end users are doing bounded, familiar analysis. For example, recurring questions over a well-curated topic set.

```yaml Cost-optimized ai_settings profile theme={null}
ai_settings:
  query_all_views_and_fields: disabled
  validate_analysis: disabled
  conversation_prune_length: short
  analyze_configuration:
    model: standard
    thinking: none
  build_configuration:
    model: standard
    thinking: none
  simple_summarize_configuration:
    model: fastest
    thinking: none
```

The tradeoffs of this approach are:

* A smaller query surface (topic-scoped only), so ad-hoc views aren't available to the AI ([`query_all_fields_and_views: disabled`][query-views-fields])
* No self-correction before users see results ([`validate_analysis: disabled`][validate-analysis])
* Earlier context pruning on long chats (75,000 LLM tokens vs. 175,000 at the default) ([`conversation_prune_length: short`][conversation-prune])
* No extended reasoning — every turn responds from the raw prompt (`*.thinking: none`)

### Balanced (default)

This profile is best for most organizations, most of the time. This profile mirrors Omni's out-of-the-box behavior — it's what you get if you don't set `ai_settings` at all. You can copy it into your model to make the intent explicit, or omit `ai_settings` entirely.

```yaml Balanced (default) ai_settings profile theme={null}
ai_settings:
  query_all_views_and_fields: enabled
  validate_analysis: disabled
  conversation_prune_length: max
  analyze_configuration:
    model: standard
    thinking: none
  build_configuration:
    model: smartest
    thinking: none
  simple_summarize_configuration:
    model: fastest
    thinking: none
```

This approach is the default because:

* The `*.model: standard` tier is strong enough for most analytical tasks without `smartest`-tier pricing
* `*.thinking: fastest` is almost always the right call for short summarization work
* [`conversation_prune_length: max`][conversation-prune] preserves context while opting you into future >200k context sizes as they become available

<Note>
  If your instance was created on or before March 5, 2026, [`query_all_views_and_fields`][query-views-fields] defaults to `disabled` rather than `enabled`. Setting it explicitly in your model overrides the instance default either way.

  Similarly, if your instance was created on or before April 23, 2026, [`build_configuration.model`][build-config] defaults to `standard` rather than `smartest`. Setting it explicitly in your model overrides the instance default.
</Note>

### Max quality

This profile is best for highly complex questions and datasets, and when you want to optimize for exploration depth and answer quality over speed. It can also be useful when you've seen accuracy issues with the defaults and want to raise the floor before debugging further.

```yaml Max quality ai_settings profile theme={null}
ai_settings:
  query_all_views_and_fields: enabled
  validate_analysis: enabled
  conversation_prune_length: max
  analyze_configuration:
    model: smartest
    thinking: high
  build_configuration:
    model: smartest
    thinking: medium
  simple_summarize_configuration:
    model: standard
    thinking: low
```

While this approach can yield higher quality results, there are a few tradeoffs:

* [`validate_analysis: enabled`][validate-analysis] adds additional model turns per analytical turn
* `smartest` + `thinking: high` on [`analyze_configuration`][analyze-config] is the single biggest cost multiplier — only use it if the accuracy lift is worth it for your workload
* [Summarization][summarize-config] is intentionally kept lighter (`standard` / `low`) because it's high-volume and low-leverage; pushing it to `smartest` / `high` rarely changes subtitle or description output meaningfully

## Mix and override profiles

The profiles above are starting points — you don't have to adopt one in its entirety. A few common compositions:

* **Mostly default with quality insurance.** Start from [**Balanced**](#balanced) and flip [`validate_analysis`][validate-analysis] to `enabled`. This adds self-correction without upgrading model tier or thinking level, which is often the cheapest way to raise answer quality.

  ```yaml theme={null}
  ai_settings:
    validate_analysis: enabled
  ```

* **Max quality analysis, default everything else.** Upgrade only [`analyze_configuration`][analyze-config] and leave build and summarize at defaults. This concentrates spend where it matters most — user-facing analytical output — without paying for it on lower-value tasks.

  ```yaml theme={null}
  ai_settings:
    analyze_configuration:
      model: smartest
      thinking: high
  ```

* **Cost-optimized with fuller context.** Start from [**Cost-optimized**](#cost-optimized) but keep [`conversation_prune_length: long`][conversation-prune] if your users tend to have long chat sessions where losing earlier context would hurt more than the LLM token savings.

  ```yaml theme={null}
  ai_settings:
    query_all_views_and_fields: disabled
    validate_analysis: disabled
    conversation_prune_length: long
    analyze_configuration:
      model: standard
      thinking: none
    build_configuration:
      model: standard
      thinking: none
    simple_summarize_configuration:
      model: fastest
      thinking: none
  ```

## Apply a profile to your model

<Steps>
  <Step>
    Navigate to the model IDE and open the model settings (`model`) file.
  </Step>

  <Step>
    Add the `ai_settings` block from the profile you want to use to the model file.

    <Tip>
      **Note sure which profile to use?** Start with [**Balanced**](#balanced) and only adjust once you see specific cost or accuracy issues you want to address.
    </Tip>
  </Step>

  <Step>
    Save your changes.
  </Step>

  <Step>
    Promote the changes to the shared model.
  </Step>
</Steps>

## Monitor and iterate

After applying a profile, check the [**Analytics > Credit tracking** dashboard](/ai/settings/usage) periodically to see how your users are interacting with Omni AI. Look for:

* **Question volume and types** — Helps you judge whether the profile still fits the actual workload
* **Turn counts per conversation** — Long conversations interact with `conversation_prune_length`; if pruning is kicking in frequently, consider raising the threshold or investigating why conversations run long

Tuning is iterative. It's common to start balanced, upgrade a single dimension (such as `validate_analysis`), observe the change, and continue from there rather than jumping straight to max quality.

## Next steps

* [AI credit tracking](/ai/settings/usage) - Track your organization's AI usage over time
* [`ai_settings` reference](/modeling/models/parameters/ai-settings) — Full parameter documentation
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Curate the context Omni AI sees, which can help improve quality instead of making model-tier upgrades
* [Learn from conversation](/ai/learn-from-conversation) — Use real user questions to improve the model over time

[analyze-config]: /modeling/models/parameters/ai-settings/analyze-configuration

[build-config]: /modeling/models/parameters/ai-settings/build-configuration

[summarize-config]: /modeling/models/parameters/ai-settings/simple-summarize-configuration

[conversation-prune]: /modeling/models/parameters/ai-settings/conversation-prune-length

[validate-analysis]: /modeling/models/parameters/ai-settings/validate-analysis

[query-views-fields]: /modeling/models/parameters/ai-settings/query-all-views-and-fields


# Bulk update model YAML files with the API
Source: https://docs.omni.co/guides/api/bulk-update-model-yaml

Use a model branch to batch programmatic YAML updates into a single git sync.

<GuideSidebar />

<GuideTitle title="Bulk update model YAML files with the API" />

The [Create or update YAML files endpoint](/api/models/create-or-update-yaml-files) writes one file per request. When you target a [git-enabled](/integrations/git) shared model directly, each write triggers its own git sync. At hundreds or thousands of files, that results in a process that could take hours.

The fix is to write against a [model branch](/content/develop/branch-mode) instead, then merge the branch once when all updates are complete. Git syncs a single time, on the merge.

## Requirements

To follow the steps in this guide, you'll need:

* An [Omni API key](/api/authentication)
* **Modeler** or higher permissions on the shared model you want to update
* The shared model's `modelId` and `connectionId`, which you can retrieve using the [List models](/api/models/list-models) endpoint

<Steps>
  <Step title="Create a branch off the shared model">
    Call the [Create model](/api/models/create-model) endpoint with `modelKind: "BRANCH"`. Set `baseModelId` to the shared model you want to branch from and reuse its `connectionId`.

    ```bash theme={null}
    curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models \
      -H "Authorization: Bearer <YOUR_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "modelKind": "BRANCH",
        "baseModelId": "<SHARED_MODEL_ID>",
        "connectionId": "<CONNECTION_ID>",
        "modelName": "<MODEL_NAME>"
      }'
    ```

    Save two values from the response:

    * `id` — The branch's UUID, which you'll pass as `branchId` in the next step.
    * `modelName` — What you provided in the request body. The merge endpoint identifies the branch by name, not by ID, so you need this exact string later.
  </Step>

  <Step title="Write YAML files against the branch">
    For each file, call the [Create or update YAML files](/api/models/create-or-update-yaml-files) endpoint:

    ```bash theme={null}
    curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/yaml \
      -H "Authorization: Bearer <YOUR_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "branchId": "<BRANCH_ID>",
        "fileName": "<view_name>.view",
        "yaml": "<file contents as a string>",
        "mode": "combined"
      }'
    ```

    In the path, put the shared model's ID. For the request body:

    * `branchId` - The branch UUID from step 1's response (`id`). This routes the write operation to the branch instead of the shared model and is required for models where pull requests are required.
    * `fileName` - The name of the file being created or updated. This can be `model`, `relationships`, `<topic_name>.topic` for topics, `<composite_topic_name>.composite_topic` for composite topics, or `<view_name>.view` for view files.
    * `yaml` - The YAML content of the file as a formatted JSON string
    * `mode` - Set to `combined`
    * `commitMessage` - Required if the model has git enabled. A short commit message for the change.

    Loop this call for every file in your batch. Because writes go to the branch, none of them triggers a git sync.

    If a single write fails partway through, the branch keeps the writes that already succeeded. Fix the failing file and retry just that request before moving on to the merge.
  </Step>

  <Step title="Validate before merging">
    Validation is optional but strongly recommended — it catches issues on the branch before they reach the shared model, where they could break existing dashboards and queries.

    Two endpoints validate different surfaces: **Validate model** for the YAML itself, and **Validate content** for the dashboards and queries that depend on it. Run both for the safest merge.

    * **Validate the model.** Use the [Validate model](/api/models/validate-model) endpoint to catch broken references, invalid types, and structural issues introduced by your YAML writes.

      ```bash theme={null}
      curl -X GET "https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/validate?branchId=<BRANCH_ID>" \
        -H "Authorization: Bearer <YOUR_API_TOKEN>"
      ```

    * **Validate content.** Use the [Validate content](/api/content-validator/validate-content) endpoint to catch dashboards and queries that reference fields or views the branch renamed or removed. Note the query parameter is `branch_id` (snake\_case) on this endpoint.

      ```bash theme={null}
      curl -X GET "https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/content-validator?branch_id=<BRANCH_ID>" \
        -H "Authorization: Bearer <YOUR_API_TOKEN>"
      ```

    Resolve any issues these endpoints return by writing additional YAML updates against the same branch, then re-run validation. Only proceed to the merge once both come back clean.
  </Step>

  <Step title="Merge the branch">
    <Note>
      The Merge branch endpoint can't be used with models that require pull requests or those using [git follower mode](/integrations/git/follower-mode). See the [Merge branch documentation](/api/model-branches/merge-a-branch) for more information.
    </Note>

    Once every file has been written and validated, merge the branch into the shared model. Use the `modelName` you saved from the step 1 response as the `<BRANCH_MODEL_NAME>` in the path:

    ```bash theme={null}
    curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models/<SHARED_MODEL_ID>/branch/<BRANCH_MODEL_NAME>/merge \
      -H "Authorization: Bearer <YOUR_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "delete_branch": true,
        "commit_message": "Bulk YAML import via API"
      }'
    ```

    Set `delete_branch: true` to clean up the branch after the merge succeeds.

    A successful response returns `success: true` and for git-enabled models, `git_synced: true`. This is the one git sync for the entire batch of updates.
  </Step>
</Steps>

## Next steps

* [Branch Mode](/content/develop/branch-mode) for the full concept overview and UI workflow equivalents
* [Omni API rate limiting](/api/rate-limits) to size your batch loop appropriately
* [Local development guide](/guides/modeling/local-development) for a CLI-driven alternative when you want to edit YAML in your IDE rather than scripting against the API


# Set up connection environments with the API
Source: https://docs.omni.co/guides/api/connection-environments

Configure dev and prod connection environments with the API.

<GuideSidebar />

<GuideTitle title="Set up connection environments with the API" />

Connection environments allow you to configure multiple database connections based on [user attributes](/administration/users/attributes). This is useful for scenarios where you need to provide different database access based on user roles or environments.

In this guide, we'll walk you through creating development and production connection environments.

## Requirements

To follow the steps in this guide, you'll need:

* An [Omni API key](/api/authentication)
* **Connection Admin** permissions on an existing Omni database connection

## Steps

<Steps>
  <Step title="Create the base connection">
    This is the default connection that will be used when no user attribute matches an environment connection. Use the [Create a connection API](/api/connections/create-connection) to create the connection.

    In this example, this would be a connection to your **development** database:

    ```bash title="POST /api/v1/connections" theme={null}
    curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/connections' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "dialect": "postgres",
      "name": "Postgres (Development)",
      "host": "postgres-dev.my-org.com",
      "port": 5432,
      "database": "dev",
      "username": "dbuser",
      "passwordUnencrypted": "mypassword",
      "includeSchemas": "public",
      "queryTimeoutSeconds": 900
    }'
    ```
  </Step>

  <Step title="Create environment connections">
    Environment conditions are additional connections with the same dialect as the base connection. Use the [Create a connection API](/api/connections/create-connection) to create the connection(s).

    In this example, this would be a connection to your **production** database:

    ```bash title="POST /api/v1/connections" theme={null}
    curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/connections' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "dialect": "postgres",
      "name": "Postgres (Production)",
      "host": "postgres-prod.my-org.com",
      "port": 5432,
      "database": "prod",
      "username": "dbuser",
      "passwordUnencrypted": "mypassword",
      "includeSchemas": "public",
      "queryTimeoutSeconds": 900
    }'
    ```
  </Step>

  <Step title="Connect the base and environment connections">
    Use the [Create connection environments API](/api/connection-environments/create-connection-environments) to associate the base connection with the environment connections. Provide the following:

    * `baseConnectionId` - The ID of the base connection. In this example, that's your **development** database.
    * `environmentConnectionIds` - The ID(s) of the connection environments. In this example, that's your **production** database.

    ```json title="POST /api/v1/connection-environments" theme={null}
    curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/connection-environments' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "baseConnectionId": "c0f12353-4817-4398-bcc0-d501e6dd2f64",
      "environmentConnectionIds": "b31f9c9f-208d-48a2-9ae3-ff80f2c79fed"
    }'
    ```
  </Step>

  <Step title="Configure the base connection user attribute">
    Use the [Update a connection API](/api/connections/update-connection) to specify which user attribute will be used to determine the connection environment.

    In this example, configure the base connection to use the `environment` user attribute and set its default value to `dev`:

    ```json title="PATCH /api/v1/connections/:id" theme={null}
    curl -L -X PATCH 'https://blobsrus.omniapp.co/api/v1/connections/c0f12353-4817-4398-bcc0-d501e6dd2f64' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "userAttributeNameForConnectionEnvironments": "environment",
      "userAttributeValuesForDefaultEnvironment": "dev"
    }'
    ```
  </Step>

  <Step title="Define user attribute values for environments">
    Use the [Update connection environment user attributes API](/api/connection-environments/update-connection-environment) to specify which user attribute values will trigger the use of each environment connection.

    In this example, set the user attribute values for the **production** environment connection to `prod`:

    ```json title="PUT /api/v1/connection-environments/:id" theme={null}
    curl -L -X PUT 'https://blobsrus.omniapp.co/api/v1/connection-environments/b31f9c9f-208d-48a2-9ae3-ff80f2c79fed' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "userAttributeValues": "prod"
    }'
    ```

    Now, users with the `environment` attribute set to `prod` will use the production database, while users with the `environment` attribute set to `dev` (or any other value not associated with an environment connection) will use the development database.
  </Step>
</Steps>


# Build a data lineage integration with the Omni API
Source: https://docs.omni.co/guides/api/data-lineage-integration

Build OpenMetadata / DataHub integrations using the Omni REST API

<GuideSidebar />

<GuideTitle title="Build a data lineage integration with the Omni API" />

Integrating Omni with metadata catalogs like OpenMetadata or DataHub allows you to visualize how data flows from raw database tables into Omni dashboards. By using the Omni REST API, you can construct a complete, queryable lineage graph that gives you a picture of how data is consumed across your organization.

The lineage will follow this structure:

```mermaid actions={false} theme={null}
flowchart LR
  A["Folder"] --> B["Dashboard"] --> C["Tile (Query)"] --> D["Topic"] --> E["View"] --> F["Database Table/Column"]
```

The approach in this guide is read-only and relies on endpoints that retrieve information from your Omni instance:

| Entity         | Endpoint                        | Purpose                                                  |
| :------------- | :------------------------------ | :------------------------------------------------------- |
| **Folders**    | `GET /v1/folders`               | Lists all top-level and nested folders.                  |
| **Documents**  | `GET /v1/documents`             | Lists dashboards and workbooks within a folder.          |
| **Queries**    | `GET /v1/documents/:id/queries` | Retrieves the underlying queries (tiles) for a document. |
| **Model YAML** | `GET /v1/models/:id/yaml`       | Retrieves the view definitions and SQL mappings.         |
| **Topics**     | `GET /v1/models/:id/topics`     | Lists the available entry points for exploration.        |

## Requirements

To follow the steps in this guide, you'll need:

* **Modeler** or **Connection Admin** permissions on the Omni model you want to work with
* [**A Personal Access Token**](/api/authentication#token-types) for the Omni API

## Steps

<Tip>
  **Remember to update example placeholders!** Throughout this guide, you'll see variables like `{your-omni-instance}` in code examples. These are placeholders that you'll need to replace with real values when you run the code yourself.
</Tip>

<Steps>
  <Step title="Retrieve a list of folders">
    Folders serve as the top-level nodes of your lineage graph. Use the [List folders](/api/folders/list-folders) endpoint to retrieve all folders in your organization.

    ```bash title="GET /api/v1/folders" theme={null}
    curl --request GET \
    --url 'https://{your-omni-instance}.omniapp.co/api/v1/folders' \
    --header 'Authorization: Bearer {your-omni-token}'
    ```

    The response from this endpoint uses cursor-based pagination. Loop until `pageInfo.hasNextPage` is `false`.

    Then, store the following fields:

    * `id` - Used to filter documents in the next step
    * `name` - The human-readable folder name
    * `url` - A direct link to the folder in Omni
  </Step>

  <Step title="List documents per folder">
    Next, you'll retrieve the documents in each folder.

    For every folder `id` you retrieved in the previous step, call the [List documents](/api/documents/list-documents) endpoint. Replace `{folder_id}` with the `id` of a folder:

    ```bash title=" GET /api/v1/documents?folderId={folder_id}" theme={null}
    curl --request GET \
    --url 'https://{your-omni-instance}.omniapp.co/api/v1/documents?folderId={folder_id}' \
    --header 'Authorization: Bearer {your-omni-token}'
    ```

    Then, store the following fields from the response - you'll use them to identify content items in a later step:

    * `identifier` - The document ID used in subsequent calls
    * `name` - The human-readable document name
    * `url` - A direct deep-link to the dashboard or workbook
    * `hasDashboard` - Indicates if the document contains tiles
    * `type` - Usually `document` for workbooks and dashboards
  </Step>

  <Step title="List queries per document">
    Next, you'll retrieve the queries in each document. Each tile on a dashboard corresponds to a workbook query.

    For every document `identifier` you retrieved in the previous step, call the [List document queries](/api/documents/list-document-queries) endpoint. Replace `{documentId}` with the `identifier` of a document:

    ```bash title="GET /api/v1/documents/{documentId}/queries" theme={null}
    curl --request GET \
    --url 'https://{your-omni-instance}.omniapp.co/api/v1/documents/{documentId}/queries' \
    --header 'Authorization: Bearer {your-omni-token}'
    ```

    The response will include a top-level `queries` object, which will contain a list of queries. For example:

    ```json title="Example response from the List document queries endpoint" theme={null}
    {
      "queries": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "Blobtastic Dashboard",
          "url": "https://{your-omni-org}.omni.co/w/abc123?key=1",
          "query": {...}
        }
      ]
    }
    ```

    The full `query` object isn't included here due to length, but you'll need to store the following fields from the response:

    * `url` - A direct deep-link to the specific tile/query
    * `query.table` - The Omni view reference in `schema__viewname` format (e.g., `ecomm__order_items`)
    * `query.fields` - Array of field references (e.g., `schema__viewname.field_name`)
    * `query.join_paths_from_topic_name` - The topic label (e.g., "Orders"). Identifies which topic the tile belongs to.
    * `query.modelId` - Use this ID when calling the Get model YAML endpoint in the next step
  </Step>

  <Step title="Resolve topics and views from model YAML">
    In this step, you'll map Omni objects to raw database tables using the model's underlying configuration.

    * **Topics** define the join graph and are the entry point for exploration
    * **Views** map to a database table or query.

    The `join_paths_from_topic_name` field identifies the topic, which usually shares the name of the base view.

    Because model logic is often split across multiple files, you'll start by finding the correct file path for a specific view.

    1. **Retrieve the view map**. Use the `modelId` from the previous step to call the [Get model YAML](/api/models/get-model-yaml) endpoint as follows:

       ```bash title="GET /api/v1/models/{modelId}/yaml" theme={null}
       curl --request GET \
       --url 'https://{your-omni-instance}.omniapp.co/api/v1/models/{modelId}/yaml' \
       --header 'Authorization: Bearer {your-omni-token}'
       ```

       The response will contain a `viewNames` map that indexes every view file path by its internal `schema__viewname` reference.
    2. **Locate the file in the map**. Search the map for the view name provided in the query (e.g., `ecomm__order_items`).

       <Note>
         **Omni supports two types of views.** Standard views map to physical tables, while [query views](/modeling/query-views) are promoted from saved queries. Check the `viewNames` map to determine if you need to request a `.view` or `.query.view` file.
       </Note>
    3. **Fetch the YAML for the file**. After you find the file name, use it in the `fileName` parameter to retrieve the file's YAML:

       ```bash title="GET /api/v1/models/{modelId}/yaml?fileName={schema_name}/{view_name}.view" theme={null}
       curl --request GET \
       --url 'https://{your-omni-instance}.omniapp.co/api/v1/models/{modelId}/yaml?fileName={SCHEMA_NAME}/{view_name}.view' \
       --header 'Authorization: Bearer {your-omni-token}'
       ```

       <Note>
         The `fileName` parameter is case-sensitive and requires the schema portion to be **uppercase** to resolve correctly (e.g., `ECOMM/order_items.view`).
       </Note>

    Once you have the specific YAML content, extract these fields from the response to complete the mapping from Omni to your database:

    * `table_name` - The physical table name in your database
    * `schema` - The database schema where the table resides
    * `dimensions` and `measures` - These blocks contain a `sql` property that defines which database columns are used for that field
  </Step>

  <Step title="Assemble the lineage graph">
    Once all data is collected, you can assemble the lineage graph:

    1. **Add deep links to the catalog**. Use the `url` fields returned directly in the response payloads to provide deep-links in your catalog:

       * **Folders** - `https://{your-omni-instance}.omniapp.co/f/{folder_id}`
       * **Documents** - `https://{your-omni-instance}.omniapp.co/dashboards/{document_id}`
       * **Tiles/Queries** - `https://{your-omni-instance}.omniapp.co/w/{document_id}?key={tile_key}`

       <Note>
         While URLs can be constructed manually, it's best practice to use the `url` property returned by the API as it handles the correct routing for different document types.
       </Note>

    2. **Create the graph**. Use the following diagram to assemble your graph. Each arrow represents a foreign-key relationship established through the API traversal you completed in previous steps.

       ```mermaid actions={false} theme={null}
       flowchart TD
         A["Folder (id, name)"] -->|"List documents (folderId filter)"| B["Dashboard / Document (identifier, name)"]
         B -->|"Get document queries"| C["Tile / Query (query id, table, fields)"]
         C -->|"join_paths_from_topic_name"| D["Topic (topic name = base view name)"]
         D -->|"Model YAML (view files)"| E["View (.view or .query.view YAML)"]
         E -->|"sql_table_name in view YAML"| F["Database table / column"]
       ```

       By parsing the `query.fields` array and comparing it to the `dimensions` and `measures` in your YAML, you can identify exactly which database columns drive each dashboard tile.

       <Tip>
         When building your graph, use the `identifier` or `id` fields as unique keys for each node to ensure updates or deletions in Omni are correctly reflected.
       </Tip>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can't access model / missing folders in API response">
    Personal Access Tokens have the same permissions as the user that created the token.

    If you can't access a model or you see folders missing in API responses, the user making the requests may not have permissions to those objects in Omni. Verify that the owner of the token has the correct permissions.
  </Accordion>

  <Accordion title="'Too many requests' error from API">
    If you receive a `429 too many requests error` from the API, you'll need to implement exponential backoff to avoid hitting the [rate limit](/api/rate-limits).
  </Accordion>

  <Accordion title="Folder or document responses are incomplete">
    The List folders and List documents endpoints use pagination in their responses, which means only a specific number of folders or documents are included per 'page'.

    If it seems like the response is incomplete, check the value of `pageInfo.hasNextPage` in the response. If `true`, you'll need to make subsequent requests and pass the `nextCursor` value as the `cursor` parameter to retrieve the next page of results.
  </Accordion>
</AccordionGroup>

## Next steps

* **Explore the API reference** - Review the full [API reference](/api) for endpoints used in this guide
* **Drafts and publishing** - Learn how to use [drafts](/content/develop/drafts) to stage model changes before deploying


# Port SQL queries into an Omni workbook via API
Source: https://docs.omni.co/guides/api/port-sql-queries-omni-api

Use a bash script to build Omni tabs and tiles via the Omni API.

<GuideSidebar />

<GuideTitle title="Port SQL queries into an Omni workbook via API" />

This guide shows you how to programmatically create an Omni workbook with multiple SQL-based tabs using a bash script. Automating workbook creation is helpful for generating standardized analysis templates or migrating queries from other systems into Omni.

## Requirements

To follow along with this guide, you'll need:

* [**An Omni API token**](/api/authentication)
* **To install `jq`**, which is a lightweight JSON processor. The script in this guide uses it to build and parse JSON payloads. Refer to the [jq documentation](https://jqlang.org/) for installation instructions.
* **The following information from your Omni instance**:
  * The subdomain of your Omni URL, for example `blobsrus`
  * The ID of the model you want to query

## Implementation

The following script uses `curl` to send a `POST` request to the [`/api/v1/documents` endpoint](/api/documents/create-document). It defines four distinct SQL queries and organizes them into a single workbook with specific visualization types: line charts, bar charts, and tables.

This part of the guide walks through different parts of the script and how they work. Refer to the [Run the script section](#run-the-script) for a full copy-pasteable version of the script.

<Steps>
  <Step title="Script configuration">
    The first part of the script contains your Omni information, which you'll need to define before running the script:

    * `OMNI_INSTANCE` - The subdomain of your Omni instance
    * `OMNI_API_TOKEN` - Your Omni API key
    * `MODEL_ID` - The ID of the model you want to query
    * `DOCUMENT_NAME` - The name of the document you'll create
    * `BASE_TABLE` - The name of an existing view in your Omni model. **This cannot be an arbitrary string**.

      <Note>
        Each query can point to a different base table. The examples in this guide all reference the same `order_items` table for simplicity, but one query could point to `orders` while another points to `products`.

        Omni recommends pointing to a view that is contextually related to the query being defined. While the field primarily serves as a reference point, using an unrelated view may produce unexpected behavior.
      </Note>

    ```bash title="Script configuration" lines theme={null}
    #!/bin/bash

    # =============================================================================
    # CONFIGURATION
    # =============================================================================

    OMNI_INSTANCE="your-instance"
    OMNI_API_TOKEN="XXXXX"
    MODEL_ID="your-model-uuid"
    DOCUMENT_NAME="Multi-Tab SQL Analysis"

    # Base table for connection context
    BASE_TABLE="order_items"
    ```
  </Step>

  <Step title="SQL queries">
    The **SQL queries** section defines the actual SQL queries that will be ported into the workbook.

    ```bash title="SQL queries" lines theme={null}
    # =============================================================================
    # SQL QUERIES
    # =============================================================================

    SQL_QUERY_1="SELECT DATE(created_at) as order_date, SUM(sale_price) as total_revenue FROM order_items GROUP BY 1"
    SQL_QUERY_2="SELECT product_category, SUM(sale_price) as total_sales FROM order_items GROUP BY 1 LIMIT 25"
    SQL_QUERY_3="SELECT status, COUNT(*) as order_count FROM order_items GROUP BY 1"
    SQL_QUERY_4="SELECT DATE_TRUNC('month', created_at) as month, SUM(sale_price) as revenue FROM order_items GROUP BY 1"
    ```
  </Step>

  <Step title="API request">
    <Tip>
      Use the **Model ID** found in the URL of your model IDE to ensure the workbook targets the correct data schema.
    </Tip>

    The **API request** portion of the script uses the information in the **Configuration** and **SQL queries** sections to build the curl request.

    The `queryPresentations` array defines the individual query tabs (tiles) within the workbook. Each query tab object contains a few parameters that are worth highlighting:

    * `isSql: true` - This parameter tells Omni to treat the `userEditedSQL` string as the primary source of truth for the query
    * `visConfig` - This parameter sets the default visualization style for the query tab, such as `line`, `bar`, or `table`

    The following snippet highlights these parameters in the script:

    ```bash title="API request" lines highlight={19,22,24} theme={null}
    # =============================================================================
    # API REQUEST
    # =============================================================================

    API_URL="https://${OMNI_INSTANCE}.omniapp.co/api/v1/documents"

    # Build JSON payload using jq
    JSON_PAYLOAD=$(jq -n \
      --arg modelId "$MODEL_ID" \
      --arg name "$DOCUMENT_NAME" \
      --arg table "$BASE_TABLE" \
      --arg sql1 "$SQL_QUERY_1" \
      --arg sql2 "$SQL_QUERY_2" \
      --arg sql3 "$SQL_QUERY_3" \
      --arg sql4 "$SQL_QUERY_4" \
      '{
        modelId: $modelId,
        name: $name,
        queryPresentations: [
          {
            name: "Daily Revenue",
            isSql: true,
            query: { table: $table, fields: [], userEditedSQL: $sql1 },
            visConfig: { chartType: "line" }
          },
          {
            name: "Top Products",
            isSql: true,
            query: { table: $table, fields: [], userEditedSQL: $sql2 },
            visConfig: { chartType: "bar" }
          },
          {
            name: "Order Status",
            isSql: true,
            query: { table: $table, fields: [], userEditedSQL: $sql3 },
            visConfig: { chartType: "table" }
          },
          {
            name: "Monthly Trends",
            isSql: true,
            query: { table: $table, fields: [], userEditedSQL: $sql4 },
            visConfig: { chartType: "area" }
          }
        ]
      }')

    # Send the request
    curl -X POST "$API_URL" \
      -H "Authorization: Bearer ${OMNI_API_TOKEN}" \
      -H "Content-Type: application/json" \
      -d "$JSON_PAYLOAD"
    ```
  </Step>
</Steps>

## Run the script

The following code example is a full copy-pasteable version of the script. To use it:

1. Save this version to a convenient location.
2. Replace the configuration variables with your Omni information.
3. Use the command line to run the script!

```bash title="Full copy-pasteable script version" expandable theme={null}
#!/bin/bash

# =============================================================================
# CONFIGURATION
# =============================================================================

OMNI_INSTANCE="your-instance"
OMNI_API_TOKEN="XXXXX"
MODEL_ID="your-model-uuid"
DOCUMENT_NAME="Multi-Tab SQL Analysis"

# Base table for connection context
BASE_TABLE="order_items"

# =============================================================================
# SQL QUERIES
# =============================================================================

SQL_QUERY_1="SELECT DATE(created_at) as order_date, SUM(sale_price) as total_revenue FROM order_items GROUP BY 1"
SQL_QUERY_2="SELECT product_category, SUM(sale_price) as total_sales FROM order_items GROUP BY 1 LIMIT 25"
SQL_QUERY_3="SELECT status, COUNT(*) as order_count FROM order_items GROUP BY 1"
SQL_QUERY_4="SELECT DATE_TRUNC('month', created_at) as month, SUM(sale_price) as revenue FROM order_items GROUP BY 1"

# =============================================================================
# API REQUEST
# =============================================================================

API_URL="https://${OMNI_INSTANCE}.omniapp.co/api/v1/documents"

# Build JSON payload using jq
JSON_PAYLOAD=$(jq -n \
  --arg modelId "$MODEL_ID" \
  --arg name "$DOCUMENT_NAME" \
  --arg table "$BASE_TABLE" \
  --arg sql1 "$SQL_QUERY_1" \
  --arg sql2 "$SQL_QUERY_2" \
  --arg sql3 "$SQL_QUERY_3" \
  --arg sql4 "$SQL_QUERY_4" \
  '{
    modelId: $modelId,
    name: $name,
    queryPresentations: [
      {
        name: "Daily Revenue",
        isSql: true,
        query: { table: $table, fields: [], userEditedSQL: $sql1 },
        visConfig: { chartType: "line" }
      },
      {
        name: "Top Products",
        isSql: true,
        query: { table: $table, fields: [], userEditedSQL: $sql2 },
        visConfig: { chartType: "bar" }
      },
      {
        name: "Order Status",
        isSql: true,
        query: { table: $table, fields: [], userEditedSQL: $sql3 },
        visConfig: { chartType: "table" }
      },
      {
        name: "Monthly Trends",
        isSql: true,
        query: { table: $table, fields: [], userEditedSQL: $sql4 },
        visConfig: { chartType: "area" }
      }
    ]
  }')

# Send the request
curl -X POST "$API_URL" \
  -H "Authorization: Bearer ${OMNI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"
```

## Next steps

Once you run the script, the API will return a JSON object containing a `workbook` identifier. You can navigate to `https://[instance].omniapp.co/dashboards/[identifier]` to view your new multi-tab analysis.


# Rotate Git SSH deploy keys with the API
Source: https://docs.omni.co/guides/api/rotate-ssh-deploy-keys

Use the API to rotate SSH deploy keys without interrupting Git operations.

<GuideSidebar />

<GuideTitle title="Rotate Git SSH deploy keys with the API" />

While Omni generates SSH deploy keys automatically when you connect a Git repository, you can also supply your own RSA or ED25519 private key via the API.

If you need to rotate keys—for example, to meet a compliance schedule—the API approach allows you to avoid downtime during the rotation. You first authorize the new public key with your Git provider, supply the private key to Omni, and then remove the unneeded public key from Git. This ensures that both keys work during the transition. The new key will take effect on the next Git operation.

## Requirements

To follow the steps in this guide, you'll need:

* An [Omni API key](/api/authentication)
* **Connection Admin** permissions on the model
* A Git-connected model using **SSH authentication**
* The shared model's `modelId`, which you can retrieve using the [List models](/api/models/list-models) endpoint
* `ssh-keygen` installed locally to generate keypairs

## Supported key types

Omni accepts RSA and ED25519 private keys in PEM format:

* **OpenSSH format** (default from `ssh-keygen`)
* **PKCS#1 format**
* **PKCS#8 format**

Keys can be passphrase-protected or unencrypted. When you supply an encrypted key, Omni uses the passphrase once to decrypt it, then stores the key under its own encryption at rest. The passphrase is not retained.

<Steps>
  <Step title="Generate a new keypair">
    Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

    <Tabs>
      <Tab title="ED25519">
        ```bash wrap theme={null}
        ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
        ```
      </Tab>

      <Tab title="RSA">
        ```bash wrap theme={null}
        ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
        ```
      </Tab>
    </Tabs>

    When prompted for a passphrase:

    * **To leave the key unencrypted**, press `Enter`.
    * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

    This generates two files:

    * `omni_deploy_key` — The private key, which you'll supply to Omni
    * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
  </Step>

  <Step title="Authorize the public key with your Git provider">
    Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

    <Tabs>
      <Tab title="GitHub" icon="github">
        1. In the GitHub repository, click the **Settings** tab.
        2. Click **Deploy keys**, located in the **Security** section of the sidebar.
        3. Click **Add deploy key**.
        4. Fill in the fields as follows:
           * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
           * **Key** -&#x20;
           * **Allow write access** -&#x20;
        5. Click **Add key**.
      </Tab>

      <Tab title="GitLab" icon="gitlab">
        1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
           <Note>
             GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
           </Note>
        2. Fill in the deploy key fields as follows:
           * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
           * **Key** -&#x20;
           * **Grant write permissions to this key** -&#x20;
        3. Click **Add key**.
      </Tab>

      <Tab title="Azure DevOps" icon="microsoft">
        1. Browse to the Azure DevOps web portal (ex: `https://dev.azure.com/<your-org-name>/`).
        2. Click the **User settings** icon next to your avatar in the top right corner of the page.
        3. Click **SSH public keys**.
        4. On the page that displays, click **+ New Key**.
        5. In the **Add New SSH Key** panel that displays, fill in the following:
           * **Name** - Enter a descriptive name, such as *Omni Snowflake Model*
           * **Public Key Data** -&#x20;
        6. Click **Add**.
      </Tab>

      <Tab title="Bitbucket Cloud" icon="cloud">
        Bitbucket Cloud access keys are read-only. To allow Omni to push changes, you'll need to add the SSH key to a user account with write access to the repository. We recommend using a service account for this purpose.

        1. Create a service account with write access to the repository.
        2. In the service account, navigate to **Personal Bitbucket settings > SSH keys**.
        3. Click **Add key**.
        4. Fill in the fields as follows:
           * **Label** - Give your new SSH key a descriptive label
           * **Key** -&#x20;
        5. Click **Add key** to save the key.
      </Tab>

      <Tab title="Bitbucket Data Center" icon="database">
        1. In the Bitbucket repository, click **Repository settings**.
        2. Click **Access keys**, located in the sidebar.
        3. Click **Add key**.
        4. Fill in the fields as follows:
           * **Key** -&#x20;
           * **Permission** - Select **Write** to allow Omni to push changes made in Omni to the repository
        5. Click **Add key**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Supply the private key to Omni with the API">
    Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

    <Tabs>
      <Tab title="Unencrypted keys">
        In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

        ```bash wrap theme={null}
        curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
          -H "Authorization: Bearer <YOUR_API_TOKEN>" \
          -H "Content-Type: application/json" \
          -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
        ```

        Replace the following variables:

        * `<your-subdomain>` - Your Omni subdomain
        * `<MODEL_ID>` - The shared model's UUID
        * `<YOUR_API_TOKEN>` - Your Omni API key

        A successful response will include the derived public key in the `publicKey` field.
      </Tab>

      <Tab title="Passphrase-protected keys">
        1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
        2. Run the following to create a plain shell variable for the passphrase:

           ```bash wrap theme={null}
           printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
           ```
        3. When prompted, enter the passphrase.
        4. Then, run the following to supply Omni with the private key and passphrase:

           ```bash wrap theme={null}
           curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
             -H "Authorization: Bearer <YOUR_API_TOKEN>" \
             -H "Content-Type: application/json" \
             -d "$(jq -n \
                   --arg key "$(cat omni_deploy_key)" \
                   --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                   '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
           ```

           Replace the following:

           * `<your-subdomain>` - Your Omni subdomain
           * `<MODEL_ID>` - The shared model's UUID
           * `<YOUR_API_TOKEN>` - Your Omni API key

           A successful response will include the derived public key in the `publicKey` field.
        5. After you receive a successful response, run the following to unset the passphrase variable:

           ```bash theme={null}
           unset DEPLOY_KEY_PASSPHRASE
           ```
      </Tab>
    </Tabs>

    <Tip>
      If you run into issues, see the [Troubleshooting section](#troubleshooting).
    </Tip>
  </Step>

  <Step title="Verify the new key works">
    To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

    Alternatively, call the [Sync model with Git repository](/api/model-git-configuration/sync-model-with-git-repository) endpoint:

    ```bash theme={null}
    curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git/sync \
      -H "Authorization: Bearer <YOUR_API_TOKEN>"
    ```

    If the connection test or sync succeeds, the new key is working correctly.
  </Step>

  <Step title="Remove the old key from your Git provider">
    Once you've confirmed the new key works, remove the old deploy key from your Git provider's settings.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="400 error: Invalid key format">
    The private key must be in PEM format (OpenSSH, PKCS#1, or PKCS#8) and be a valid RSA or ED25519 key. Common causes:

    * The key file is corrupted or incomplete
    * The key is in an unsupported format (for example, PuTTY `.ppk` format)
    * The key file contains extra whitespace or characters

    Regenerate the key with `ssh-keygen` and try again.
  </Accordion>

  <Accordion title="400 error: Wrong passphrase">
    The passphrase you provided does not match the passphrase used to encrypt the private key. Verify the passphrase and retry.

    If you've forgotten the passphrase, you'll need to generate a new keypair and start the rotation process again.
  </Accordion>

  <Accordion title="400 error: Encrypted key requires deployKeyPassphrase">
    The private key is passphrase-protected, but you didn't supply `deployKeyPassphrase` in the request. Either:

    * Provide the passphrase via the `deployKeyPassphrase` field
    * Or generate a new unencrypted key (press Enter when `ssh-keygen` prompts for a passphrase)
  </Accordion>

  <Accordion title="400 error: deployKeyPassphrase cannot be provided without deployPrivateKey">
    You included `deployKeyPassphrase` in the request body without `deployPrivateKey`. Remove `deployKeyPassphrase` or include `deployPrivateKey`.
  </Accordion>

  <Accordion title="400 error: deployPrivateKey not supported with authMethod: https_token">
    Custom deploy keys are only supported for SSH authentication. If your model uses HTTPS token authentication (`authMethod: https_token`), you cannot supply a custom deploy key. HTTPS token connections rotate via the `token` field instead.

    To use custom deploy keys, switch your model to SSH authentication.
  </Accordion>

  <Accordion title="Sync fails after rotation">
    If Git operations fail after rotating the key:

    1. Verify the public key was added to your Git provider with **write access**.
    2. Verify the public key in the API response matches the public key you added to your Git provider (compare the `publicKey` field in the response to the contents of `omni_deploy_key.pub`).
    3. Check your Git provider's webhook logs for authentication errors.

    If the issue persists, re-add the public key to your Git provider and retry the rotation.
  </Accordion>
</AccordionGroup>

## Next steps

* [Git integration settings](/integrations/git/settings) to configure pull request behavior, base branches, and more
* [Git integration overview](/integrations/git) for the full feature set
* [Update Git configuration API reference](/api/model-git-configuration/update-git-configuration) for all available fields


# Run document queries with the Query API
Source: https://docs.omni.co/guides/api/run-document-queries

Programmatically run document queries with the Omni API.

<GuideSidebar />

<GuideTitle title="Run document queries with the Query API" />

The [List document queries API](/api/documents/list-document-queries) provides information about documents and their associated queries. You can use these queries directly with the [Run query API](/api/queries) to programmatically run the document's queries.

## Requirements

To follow the steps in this guide, you'll need an [Omni API key](/api/authentication).

## Steps

<Steps>
  <Step title="Retrieve the document's queries">
    ```bash title="GET /api/v1/documents/:id/queries" theme={null}
    curl -L'https://<your-omni-org>.omniapp.co/api/v1/documents/12db1a0a/queries' \
    -H 'Authorization: Bearer <TOKEN>'
    ```
  </Step>

  <Step title="Extract a query object from the response">
    The query objects returned by the Document Queries API are already structured in the format required by the Query API, making it easy to run these queries programmatically without having to manually build the query structure.

    ```javascript theme={null}
    const document = response.body;
    const queryObject = document.queries[0].query;
    ```
  </Step>

  <Step title="Run the query">
    Use the query object directly with the [Run query API](/api/queries) to run the query:

    ```bash title="POST /api/v1/query/run" theme={null}
    curl -L -X POST 'https://<your-omni-org>.omniapp.co/api/v1/query/run' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": {
        "limit": 1000,
        "sorts": [
          {
            "column_name": "order_items.created_at[month]",
            "sort_descending": false
          }
        ],
        "table": "order_items",
        "fields": [
          "order_items.created_at[month]",
          "order_items.sale_price_sum"
        ],
        "filters": {},
        "modelId": "7155f419-a071-405c-8426-b4b5d3939049"
      }
    }'
    ```
  </Step>
</Steps>


# Enforce database RBAC in Omni with connection environments
Source: https://docs.omni.co/guides/connections/enforce-database-rbac

Use database-level roles to manage data access, audit logging, and resource allocation in Omni.

<GuideSidebar />

<GuideTitle title="Enforce database RBAC in Omni with connection environments" />

If your organization manages data access through database-level role-based access control (RBAC), you can enforce that same security model in Omni. By mapping each database role to a separate Omni connection and using [dynamic environments](/connect-data/dynamic-environments) with [user attributes](/administration/users/attributes), queries execute under the correct database role for each user — without requiring multiple models.

This approach assumes the underlying data structure is the same across all roles. Individual roles may have access to a subset of the data, but none should reference objects outside the primary connection's schema.

## Benefits

* **Row-level security**: Database policies applied to each role are enforced automatically, since Omni queries run as the connection's database user.
* **Audit logging**: Database logs reflect which role executed each query, providing a clear trail for compliance.
* **Resource management**: Assign different compute warehouses or resource pools to specific roles to manage performance and cost.

## Prerequisites

* Administrative access to your database to create roles and service accounts
* **Organization Admin** permissions in Omni

## Steps

<Steps>
  <Step title="Create the primary connection">
    Create a connection using credentials for the **most permissive role** — the one that is a superset of all other roles you plan to use. This connection will serve as the base for your model.

    Refer to the [Database setup guides](/connect-data/setup) for instructions specific to your data warehouse.
  </Step>

  <Step title="Create a connection for each additional role">
    For every additional database role you want to map, create a separate Omni connection using that role's service account credentials.

    Each connection must be the **same database type** as the primary connection. The schemas should be structurally identical — if a model references an object that doesn't exist in a role's connection, queries for users on that connection will fail.
  </Step>

  <Step title="Add role connections as environments">
    1. Navigate to the **primary connection's** settings page.
    2. Click the **Environments** tab.
    3. Click **New Environment** and select one of the role connections you created in the previous step.
    4. Repeat for each additional role connection.
    5. Click **Save**.

    For more details, see [Dynamically switching database environments](/connect-data/dynamic-environments).
  </Step>

  <Step title="Create the user attribute">
    Create a [user attribute](/administration/users/attributes) that will map each Omni user to their database role:

    1. Navigate to **Settings > Attributes**.
    2. Click **New Attribute**.
    3. Choose a **Reference** name that describes the role mapping (for example, `db_role`). You'll use this reference name when configuring the connection in the next step.
    4. Set a **Default Value** that corresponds to the primary connection's role, so users without an explicit assignment fall back to the default.
    5. Click **Save**.

    <Warning>
      Be careful when setting the default value. The default role determines what data unassigned users can access.
    </Warning>

    Then assign the appropriate value to each user. This can be done:

    * **Manually** in **Settings > Attributes > Users** tab
    * **Via the API** using the [User attributes API](/api)
    * **Via SCIM** through an identity provider like Okta, which can sync role assignments automatically
  </Step>

  <Step title="Enable dynamic environment assignment">
    1. Navigate back to the primary connection's **Environments** tab.
    2. Toggle **Allow environments to be assigned dynamically** to on.
    3. In the **User attribute** field, enter the reference name of the user attribute you created in the previous step.
    4. In the **Values for the default connection** field, enter the value that maps to the primary connection.
    5. For each environment connection, enter the user attribute value that should route users to that connection.
    6. Click **Update**.
  </Step>

  <Step title="Clean up extra models">
    When you created the additional connections in step 2, Omni may have auto-generated a model for each one. Since all roles share the primary connection's model, delete any models that were created for the non-primary connections.

    1. Navigate to **Settings > Connections**.
    2. Click the connection for one of the non-primary roles.
    3. If a model was auto-generated, click **Delete model** on the connection's settings page.
    4. Repeat for each non-primary connection.
  </Step>
</Steps>

## Next steps

* Verify the setup by [impersonating](/administration/users/impersonate) a user with a non-default role and running a test query
* Review your data models to confirm they don't reference objects that are unavailable to restricted roles
* If using an identity provider, configure SCIM to automatically sync role assignments as users are provisioned


# Filter dashboard charts with calculated fields
Source: https://docs.omni.co/guides/dashboards/calculated-field-filter

Create a dashboard filter using a calculated field in the underlying query.

<GuideSidebar />

<GuideTitle title="Filter dashboard charts with calculated fields" />

Instead of hardcoding row limits on charts, you can let dashboard viewers control how many items they see. For example, users could switch between viewing the top 10, top 15, or top 20 products by sales.

This guide walks through creating a dynamic Top N filter using a [`RANK`](/analyze-explore/calculations/math-number#rank) calculation and dashboard filter mapping.

## Requirements

* A dashboard that:
  * You have the ability to edit
  * Has at least one visualization tile
* Familiarity with [calculations](/analyze-explore/calculations)

## Steps

<Steps>
  <Step title="Add a calculated field to the query">
    In a **draft** workbook, add the calculation to the query that powers your chart. In this example, we added a `RANK` calculation that uses the value of the `Total Sold` column to rank results:

    <img alt="" />

    **Before continuing**, remove the row limit from the query if one is applied. The filter you're creating will control this instead.

    You can add the calculation manually or by using the Workbook Agent. Refer to the [Table calculations guide](/analyze-explore/calculations#create-table-calculations) if you need a refresher.
  </Step>

  <Step title="Create a numeric dashboard filter">
    1. Navigate to the dashboard by clicking the **Dashboard** button in the top right corner of the page.
    2. Click **Add > Filter**.
    3. For the filter source field, select any numeric field included in the query. In this example, we selected the `Total Sold` field.

       **Note**: This field only establishes the filter **type** - you'll map it to the calculation field in the next step.
    4. Give the filter a descriptive label.
  </Step>

  <Step title="Map the filter to the calculation">
    1. While still in the **Edit filter** panel, scroll to the **Filter mapping** section.

    2. Deselect tiles that don't contain the calculation. The filter should only apply to those that have the calculation.

    3. Search for the name of the calculation, or scroll down to the **Calculations** group. Select the calculation:
       <img alt="" />

    4. Verify that the tile is mapped to the calculation:

       <img alt="" />

    5. Click **Done** to save the filter.

    The filter will be added to the dashboard:

    <img alt="" />
  </Step>

  <Step title="Publish your changes">
    The last step is to publish the changes to the document. This will make the filter available for the viewers of your dashboard.

    Click the **Publish** button near the top right corner of the page.

    <Note>
      If you don't see the **Publish** button, your instance settings may not allow publishing without using a branch. Refer to the [Developing and publishing content guides](/content/develop) for more information.
    </Note>
  </Step>
</Steps>


# Dashboard best practices
Source: https://docs.omni.co/guides/dashboards/dashboarding-best-practices

Tips and patterns from the Omni team to help you build dashboards your whole org actually wants to use.

<GuideSidebar />

<GuideTitle title="Dashboard best practices" />

This guide covers nine core practices for designing dashboards in Omni, drawn from patterns we see across customers. Treat it as a starting place — not a checklist. Each section includes Omni-specific guidance and links to the relevant docs.

## Before you build

### 1. Know your audience

Every good dashboard starts with a person, not a dataset. Who's actually going to use this? A sales rep glancing at pipeline between calls has different needs than a finance analyst running a quarterly review. Build for one of them, not both at once.

Think about data fluency too. If your audience isn't used to slicing and dicing, lean toward clear labels, obvious filters, and a single clear takeaway per tile. If they're power users, give them room to explore — drill paths, controls, links to the underlying workbook. When in doubt, start simple and add complexity based on real feedback.

<Tip>
  Use [topics](/modeling/topics) to define what each audience can see. A sales topic can surface win rates and pipeline without touching margin data. A finance topic gets the full picture. Pair with [access grants](/modeling/develop/data-access-control) to enforce this automatically based on who's logged in — no parallel dashboards to maintain.
</Tip>

### 2. Start with a question, not a dataset

A lot of dashboards get built by staring at available data and asking "what could I show?" Flip it. Write down the two or three questions your audience is actually trying to answer, then build only what helps them answer those questions.

Specific questions produce better dashboards. "How is revenue trending?" gives you a line chart and not much else. "Which sales reps are at risk of missing quota this quarter, and in which product lines?" gives you something worth building.

<Tip>
  Not sure which metrics actually matter? Use the [Omni Agent](/ai/chat) to explore the data before committing to a layout. Ask questions in plain English, see what Omni pulls back, and use that as a signal for what belongs on the dashboard. From the chat, you can turn results into a dashboard in one click to get your foundation.
</Tip>

## Informed design

### 3. Match the chart to the question

The chart type is part of the answer. A bar chart that should be a line chart doesn't just look wrong — it actively obscures what you're trying to say. Omni picks a reasonable default when you run a query, but it's worth knowing the common patterns:

| Analysis type          | Recommended chart type                    |
| ---------------------- | ----------------------------------------- |
| Trends over time       | Line chart, area chart, or bar chart      |
| Comparison and ranking | Horizontal bar chart or bullet chart      |
| Correlation            | Scatter plot with trend line              |
| Geographic data        | Map paired with a ranked bar chart        |
| Part to whole          | 100% stacked bar chart (avoid pie charts) |
| Distribution           | Histogram or box plot                     |

Omni's chart picker previews your data in each format as you switch types — try bar vs. line vs. area before committing.

<Tip>
  For chart types beyond the standard library — Gantt charts, heatmaps, custom scatter plots — use [custom Vega-Lite visualizations](/visualize-present/visualizations/types/custom). For full design control over a tile, [Markdown visualizations](/visualize-present/dynamic-content) let you write HTML and CSS with dynamic data references.
</Tip>

### 4. Put the most important thing top-left

Eyes land in the upper-left and scan right then down — same as reading. Whatever your dashboard is really about should be there. Not a logo, not a date filter, not a decorative header. The number or chart that answers the main question.

A few principles to keep in mind:

* **Design for scanning patterns.** People typically scan in an "F" or "Z" pattern. Place high-level KPIs along the top and your most important trend chart in the top-left quadrant.
* **Establish visual hierarchy.** Use size and font weight to signal importance. The most critical number should be the largest; supporting text (like "vs. Last Year") should be smaller and lighter.
* **Group related tiles.** Related tiles should feel related — keep them physically close, use consistent sizing, and let whitespace do the separating. You rarely need borders or shading; spacing alone usually works better.

<Tip>
  A KPI tile or Markdown header pinned at the top lets executives get the answer before they even look at the charts. The [Omni showcase](/showcase) has examples worth stealing — check out the gradient card and data readout patterns.
</Tip>

### 5. Limit colors and charts, then theme consistently

Three to five charts per dashboard is a good starting point. If you're cramming in eight charts because they're all "relevant," you probably need two dashboards, not one big one. Same goes for color: every extra color is cognitive work for the viewer. Use color to encode meaning, not to make things look busy.

A couple of principles that tend to hold up:

* **Color is a functional alert, not decoration.** Reserve high-contrast colors (red/green, bright orange) for performance or status. Don't assign every category its own color — use shades of a single color or neutral tones to keep focus on actionable data.
* **The 90/10 rule.** Use a neutral palette (grays, light blues, muted tones) for 90% of dashboard elements. Reserve a single accent color — usually your brand's primary hex — for the remaining 10% to draw the eye to what matters.

| Don't                                   | Do                                            |
| --------------------------------------- | --------------------------------------------- |
| Put 8+ charts on one page               | Keep 3–5 focused charts per page              |
| Assign every category a different color | Use one color for a single dimension          |
| Use saturated, clashing palettes        | Apply a consistent palette across all charts  |
| Use color purely for aesthetics         | Use a muted base with one accent for emphasis |

#### Theming your dashboards

Once the layout is right, a well-applied theme is what takes a dashboard from "functional" to something people actually want to look at. Omni's [document themes](/administration/themes) give you control over color palettes, fonts, tile backgrounds, border styles, spacing, and more — applied across an entire workbook at once. Manage themes from **Settings > Themes > Document themes**, where you can create multiple themes and set a default that applies instance-wide, or apply a theme per-document for one-off needs. Set an org-wide default so every new dashboard starts on-brand.

<Tip>
  Not a CSS expert? Use AI to generate your theme config. Paste Omni's theme JSON template into ChatGPT or Claude and describe the look you want — including your company's hex colors, font preferences, and overall vibe. Iterate with follow-up prompts until it's right, then import the JSON directly into Omni. See the [community walkthrough](https://community.omni.co/t/easily-create-dashboard-themes-with-ai/278) for a step-by-step.
</Tip>

### 6. Emphasize what matters most

Axis labels, chart titles, legends — these only earn their space if they're adding information the viewer doesn't already have. If a label restates something obvious from the chart, remove it. If a legend has only one item, remove it. Less chrome means more signal.

On any given chart, the axes carry the most visual weight. Put your most important metric there. Color, size, and shape are for secondary dimensions — context without competition.

Whitespace matters too. Don't be afraid of empty space, and use [tabs](/visualize-present/dashboards) to separate themes of questions. Whitespace acts as a visual buffer, letting the viewer distinguish between groups of information without getting overwhelmed.

<Tip>
  Markdown tiles are one of the most underused features in Omni. A single sentence above a chart — "margins improved in Q3 but the East region is still lagging" — can do more work than any axis label. Pair with a KPI tile at the top to anchor the headline number.
</Tip>

## Interactivity

### 7. Add interactivity to encourage exploration

A dashboard that lets viewers answer their own follow-up questions is one they'll keep coming back to. The goal isn't to anticipate every question — it's to give people the right handles to pull so they can get there themselves.

That said, interactivity that isn't discoverable may as well not exist. If you add a control, make it obvious. Label filters with action-oriented text. Proximity is key — if a control only impacts one chart, place it where that's clear. For complex controls, drop a short Markdown tile nearby that explains what they do.

<Note>
  Filters added to a dashboard apply across all connected tiles at once. [Drill-to-explore](/visualize-present/dashboards) lets viewers click any data point to open the underlying workbook for full detail without leaving the dashboard. Cross-filtering — clicking a chart to filter other charts — is built in but needs to be turned on per dashboard under **Dashboard Settings**.
</Note>

#### Dashboard controls

Beyond standard filters, Omni's [dashboard controls](/visualize-present/dashboards/controls) give viewers structured ways to interact with data without leaving the dashboard. Controls are added in edit mode via **Add Control** and can be connected to one or many tiles at once.

* **Field switcher** — Swap one field for another. Let viewers toggle between Revenue, Orders, and Margin on the same chart.
* **Multi-field picker** — Select zero or more fields to show in a tile. Especially useful for table visualizations.
* **Time frame switcher** — Change date granularity (day / week / month / quarter) without editing the underlying query.
* **Period over period** — Compare a metric across two time periods, like this month vs. last month.
* **Parent control** — Coordinate multiple controls at once. Useful when tiles share different date fields that should move together.
* **Dynamic text tiles** — Reference the current control or filter value in a Markdown tile using `{{controls.<id>.value}}` syntax.

<Tip>
  Controls can be hidden from viewers while still being driven by a parent control. This lets you build clean, minimal dashboards where one dropdown coordinates multiple underlying field switchers — with no clutter.
</Tip>

### 8. Build for self-service, not just self-sufficiency

There's a difference between a dashboard that answers questions and one that helps people answer their own. The first requires someone on the data team to anticipate everything. The second gives viewers room to dig in without breaking anything.

The goal isn't to expose everything — it's to expose the right things. Well-scoped topics, default filters, and clear drill paths cover 80% of questions. For the other 20%, [Chat with Content](/ai/dashboard-assistant) means viewers can just ask in plain English, right on the dashboard, without pinging the data team.

<Note>
  Link tiles directly to a scoped Omni workbook using the dashboard link feature — viewers who want to go deeper can, without you having to build another dashboard. [Create mode](/embed/customization/create-mode) takes this further: power users can build and save their own analyses off the shared model, completely independently.
</Note>

## Refining your dashboard

### 9. Complete the story with AI, summaries, and tooltips

A well-built dashboard still leaves interpretation work on the table. What does that dip in March mean? Is that trend significant? Tooltips, labels, and written context help — but Omni's AI features can take this further, doing the interpretation work automatically so viewers spend less time puzzling over charts and more time acting on them.

#### Tooltips and labels

Tooltips show up at exactly the moment someone wants more context — make that moment count. Lead with the thing they're actually asking about (the metric, the dimension), not field names that mean nothing outside the data model. And if you can answer the question with a mark label instead of a hover, do that — it's one less interaction required.

A good rule of thumb: if a viewer can understand the key insight without touching the chart at all, the chart is working. Interactivity is a bonus, not a crutch.

#### AI Summary tiles

Drop an [AI Summary tile](/visualize-present/visualizations/types/ai-summary) onto a dashboard to generate a plain-language interpretation of what the data shows — automatically. It updates as filters change, so an executive filtering to their region gets a summary specific to their view, not a generic one written when the dashboard was built.

<Tip>
  Enable **Read data result** in [**AI Hub > General > Features**](/ai/settings/features#read-result-data) to let the Omni Agent analyze actual query results. Once on, add a Summary tile from the dashboard edit panel. The Omni Agent can call out anomalies, direction of trends, and notable comparisons — the kind of commentary that would otherwise require a data analyst to write.
</Tip>

#### Chat with Content

[Chat with Content](/ai/dashboard-assistant) makes conversational analytics available directly inside every published dashboard. Viewers can ask follow-up questions in plain English, request a different cut of the data, or ask what a number means — without opening a workbook or pinging the data team. It's available via the icon in the bottom-right corner once enabled.

<Note>
  Two settings need to be on before you can use Chat with Content:

  1. **Read data result** — [**AI Hub > General > Features**](/ai/settings/features#read-result-data)
  2. **AI on dashboard** — **File > Document Settings**, or globally in **Settings > General > Content permissions**

  You can also customize the agent's name and icon in [**AI Hub > General > Branding**](/ai/settings/branding) — handy if you're embedding Omni and want it to feel native to your product.
</Note>

### Test for usability, then share

Before publishing, walk through your dashboard as if you've never seen it. Can you answer the core question within 30 seconds? Do the filters and controls work as expected? Are there any blank states that might confuse a viewer?

Then test with a real member of your audience — watch where they click first, what confuses them, and what questions they ask that the dashboard doesn't yet answer.

<Warning>
  Don't assume people will find their way to a dashboard on their own — they won't. Set up a [scheduled delivery](/share/deliveries) via email, Slack, or Google Sheets to push it to them on a cadence that makes sense. If something is worth building, it's worth making sure people actually see it.
</Warning>

## Getting it in front of people

A dashboard nobody sees is a dashboard that doesn't exist. Omni gives you several ways to close that last mile — from scheduled pushes to embedded experiences to on-demand answers in Slack.

* **[Scheduled deliveries](/share/deliveries)** — Email, Slack, or Google Sheets on a custom cadence.
* **[Alerts](https://omni.co/blog/using-alerts-for-operational-workflows-in-omni)** — Notify stakeholders when a KPI crosses a threshold.
* **[Embedded dashboards](/embed)** — Signed iframe in any product or internal tool.
* **[PDF / CSV export](https://omni.co/demos/20240322#dashboard-pdf-and-csv-downloads)** — One-click export for stakeholders who prefer offline.
* **[Omni Slack Agent](https://docs.omni.co/integrations/omni-slack-agent)** — Answer data questions without opening Omni.

## A note on performance

Omni is designed to be fast out of the box. Because queries are defined and aggregated in the shared model and pushed down to your warehouse, most dashboards load quickly without optimization work.

If you do hit slow load times, Omni's [Dashboard performance profiler](/visualize-present/dashboards/performance-profiler) helps diagnose the cause. Open the dashboard, click **View > Performance profile**, and the profiler opens as a side panel showing query timing, caching behavior, and result sizes for each tile — with specific guidance on where to focus.

<Note>
  Common performance improvements include reducing the default date range on high-volume tables, defining aggregations in the model rather than the dashboard, and using `default_filters` on topics to limit the initial result set. For very large datasets, consider pre-aggregating in your warehouse with a [dbt model](/integrations/dbt/models).
</Note>


# Embed dbt data health tiles in Omni dashboards
Source: https://docs.omni.co/guides/dashboards/dbt-data-health-tiles

Embed dbt data health tiles (formerly status tiles) in Omni dashboards to show data freshness and quality at a glance.

<GuideSidebar />

<GuideTitle title="Embed dbt data health tiles in Omni dashboards" />

[dbt data health tiles](https://docs.getdbt.com/docs/explore/data-tile) - formerly called dashboard status tiles - display the freshness and quality of the data behind a dashboard. Embedding a health tile in an Omni dashboard gives your stakeholders at-a-glance confirmation that the data they're looking at is fresh and passing quality checks, with a deep link into dbt Catalog for investigating issues.

In Omni, health tiles are embedded using an iframe in a [text (Markdown) tile](/visualize-present/dashboards/text-markdown).

<Frame>
  <img alt="An Omni dashboard with an embedded dbt data health tile showing a Healthy status, with passing data freshness and data quality checks and a link to see more details in dbt" />
</Frame>

Each tile displays the health signals dbt tracks for the exposure backing your dashboard:

* **Freshness status**, such as `Data is fresh`, based on source freshness checks
* **Quality status**, such as `Data quality passed`, based on test results
* A breakdown of upstream source and model health, with links into dbt Catalog for debugging

## Requirements

To follow the steps in this guide, you'll need:

* **Permission to edit the Omni dashboard** where you'll add the tile
* **For dbt**:
  * **A dbt account on the Enterprise or Enterprise+ plan.** Refer to the [dbt data health tile documentation](https://docs.getdbt.com/docs/explore/data-tile) for current plan requirements.
  * **A dbt exposure for your dashboard** with `type: dashboard`, defined manually or [pushed from Omni](/integrations/dbt/exposures)
  * **Source freshness enabled** in the dbt job that generates the exposure
  * **A Metadata Only service token**, created by a dbt account admin in **Account Settings > API tokens > Service tokens**
    <Note>
      This token will be part of the iframe URL, so anyone who can view the dashboard's Markdown tile source can see it. Only use a **Metadata Only** service token, which limits access to dbt metadata and can't modify your dbt account.
    </Note>

<Steps>
  <Step title="Copy the iframe snippet from dbt">
    1. In dbt, navigate to the exposure for your dashboard.
    2. Copy the embed snippet. It will look similar to the following:

       ```html wrap theme={null}
       <iframe src='https://<YOUR_ACCOUNT_PREFIX>.metadata.<REGION>.dbt.com/exposure-tile?uniqueId=exposure.<EXPOSURE_NAME>&environmentType=production&environmentId=<ENV_ID_NUMBER>&token=<YOUR_METADATA_TOKEN>' title='Exposure status tile'></iframe>
       ```
    3. Replace the placeholder URL values (e.g., `<YOUR_ACCOUNT_PREFIX>`). Refer to the [dbt documentation](https://docs.getdbt.com/docs/explore/data-tile) for details on each URL parameter.
  </Step>

  <Step title="Add the iframe to an Omni dashboard">
    1. In Omni, navigate to the dashboard you want to work with.
    2. Click **Edit** to enter draft mode.
    3. Add a [text tile](/visualize-present/dashboards/text-markdown) to the dashboard.
    4. Paste the iframe snippet from step 1 into the Markdown editor. To make the dbt health tile fill the dashboard text tile instead of rendering at a fixed size, wrap the iframe in a positioned container:

       ```html wrap theme={null}
       <div style="position:relative;width:100%;height:100%;">
         <iframe
           style="position:absolute;inset:0;width:100%;height:100%;border:0;"
           src="https://YOUR_ACCOUNT_PREFIX.metadata.REGION.dbt.com/exposure-tile?uniqueId=exposure.EXPOSURE_NAME&environmentType=production&environmentId=ENV_ID_NUMBER&token=YOUR_METADATA_TOKEN"
           title="Exposure status tile"
           scrolling="no"></iframe>
       </div>
       ```
    5. When finished, publish the dashboard.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The tile doesn't render or appears blank">
    * **Check the URL parameters**. The exposure `uniqueId`, `environmentId`, and token must all be valid. Regenerate the snippet from dbt if you're unsure.
    * **Check the token type**. The token must be a **Metadata Only** service token.
    * **Check for sandboxing limitations**. Omni applies [sandboxing restrictions](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#:~:text=to%20insecure%20origins.-,sandbox,-Controls%20the%20restrictions) when rendering iframes, which can make some website features unavailable.
  </Accordion>

  <Accordion title="The tile renders but shows no health data">
    * **Verify the exposure exists** in the environment referenced by the URL and has `type: dashboard`.
    * **Verify source freshness is enabled** in the dbt job that generates the exposure. Without it, freshness status can't be reported.
  </Accordion>
</AccordionGroup>

## Next steps

* [Push exposures to dbt](/integrations/dbt/exposures) — Generate the dbt exposures that health tiles are built on directly from your Omni dashboards.
* [Markdown visualizations](/visualize-present/visualizations/types/markdown) — Learn about iframes and other options available in Markdown visualizations.


# Choosing your deployment
Source: https://docs.omni.co/guides/deployment/choosing-your-deployment

This guide will help you to identify the right Omni deployment pattern for your environment based on your infrastructure, team structure, and content governance requirements

<GuideSidebar />

<GuideTitle title="Choosing your deployment" />

Omni offers a range of deployment options, from a single-instance setup to multi-instance, multi-region architectures. This guide helps you identify the right starting point based on your actual requirements.

**Our recommendation: Start with the simplest architecture that meets your requirements.** The vast majority of teams can accomplish what they need within a [single Omni instance](/guides/deployment/single-instance-git-dbt). Multi-instance deployments add operational overhead — they're worth it when the requirements genuinely call for them, and not before.

## What's your primary requirement?

<AccordionGroup>
  <Accordion title="I need to safely develop and test model changes before they affect production users">
    **→ [Single instance deployment with git and dbt](/guides/deployment/single-instance-git-dbt)**

    This is the most common Omni deployment. A single instance with git integration gives you branch-based development, pull request workflows, and the Content Validator — everything you need to manage changes safely without running a separate production environment.

    If you're using dbt, the same guide covers connecting your dbt project and syncing metadata into the model.
  </Accordion>

  <Accordion title="I need separate development/staging and production databases and need to validate changes against non-production data">
    **→ [Single instance deployment with dynamic database environments](/guides/deployment/single-instance-dynamic-connections)**

    Dynamic connection environments let your developers switch to a staging database within an Omni branch — so model changes can be tested against non-production data without maintaining a separate Omni instance.

    This is the right choice when:

    * You have `analytics_prod` and `analytics_dev` databases
    * All developers are allowed to see both databases
    * You don't need true environment isolation between developers and production users
  </Accordion>

  <Accordion title="I have strict separation requirements between development/staging and production environments within a single region">
    **→ [Multiple instance deployment with git follower](/guides/deployment/multi-instance-prod-stage)**

    When you need two fully isolated Omni environments — one where development happens and one where production users live — a two-instance git follower setup is the right architecture. Developers work entirely in staging; production is updated only through deliberate git-based promotions.

    This is the right choice when:

    * Organizational policy prohibits developers from having production access
    * You need a stable, read-only production environment
    * You want to preview full model and content state in a production context before going live
  </Accordion>

  <Accordion title="I have strict separation requirements for development, staging and production environments and/or handling environments across multiple geographic regions">
    **→ [Multiple instance deployment with multiple regions](/guides/deployment/multi-instance-multi-region)**

    For teams with data residency requirements or globally distributed operations, the multi-region pattern extends the two-instance architecture into a full matrix of environments and regions. It's the most operationally robust pattern — reserve it for situations where it's genuinely required.

    This is the right choice when:

    * Regulations require data to reside in specific geographic regions
    * You need DEV, STAGE, and PROD isolation across US, EU, and other regions simultaneously
    * Your team has the operational capacity to manage nine (or more) Omni instances
  </Accordion>
</AccordionGroup>

## How much review does your content need?

<AccordionGroup>
  <Accordion title="Minimal review (Agile teams)">
    Use standard Omni permissions — apply view, edit, and manage rights by folder and group. The [branch/publish workflow](/content/develop/branch-mode) provides a natural review gate without enforcing it.
  </Accordion>

  <Accordion title="High review (Waterfall teams)">
    Enable [**Require pull requests**](/integrations/git/settings) in git settings. This blocks direct commits to your default branch and requires all model changes to go through a PR. For content, you can additionally enable [**Require PR to publish**](/integrations/git/settings) at the document level — this prevents any published document from being updated without a reviewed PR.
  </Accordion>

  <Accordion title="Mixed review — some content 'can't break' (Agile and Waterfall teams)">
    Use document-level [**Require PR to publish**](/integrations/git/settings) selectively on your highest-stakes dashboards, while leaving standard draft/publish behavior on everything else.
  </Accordion>

  <Accordion title="High review — production environment is read-only (Waterfall teams)">
    Use a [multi-instance setup with git follower](/guides/deployment/multi-instance-prod-stage). Production users see only the promoted, validated state of your model and content.
  </Accordion>
</AccordionGroup>

## How do you manage database schema changes?

<AccordionGroup>
  <Accordion title="Additive changes on a single connection">
    Standard schema refresh works well. Use [soft refreshes](/modeling/develop/schema-refreshes) (additive only) for routine updates. Run a full [hard refresh](/modeling/develop/schema-refreshes) only when you need to remove references to dropped objects.
  </Accordion>

  <Accordion title="Schema changes with git branch protection enabled">
    Enable [**branch-based schema refresh**](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) on your connection. This routes schema refreshes through a branch before they can be merged, preventing the force-push that a regular schema refresh would require.
  </Accordion>

  <Accordion title="Changes from a staging database">
    Open a branch, switch to your staging connection through [dynamic environments](/connect-data/dynamic-environments), trigger the schema refresh there, and validate before merging.
  </Accordion>

  <Accordion title="High-frequency programmatic schema updates">
    Use the [schema refresh API](/api/models/refresh-schema), [Agent Skills](/developers/agent-skills), or [CLI](/developers/cli) to trigger refreshes from your pipeline and for bulk model updates in a local IDE workflow.
  </Accordion>
</AccordionGroup>

## How should you scope data access across your team?

| Scenario                                                                 | Recommended approach                                                                                                  |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| One data team, some row-level security                                   | [Single model](/guides/deployment/single-instance-git-dbt) with [access rules](/modeling/develop/data-access-control) |
| Multiple departments with shared core logic + department-specific fields | [Model extensions (shared extension models)](/modeling/develop/shared-extensions)                                     |
| Multi-tenant embedded analytics, one database, schemas per customer      | [Dynamic schemas](/connect-data/dynamic-environments)                                                                 |
| Multi-tenant embedded analytics, separate databases per customer         | [Dynamic connection environments](/connect-data/dynamic-environments)                                                 |
| Multi-region with data residency requirements                            | [Multiple Omni organizations](/guides/deployment/multi-instance-multi-region) (separate instances per region)         |
| Sensitive internal data that BI admins shouldn't see                     | Two separate Omni tenants                                                                                             |

## How do you structure both internal and embedded (external) users?

The right answer depends on whether internal and external users share the same data or need complete isolation:

* **Shared data, different access rules:** A single instance with user attributes and row-level security handles this well. Use [model extensions](/guides/deployment/scaled-deployments-shared-model-extensions) if external customers need customized views.
* **Separate databases per customer:** [Dynamic connection environments](/connect-data/dynamic-environments) plus model extensions is the standard embedded pattern.
* **Full isolation between internal and external:** Consider separate Omni instances for internal and embedded deployments, using [git follower](/integrations/git/follower-mode/index) to keep models in-sync.

## Decision tree summary

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px'}}}%%
flowchart LR
    A([Start]) --> B

    B{"Multiple Omni instances needed?"}

    B -->|No| C
    B -->|Yes| F

    C{"Separate staging database?"}

    C -->|Yes| D["Single instance + dynamic connections"]
    C -->|No| E["Single instance + git (+ dbt if applicable)"]

    F{"What is the scope?"}

    F -->|"Two instances (PROD / STAGE)"| G["Multi-instance PROD/STAGE with git follower"]
    F -->|"Multiple environments + regions"| H["Multi-instance multi-region"]

    style A fill:#272D6D,color:#fff,stroke:none

    style B fill:#272D6D,stroke:#3F4755,stroke-width:3px,color:#fff
    style C fill:#3F4755,stroke:#3F4755,stroke-width:3px,color:#fff
    style F fill:#3F4755,stroke:#3F4755,stroke-width:3px,color:#fff

    style D fill:#FF5789,color:#fff,stroke:none
    style E fill:#FF5789,color:#fff,stroke:none
    style G fill:#AA3F6B,color:#fff,stroke:none
    style H fill:#AA3F6B,color:#fff,stroke:none
```

## Deployment pattern guides

* [Single instance deployment with git and dbt](/guides/deployment/single-instance-git-dbt)
* [Single instance deployment with dynamic database environments](/guides/deployment/single-instance-dynamic-connections)
* [Multiple instance deployment with git follower (Prod/Stage)](/guides/deployment/multi-instance-prod-stage)
* [Multiple instance deployment across multiple regions](/guides/deployment/multi-instance-multi-region)


# Deploying Omni: Multiple instances across multiple regions
Source: https://docs.omni.co/guides/deployment/multi-instance-multi-region

Manage a full DEV/STAGE/PROD deployment across multiple geographic regions using git follower mode — for enterprise teams with data residency requirements or globally distributed operations

<GuideSidebar />

<GuideTitle title="Deploying Omni: Multiple instances across multiple regions" />

This guide covers the most complex Omni deployment pattern: multiple environments (DEV, STAGE, PROD) across multiple geographic regions, where each environment/region combination is a separate Omni instance.

[Git follower mode](/integrations/git/follower-mode/index) keeps all instances in each environment synchronized, and deliberate git-based promotions move changes between environments.

This architecture is appropriate when:

* Data residency regulations require Omni to run in specific geographic regions (e.g., US, EU, Canada)
* You manage a globally distributed user base where each region requires its own Omni organization
* You need three-tier environment isolation (DEV → STAGE → PROD) across all regions

## Architecture overview

A three-region, three-environment deployment has nine logical instances. One region (typically your primary region, e.g., US) designates one development instance as the *origin* — the single source of all development activity.

Each environment tier tracks a different git branch:

| Environment | Git base branch | Instances                                                      |
| ----------- | --------------- | -------------------------------------------------------------- |
| DEV         | `dev`           | US DEV (origin / leader), EU DEV (follower), CA DEV (follower) |
| STAGE       | `stage`         | US STAGE (leader), EU STAGE (follower), CA STAGE (follower)    |
| PROD        | `main`          | US PROD (leader), EU PROD (follower), CA PROD (follower)       |

<Frame>
  <img alt="Diagram of a nine-instance deployment: three environments (DEV, STAGE, PROD), each with a US leader and EU and CA followers" />
</Frame>

<Note>
  Each Omni organization is hosted in a single geographic region. To operate across multiple regions, you must maintain a separate Omni organization account per region. Contact your Omni account team to provision additional regional organizations.
</Note>

<Tip>
  This architecture can be simplified if your use case does not have the hard requirement of DEV and STAGE in each region. Additionally, multiple git repositories can be used.
</Tip>

Promotions between environments happen through pull requests in git:

* **DEV → STAGE**: PR from `dev` branch into `stage` branch
* **STAGE → PROD**: PR from `stage` branch into `main` branch

When a PR merges into an environment's base branch, the follower instances in that environment automatically receive the model update. Content is not promoted automatically; it must be migrated separately (see [Git follower mode](#git-follower-mode) below).

## Git follower mode

[Git follower mode](/integrations/git/follower-mode/setup) designates one Omni model as the *leader* and others as read-only *followers* that automatically update when changes merge from the leader's base branch into the follower's base branch through a pull request. See [git follower mode](/integrations/git/follower-mode/index) for the full mechanism.

This guide outlines the process for a single git repository; the configuration is similar if regional git repositories are required. The origin DEV, STAGE, and PROD Omni instances hold the leader models.

Development branches are opened from DEV and STAGE, their changes are tested, and PRs target the respective branch (`dev` or `stage`). When you're ready to promote to production, create a release branch in git that carries the changes from `stage` into production's base branch (e.g., `main`). The follower models automatically detect the new branch from the origin (leader) production instance and create a matching branch, which is validated before merging.

Git follower mode promotes model changes only. Content (workbooks and dashboards) must be migrated separately using the Content Migration APIs, [agent skills](/developers/agent-skills), or [Omni CLI](/developers/cli).

## Requirements

Before you begin:

* Nine Omni instances across three regions and three environments (or the subset your team needs)
* **Organization Admin** permissions on all instances
* **Connection Admin** permissions on each instance's model connections
* A single git repository in GitHub, GitLab, or Azure DevOps shared across all instances
* Three base branches in that repository: `dev`, `stage`, and `main`
* Permissions in your git provider to add webhooks and deploy/SSH keys (nine sets — one per instance)
* Structurally identical schemas across all databases in all regions and environments

## Initial setup

* In this configuration, there are nine logical instances (three regions × three environments).
* One region's development instance acts as the origin for all development, with all other regions configured with [git follower](/integrations/git/follower-mode/setup).
* Each SDLC stage points to a different branch in git: `dev`, `stage`, and `main` (for prod).

<Info>
  This guide uses the US region as the origin for illustrative purposes.
</Info>

## Development workflow - US DEV (origin)

All development happens on the **US DEV origin instance**. Other instances in the DEV environment automatically stay in-sync.

<Steps>
  <Step title="Open a branch">
    From the **DEV** model IDE, create a new branch. Make model and content changes on this branch.
  </Step>

  <Step title="Validate with the Content Validator">
    Run the [Content Validator](/modeling/develop/content-validator) on your branch to surface any broken references before promoting.
  </Step>
</Steps>

## Deployment workflow - US DEV (origin)

<Steps>
  <Step title="Merge model changes to US DEV">
    Merge your changes to the  **DEV** (the origin instance) shared model:

    * **With pull requests required** (recommended):
      * Open a PR to `dev` and merge after review. This publishes attached content **on the US DEV origin instance only**.
      * **Without pull requests**: Merge the branch directly from the model IDE.

    When changes merge to `dev`, the EU DEV and CA DEV follower instances automatically receive the model update. 

    <Note>
      Content changes (published workbooks and dashboards) are **not** automatically propagated to EU DEV and CA DEV via [git follower.](/integrations/git/follower-mode/index) Git follower syncs **model changes only**. To replicate content across regional DEV instances, use the Content Migration APIs.
    </Note>
  </Step>

  <Step title="Deploy content to EU DEV and CA DEV">
    As git follower only promotes model changes, and if content is required to be deployed to DEV followers, use the content migration APIs, the [agent skills](/developers/agent-skills) or [Omni CLI](/developers/cli) to promote content across instances prior to promoting model changes.

    <Tip>
      It's a best practice to consider your folder structures and their mapping between environments. This can be accomplished with Content, Folders, and Documents APIs.
    </Tip>

    <AccordionGroup>
      <Accordion title="New content?">
        Use the [get-document-state](/api/documents-v2/get-document-state) endpoint to create a copy of the content. Use [create-document](/api/documents-v2/create-document) endpoint to create a new document on the target environment that will also be published.

        <Warning>
          You may also consider using the [get-draft-state](/api/documents-v2/get-draft-state) endpoint when migrating a draft.  Viewing data, ownership, schedules and history will NOT transfer to the copy and will need to be updated separately.
        </Warning>
      </Accordion>

      <Accordion title="Updating content?">
        If the document already exists, use [create-draft-and-patch-document](/api/documents-v2/create-draft-and-patch-document) to create the draft  of the published version and then the [publish-draft](/api/documents-v2/publish-draft) endpoint to publish it. You may also consider [patch-draft](/api/documents-v2/patch-draft) for further patch iterations on a draft. 
      </Accordion>
    </AccordionGroup>

    <Tip>
      Migrate content after the model promotion is confirmed in the target environment. This ensures the target's model is in the correct state before any content references it.
    </Tip>
  </Step>
</Steps>

### Promotion workflow - US DEV to US STAGE

Because git follower is being used and **US DEV** is leader to followers **EU DEV** and **CA DEV**,  all dev model changes propagate to EU DEV and CA DEV. Promoting dev to stage requires moving those changes from `dev` to `stage` via pull request.

<Steps>
  <Step title="Create release branch in git">
    * In git repository
      * Create a new branch off of the base branch(`dev`) (e.g. `release-to-stage-YYYYMMDD`) 
      * Create a pull request that merge your changes into the follower’s base branch (`stage`in git)
      <Tip>
        Make sure the **Always create branches** setting is enabled in Omni, as it will create a branch in Omni with the same name.
      </Tip>
  </Step>

  <Step title="Migrate content from US DEV to US STAGE instance">
    If content needs to be deployed to the US STAGE instance, follow the same directions outlined in step #2 (**Deploy content to EU DEV and CA DEV**) of the **Deployment workflow - US DEV (origin)** section above, making sure to update to staging targets.
  </Step>

  <Step title="Review changes in the Omni US STAGE instance">
    * In the Omni STAGE instance
    * Open the <Tooltip>model</Tooltip>
    * Open the `release-to-stage-YYYYMMDD` branch
    * Test the changes by reviewing the [Content Validator](/modeling/develop/content-validator#content-validator-basics) for any issues
  </Step>

  <Step title="Merge the release branch into the base stage branch">
    * In git repository:
      * Merge the pull request in git to merge the release branch changes into the base branch (e.g. `stage`)
        <Note>
          Because git follower is enabled between `dev` and `stage`, the follower regions (EU STAGE and CA STAGE) will receive the update
        </Note>
    * At this point, your model changes are live in the staging instance
  </Step>

  <Step title="Deploy content to EU STAGE and CA STAGE">
    If content needs to be deployed to STAGE followers, follow the same directions outlined in step #2 (**Deploy content to EU DEV and CA DEV**) of the **Deployment workflow - US DEV (origin)** section above, making sure to update to staging targets.
  </Step>
</Steps>

## Promote from US STAGE to US PROD

Because git follower is being used, and **US STAGE** is leader to followers **EU STAGE** and **CA STAGE**, all stage model changes propagate to EU STAGE and CA STAGE. Promoting stage to prod requires moving those changes from `stage` to `prod` through a pull request.

<Steps>
  <Step title="Create release branch in git">
    * In git repository
      * Create a branch off of the base branch `stage` (e.g. `release-to-prod-YYYYMMDD`)
      * Create a pull request that merges your changes into the follower's base branch (`main` or `prod` in git)
      <Tip>
        Make sure the “Always create branches” setting is enabled in Omni as it will create a branch in Omni with the same name
      </Tip>
  </Step>

  <Step title="Migrate content from US STAGE to US PROD instance">
    If content needs to be deployed to US PROD, follow the same directions outlined in step #2 (**Migrate content from US DEV to US STAGE instance**) of the **Promote from US DEV to US STAGE** section above, making sure to update to production targets.
  </Step>

  <Step title="Review changes in the Omni PROD instance">
    * In the Omni PROD instance
    * Open the <Tooltip>model</Tooltip>
    * Open the `release-to-prod-YYYYMMDD` branch
    * Test the changes by reviewing the [Content Validator](/modeling/develop/content-validator#content-validator-basics) for any issues
  </Step>

  <Step title="Merge the release branch into the base main branch">
    * In git repository:
      * Merge the pull request in git to merge the release branch changes into the base branch (likely `main` or `prod` in git)
        <Note>
          Because git follower is enabled between `stage` and `prod`, the follower regions (EU PROD and CA PROD) will receive the update
        </Note>
    * At this point, your model changes are live in the production instance
  </Step>

  <Step title="Deploy content to EU PROD and CA PROD">
    If content needs to be deployed to PROD followers, follow the same directions outlined in step #2 (**Deploy content to EU DEV and CA DEV**) of the **Deployment workflow - US DEV (origin)** section above, making sure to update to production targets.
  </Step>
</Steps>

## Schema refreshes across instances

When your source databases change, each instance needs a schema refresh to incorporate the updates. In a nine-instance setup, this requires nine separate refresh operations (or [API-triggered refreshes](/api/models/refresh-schema)).

<Warning>
  Coordinate schema changes across regions carefully. All databases should receive schema updates before any schema refreshes are triggered in Omni, so that model state across instances stays consistent.
</Warning>

## Permissions model

| Instance type             | Developer access             | Content consumer access |
| ------------------------- | ---------------------------- | ----------------------- |
| **US DEV** (origin)       | Full branch and model access | Test / internal only    |
| **Regional DEV** (EU, CA) | Read-only or limited         | Test / internal only    |
| **STAGE** (all regions)   | Read-only                    | QA / preview            |
| **PROD** (all regions)    | No direct access             | Primary audience        |

## Best practices

### Treat the origin instance as the single source of truth

All model development, all branch work, and all PR activity targeting `dev` should happen on the US DEV origin instance. Working directly on regional DEV follower instances creates drift and model conflicts.

### Keep all nine schemas structurally identical

The shared model definition flows across all nine instances. Schema differences between regions or environments will cause modeling errors when a promotion reaches an instance with a divergent schema. Coordinate schema migrations across all databases before triggering Omni promotions.

### Use a consistent release branch naming convention

A format like `release-to-stage-YYYYMMDD` or `release-to-prod-YYYYMMDD` makes promotions traceable and rollbacks straightforward.

### Plan content migration per release

Content migration to nine instances is operationally significant. Build it into your release process with a clear checklist of which content needs to move, to which instance, and in what order. Automate where possible using the Content Migration APIs.

## Next steps

* [git follower mode setup](/integrations/git/follower-mode/setup) — Detailed reference for configuring git follower
* [git follower mode best practices](/integrations/git/follower-mode/best-practices) — Managing follower workflows at scale
* [Migrating dashboards](/visualize-present/dashboards/migrate) — Migrating content across instances and regions
* [Content Validator](/modeling/develop/content-validator) — Validating content before and after promotions


# Deploying Omni: Multiple instances (Prod/Stage)
Source: https://docs.omni.co/guides/deployment/multi-instance-prod-stage

Set up and manage separate staging and production Omni instances using git follower mode — the recommended pattern for teams that require full environment isolation

<GuideSidebar />

<GuideTitle title="Deploying Omni: Multiple instances (Prod/Stage)" />

This guide covers a two-instance Omni deployment: a **staging instance** where all active development happens, and a **production instance** that receives promoted changes through git. The production instance uses git follower mode to stay in-sync with staging's main branch.

This setup provides true environment isolation — developers work entirely in staging, and production is only updated through a deliberate, git-controlled promotion process. It is the recommended approach for teams that need:

* A stable, read-only production environment that cannot be affected by in-progress development
* Strict control over what reaches production and when
* Full separation of developer and end-user data access

## Git follower mode

[**Git follower mode**](/integrations/git/follower-mode/setup) lets you centralize model development by designating one Omni model as a **leader** and another as a **follower**. The follower is read-only and automatically updates when changes are merged from the leader's base branch into the follower's base branch through a pull request. This is useful for creating dev/production environments or deploying a model across multiple regions or organizations.

The staging instance holds the **leader model**: all development branches are opened here, all changes are tested here, and all PRs target staging's `main` branch. When you're ready to promote to production, you create a release branch in git that carries the changes from staging's `main` into production's base branch (e.g., `prod`). The production instance's follower model automatically detects this branch and creates a matching Omni branch, which you validate before merging.

Git follower mode promotes model changes only. Content (workbooks and dashboards) must be migrated separately to production using the content migration APIs, the [agent skills](/developers/agent-skills) or [Omni CLI](/developers/cli).

## Requirements

Before you begin:

* Two separate Omni instances: one for staging, one for production
* **Organization Admin** permissions on both instances
* **Connection Admin** permissions on both models' connections
* A staging database and a production database of the same type (e.g., both Snowflake) with identical schemas
* A git repository in GitHub, GitLab, or Azure DevOps
* Permissions in your git provider to add webhooks and deploy/SSH keys

## Architecture overview

|                            | Staging instance                        | Production instance                             |
| -------------------------- | --------------------------------------- | ----------------------------------------------- |
| **Role**                   | Leader — all development and validation | Follower — read-only, receives promoted changes |
| **Database**               | Staging database                        | Production database                             |
| **Git base branch**        | `main`                                  | `prod` (or equivalent)                          |
| **Git follower mode**      | Disabled                                | Enabled                                         |
| **Always create branches** | Not required                            | Required                                        |
| **Content**                | Builds and tests content                | Hosts live content (migrated through API)       |

## Initial setup

1. Create production database connection in production Omni instance
2. Create staging database connection in staging Omni instance 
3. Set up the git integration on each instance
   * In staging, you’ll be pointed to the `main` branch
   * In production, you’ll check the box for “Git Follower” and point to a separate base branch (e.g. `prod` - make sure you configure this in git as well)

## Development workflow (staging)

All development happens on the stage instance which acts as the **leader**.

<Steps>
  <Step title="Open a branch">
    From the  **staging** instance model IDE, create a new branch. Make model and content changes on this branch.
  </Step>

  <Step title="Validate with the Content Validator">
    Run the [Content Validator](/modeling/develop/content-validator) on your branch to surface any broken references before promoting.

    <Tip>
      Run the Content Validator before opening a pull request. Catching broken references early keeps your PR focused on model logic, not cleanup.
    </Tip>
  </Step>
</Steps>

## Deployment workflow (staging)

<Steps>
  <Step title="Merge model changes to STAGE ">
    Merge your changes to the shared model of STAGE (the leader instance)

    * **With pull requests required** (recommended):
      * Open a PR to `main` and merge after review. This publishes attached content **on the leader instance only**.
    * **Without pull requests**: Merge the branch directly from the model IDE.

    <Note>
      Content changes (published workbooks and dashboards) are **not** automatically propagated to the production instance through [git follower.](/integrations/git/follower-mode/index) Git follower syncs **model changes only**. To replicate content across instances, use the content migration API.
    </Note>
  </Step>
</Steps>

## Promotion workflow (staging to production)

Because STAGE is **leader** to follower **PROD**, the changes in stage's `main` need to be moved to `prod` through a pull request.

<Steps>
  <Step title="Create release branch in git">
    * In git repository
      * Create a branch off of the base branch of stage (`main`) (e.g. `release-to-prod-YYYYMMDD`). This pull request wraps all "followed" changes into the newly created branch.
      * Create a pull request that merges your changes into the follower's base branch (`prod` in git)
      <Tip>
        Make sure the “Always create branches” setting is enabled in Omni as it will create a branch in Omni with the same name
      </Tip>
  </Step>

  <Step title="Migrate content from STAGE to PROD instance">
    As git follower only promotes model changes, use the content migration API to promote content across instances prior to promoting model changes.

    <Tip>
      It's a best practice to consider your folder structures and their mapping between STAGE and PROD. This can be accomplished with Content, Folders, and Documents APIs.
    </Tip>

    <AccordionGroup>
      <Accordion title="New content?">
        Use the [get-document-state](/api/documents-v2/get-document-state) endpoint to create a copy of the content. Use [create-document](/api/documents-v2/create-document) endpoint to create a new document on PROD that will also be published.

        <Warning>
          You may also consider using the [get-draft-state](/api/documents-v2/get-draft-state) endpoint when migrating a draft.  Viewing data, ownership, schedules and history will NOT transfer to the copy and will need to be updated separately.
        </Warning>
      </Accordion>

      <Accordion title="Updating content?">
        If the document already exists, use [create-draft-and-patch-document](/api/documents-v2/create-draft-and-patch-document) to create the draft  of the published version and then the [publish-draft](/api/documents-v2/publish-draft) endpoint to publish it. You may also consider [patch-draft](/api/documents-v2/patch-draft) for further patch iterations on a draft. 
      </Accordion>
    </AccordionGroup>

    <Tip>
      Migrate content after the model promotion is confirmed in production. This ensures the PROD model is in the correct state before any content references it.
    </Tip>
  </Step>

  <Step title="Review changes in the Omni PROD instance">
    * In the Omni PROD instance
      * Open the model. The PROD model is read-only due to git follower settings, so you review changes here but don't edit them.
      * Open the `release-to-prod-YYYYMMDD` branch
      * Test the changes by reviewing the [Content Validator](/modeling/develop/content-validator#content-validator-basics) for any issues
  </Step>

  <Step title="Merge the release branch into base prod branch">
    * In git repository:
      * Merge the pull request in git to merge the release branch changes into the base branch (likely `prod`)
    * At this point, your model changes are live in the production instance
  </Step>
</Steps>

## Permissions considerations

Structuring permissions across two instances keeps the production environment clean and reduces the risk of accidental changes.

| Role                      | Staging instance                | Production instance             |
| ------------------------- | ------------------------------- | ------------------------------- |
| **Developers / Modelers** | Full branch and model access    | Read-only or no access          |
| **PR approvers**          | Controlled through git provider | Controlled through git provider |
| **Content consumers**     | Testing and preview             | Primary audience                |

Consider restricting developer access to the production instance to read-only. Changes to the production model should only arrive through the git promotion process, not through direct Omni access.

## Best practices

### Mirror your database schemas

The shared model is the same across both instances — it doesn't know which instance it's in. If your staging and production schemas diverge (different tables, columns, or data types), model references that work in staging will break in production after promotion. Keep schemas structurally identical.

### Use a consistent release branch naming convention

A format like `release-to-prod-YYYYMMDD` makes it straightforward to identify in-flight promotions, track the history of what landed in production and when, and quickly roll back by reverting the PR.

### Plan content migration as part of your release checklist

Content migration is often skipped under time pressure. Build it explicitly into your release process — document which content needs to move with each release and trigger migration before announcing changes are live to end users.

### Refresh the production schema after promotion

After merging a release, perform a schema refresh on the production model to ensure the schema matches staging. This is especially important after releases that include database schema changes.

## Next steps

* [git follower mode setup](/integrations/git/follower-mode/setup) — Detailed reference for git follower configuration
* [git follower mode best practices](/integrations/git/follower-mode/best-practices) — Recommendations for managing follower workflows
* [Migrating dashboards](/visualize-present/dashboards/migrate) — How to migrate content across instances using the API
* [Content validator](/modeling/develop/content-validator) — How to validate and repair content after model changes


# Deploying Omni at scale with shared model extensions
Source: https://docs.omni.co/guides/deployment/scaled-deployments-shared-model-extensions

Learn how to use Shared Model Extensions to manage large Omni deployments across multiple data teams.

<GuideSidebar />

<GuideTitle title="Deploying Omni at scale with shared model extensions" />

When you manage multiple departments or distributed data teams, a centralized modeling approach can become a bottleneck. By leveraging a layered system of connections and models, you can empower individual teams to own their data products while you preserve core governance.

This is especially relevant if:

* Your verticalized teams need to own their own data models
* Your central data team is overwhelmed by team-specific metric requests
* You provide custom metrics for external tenants
* You need region-specific localizations or cache policies without altering the core model

This guide walks through a layered architecture for scaling Omni across multiple teams — from choosing how to organize your database connections, to building a governed shared model as your foundation, to letting individual teams extend that model for their own needs. It also covers how to use folders and permissions to control who sees what.

## Structure connections for scale

The first layer of your architecture is the [database connection](/connect-data). Since each [model](/modeling) in Omni is tied to a single database connection, the way you organize your connections directly shapes how you'll structure your models.

There are two common patterns for connecting databases at scale:

1. **One database per model**: Each database gets its own connection and shared model. This gives you the most isolation — teams can work independently — but it also means managing more models. Use [shared model extensions](#extend-the-shared-model) to let teams customize without duplicating the core model.
2. **Dynamic connections, one model**: Use [dynamic connections](/connect-data/dynamic-environments) to route users to different database connections (e.g., production vs. staging, or region-specific replicas) while sharing a single model definition. Be aware that tables must be structurally consistent across environments, or you'll see validation errors.

Regardless of which pattern you choose, you can also use [OAuth](/connect-data/oauth) to delegate access control to your warehouse. If your database — like Snowflake — already manages user-level permissions, OAuth lets those flow directly into Omni so you don't need to duplicate access controls in the semantic layer. The tradeoff is that OAuth bypasses the shared cache, which means queries will rely solely on the performance of your database.

<img alt="Diagram showing three patterns for connecting multiple databases in Omni" />

## Extend the shared model

In a distributed organization, your core data team typically governs the **shared model** — the canonical source of truth — while departmental analysts manage [**shared model extensions**](/modeling/develop/shared-extensions). Extensions let teams modify logic in a "forked" environment against the same database connection without affecting the parent model.

Extensions inherit everything from the upstream shared model by default, so they're additive — if you need to exclude specific objects, you'll need to manually hide them. This makes getting started with extensions straightforward, but keep these governance considerations in mind:

* **Upstream logic can be overwritten**: Users with edit permissions to an extension can overwrite any logic from the upstream model, including data access policies. Establish clear ownership and review processes for extension changes.
* **Connection-level access still applies**: Developers can access all views allowed by the underlying connection credentials, regardless of what the model exposes. Keep this in mind when scoping connection permissions.
* **Performance at scale**: As your model grows, use [offloaded schemas](/connect-data/offloading-schemas) to defer loading metadata for specific schemas until they're explicitly needed. This keeps the field browser responsive.

<img alt="Diagram showing how to configure shared model extensions" />

## Manage version control

<Warning>
  Full Git support for [extension models](/modeling/develop/shared-extensions) is a work in progress. Currently, Git workflows only apply to the base shared model — extensions use Omni's native branching.
</Warning>

If your organization uses Git, you can [integrate it with Omni](/integrations/git) to manage version control for your shared model. When planning your repository structure, there are three common strategies:

| Strategy           | Description                                                                | Best for                                                                              |
| :----------------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| **Monorepo**       | Parent model and extensions live in one repo; use `CODEOWNERS` for control | Teams that need visibility across models and want to manage dependencies in one place |
| **Isolated repos** | Separate repo per model                                                    | Teams that need strict isolation and independent release cycles                       |
| **Hybrid**         | Sensitive extensions use isolated repos; others use a monorepo             | Organizations balancing security requirements with cross-team collaboration           |

### How Git syncing works

Since Git isn't yet native to extensions, it's important to understand how Omni interacts with your repository:

* **Extensions store diffs, not full models**: Extensions use extension-only mode, recording only changes relative to the parent. This keeps your repo clean but means you can't reconstruct an extension without its parent.
* **Syncs occur only on merge**: Omni monitors for merges to the `main` branch and copies those changes to its internal record. Changes on other branches won't appear until they're merged.
* **Branching may behave differently than expected**: Omni uses its own internal database for version control, so branch behavior may not match standard Git workflows exactly.

## Manage content access

With your shared model and extensions in place, the next step is making sure the right people can access the right content.

### Control document access with folders

[Folders](/content/organize#folders) are the primary mechanism for controlling who can see and interact with your content. Understanding how permissions cascade from folders to documents will help you design a folder structure that scales with your team.

* **Permissions flow downward**: Workbooks and dashboards inherit permissions from their parent folder. You can grant *broader* access at the document level, but you can't make a document more restrictive than its folder — so plan your folder structure around your most restrictive access needs first.
* **Visibility is model-aware**: Users only see documents associated with models they have permission to access. For workbooks that pull from multiple topics, users will see charts from their authorized topics but get an error for any charts tied to topics they can't access — so avoid mixing broadly-shared and restricted topics in a single workbook when possible.

<img alt="Diagram showing shared model extension access control" />

### Increase permissions with AccessBoost

In a scaled deployment, you may have dashboards intended for a broad audience — like executives or external stakeholders — who don't need to build their own queries but do need to see results from topics or fields they wouldn't normally have access to.

[AccessBoost](/share#boosting-permissions-with-accessboost) solves this by selectively elevating permissions at the **dashboard** or **folder** level. This allows users with lower-level [connection roles](/administration/users/permissions) - like **Restricted Querier** or **Viewer** — to view all data on a boosted dashboard, even content built with SQL they wouldn't normally have access to.

## Next steps

* [Set up your database connection](/connect-data) and choose a connection pattern
* [Create shared model extensions](/modeling/develop/shared-extensions) for your departmental teams
* [Configure Git integration](/integrations/git) for your shared model
* [Organize content with folders](/content/organize#folders) to manage access across teams


# Deploying Omni: Single instance with dynamic connections
Source: https://docs.omni.co/guides/deployment/single-instance-dynamic-connections

Set up and manage Omni in a single instance with dynamic connection environments for development and production database switching

<GuideSidebar />

<GuideTitle title="Deploying Omni: Single instance with dynamic connections" />

This guide covers the single-instance dynamic connections deployment pattern: a single Omni instance that routes developers to separate development and production databases using dynamic connection environments. Use this when your team needs to test model changes against non-production data without maintaining a separate Omni instance.

## When to use this approach

* You have [a single Omni instance](/guides/deployment/single-instance-git-dbt)
* You have separate PROD and DEV/STAGE databases (e.g., `analytics_prod` and `analytics_dev`)
* All developers are allowed to see both databases
* You don't need true environment isolation between developers and production users

For setup, see [dynamic connection environments](/connect-data/dynamic-environments).

## Requirements

Before you begin, make sure you have:

* An existing database connection in Omni with [dynamic connection environments](/connect-data/dynamic-environments) configured
* The [git integration](/integrations/git/setup/github) set up for your Omni instance
* **Organization Admin** permissions in Omni (required for git settings)
* **Connection Admin** permissions in Omni

## Development workflow

<Note>
  With git connected, all model development in Omni happens on [branches](/content/develop/branch-mode). This keeps your shared model stable while changes are built, tested, and reviewed.
</Note>

<Steps>
  <Step title="Open a branch">
    From the Omni model IDE, create a new branch. Give it a descriptive name that matches your work. If you're making dbt changes in parallel, use the same branch name in both repositories to keep them in-sync.
  </Step>

  <Step title="Make your changes">
    On the branch, you can:

    * Add or edit fields, dimensions, measures, and views in the model IDE
    * Update topics and joins
    * Build and edit workbooks and dashboards — these are automatically attached to your branch
    * With dynamic connections, switch the active connection environment from within the branch: when you create a branch, Omni shows an option to change the environment from the primary (production) connection to your non-production environment. Run and validate queries against non-production data before merging.
      <Frame>
        <img alt="Switching the active database connection from within an Omni branch" />
      </Frame>

    If your changes depend on a new or updated dbt model, [sync the dbt metadata](/modeling/develop/schema-refreshes) first so the latest fields are available on the branch.
  </Step>

  <Step title="Validate with the Content Validator">
    Before deploying, run the [Content Validator](/modeling/develop/content-validator) to check whether your model changes break any existing content. The Content Validator surfaces broken field references across all workbooks and dashboards and lets you find and replace them in bulk before deploying.

    <Tip>
      Run the Content Validator before opening a pull request, not after. Catching broken references early keeps your PR review focused on model logic, not cleanup.
    </Tip>

    When the validator reports no broken references, your branch is ready to deploy.
  </Step>
</Steps>

## Deploy your changes

When your changes are ready, the deployment path depends on whether you've enabled  [Require pull requests](/integrations/git/settings) in your git settings.

### With pull requests required (recommended)

<Steps>
  <Step title="Add changes to your branch">
    Click **Add to branch** to stage your shared model changes. Any changes not shared to the branch will remain in the workbook.

    <Frame>
      <img alt="The Add to Branch button in Omni's model IDE" />
    </Frame>
  </Step>

  <Step title="Confirm the impact">
    Review the staged changes in the branch summary and confirm they're ready to promote. These changes affect everyone who accesses the shared model.

    <Frame>
      <img alt="Staged model changes shown in the branch summary" />
    </Frame>
  </Step>

  <Step title="Open pull request">
    In your git provider, open a pull request targeting `main` (or your default branch).

    <Frame>
      <img alt="Opening a pull request from Omni" />
    </Frame>
  </Step>

  <Step title="Add details to the pull request">
    Add notes to your pull request and assign reviewers in git as needed.

    <Frame>
      <img alt="The open pull request screen in your git provider" />
    </Frame>
  </Step>

  <Step title="Pull request review">
    Have your changes reviewed and approved in git.

    <Frame>
      <img alt="Reviewing and approving the pull request" />
    </Frame>
  </Step>

  <Step title="Merge the pull request">
    Merge the pull request and delete the branch (optional).

    <Frame>
      <img alt="The merged and closed pull request in git" />
    </Frame>
  </Step>
</Steps>

Merging the PR promotes model changes to the shared model and publishes any content (workbooks, dashboards) that were attached to the branch. Both happen in a single merge.

### Without pull requests required

<Steps>
  <Step title="Add changes to your branch">
    Click **Add to branch** to stage your shared model changes.
  </Step>

  <Step title="Merge to the shared model">
    From the Omni model IDE, merge your branch directly to the shared model. This promotes model changes and publishes attached content in one step.
  </Step>
</Steps>

<Warning>
  Merging directly to the shared model bypasses peer review. For teams where model accuracy and stability matter, enabling **Require pull requests** is strongly recommended.
</Warning>

## Next steps

* [git integration settings reference](/integrations/git/settings) — Full reference for all git configuration options
* [git integration best practices](/integrations/git/best-practices) — Branch protection, monorepo setup, and more
* [dbt integration overview](/integrations/dbt) — Feature overview including dbt Semantic Layer and dynamic schema switching
* [Branch Mode](/content/develop/branch-mode) — How branching works for both model and content changes
* [Content Validator](/modeling/develop/content-validator) — How to validate and repair content after model changes


# Deploying Omni: Single instance deployment with git and dbt
Source: https://docs.omni.co/guides/deployment/single-instance-git-dbt

Set up and manage Omni in a single instance, single connection environment with git version control and dbt integration — the most common Omni deployment pattern.

<GuideSidebar />

<GuideTitle title="Deploying Omni: Single instance deployment with git and dbt" />

This guide covers the most common Omni deployment pattern: a single Omni instance connected to a single database, with git for model version control and dbt for semantic layer metadata.

If you're setting up Omni for the first time and your team uses dbt, start here.

This setup gives you:

* Structured model development and review through git branches and pull requests
* dbt metadata (descriptions, foreign key constraints) surfaced automatically in Omni
* A safe development workflow where changes are staged, validated, and merged before going live

## Requirements

Before you begin, make sure you have:

* An existing database connection in Omni
* **Organization Admin** permissions in Omni (required for git settings)
* **Connection Admin** permissions for the target connection (required for dbt setup)
* An existing git repository in GitHub, GitLab, Bitbucket, or Azure DevOps
* Permissions in your git provider to add webhooks and deploy/SSH keys
* A dbt project with an accessible git repository

## Set up the git integration

The [git integration](/integrations/git/setup/github) connects your Omni shared model to a git repository, enabling branch-based development and pull request workflows for model changes.

<Note>
  [Branch Mode](/content/develop/branch-mode) is required to make changes to the shared model when the git integration is enabled. All model changes must be made on a branch.
</Note>

## Set up the dbt integration

The [dbt integration](/integrations/dbt/setup) connects your dbt project to an Omni database connection. Once connected, Omni syncs dbt metadata — including field descriptions, foreign key constraints, and dbt Semantic Layer definitions — into your model automatically.

## Development workflow

<Note>
  With git and dbt connected, all model development in Omni happens on [branches](/content/develop/branch-mode). This keeps your shared model stable while changes are built, tested, and reviewed.
</Note>

<Steps>
  <Step title="Open a branch">
    From the Omni model IDE, create a new branch. Give it a descriptive name that matches your work. If you're making dbt changes in parallel, use the same branch name in both repositories to keep them in-sync.
  </Step>

  <Step title="Make your changes">
    On the branch, you can:

    * Add or edit fields, dimensions, measures, and views in the model IDE
    * Update topics and joins
    * Build and edit workbooks and dashboards — these are automatically attached to your branch

    Schema refreshes only pick up dbt models that already exist in your warehouse. If your change depends on a new or updated dbt model, build it in your warehouse first, then run a [schema refresh](/modeling/develop/schema-refreshes) so the latest fields are available on the branch.
  </Step>

  <Step title="Validate with the Content Validator">
    Before deploying, run the [Content Validator](/modeling/develop/content-validator) to check whether your model changes break any existing content. The Content Validator surfaces broken field references across all workbooks and dashboards, and lets you find and replace broken references in bulk before deploying.

    <Tip>
      Run the Content Validator before opening a pull request, not after. Catching broken references early keeps your PR review focused on model logic, not cleanup.
    </Tip>

    When the validator reports no broken references, your branch is ready to deploy.
  </Step>
</Steps>

## Deploy your changes

Once your branch passes validation, deploy it. The steps below depend on whether **Require pull requests** is enabled in your [git settings](/integrations/git/settings#pull-request-required). You set this during git integration setup and can change it at any time.

### With pull requests required (recommended)

<Steps>
  <Step title="Add your model changes to your branch in Omni">
    In the model IDE, click **Add to branch** to stage your in-progress model edits onto the current branch.

    <img alt="Add To Branch" />
  </Step>

  <Step title="Open a pull request">
    In your git provider, open a pull request from your Omni branch into `main` (or your default branch).

    <img alt="Open Pull Request Git Screen" />
  </Step>

  <Step title="Have your changes reviewed and approved in git">
    Request a review from your team. The PR must be approved before it can be merged.

    <Frame>
      <img alt="Pr Review And Approve" />
    </Frame>
  </Step>

  <Step title="Merge the pull request and delete the branch">
    Merge the PR into `main` and delete the branch. Merging promotes the model changes to the shared model and publishes any content attached to the branch.

    <img alt="Pr Merged And Closed" />
  </Step>
</Steps>

### Without pull requests required

With **Require pull requests** disabled, you can stage and merge model changes directly from the IDE in two steps.

<Steps>
  <Step title="Add your changes to the branch">
    With your branch open, click **Add to branch** to stage your changes.
  </Step>

  <Step title="Merge to the shared model">
    Click **Merge to shared model**. This promotes model changes and publishes attached content in one step.
  </Step>
</Steps>

1. With your branch open, click **Add to branch** to stage your changes.
2. Click **Merge to shared model**. This promotes model changes and publishes attached content in one step.

<Warning>
  Merging directly to the shared model bypasses peer review. For teams where model accuracy and stability matter, enabling **Require pull requests** is strongly recommended.
</Warning>

## Best practices

* [Working with dbt and Git](/integrations/dbt/git-workflows) — The full branch → schema refresh → validate → merge lifecycle for dbt and git
* [git integration settings reference](/integrations/git/settings) — Full reference for all git configuration options
* [git integration best practices](/integrations/git/best-practices) — Branch protection, monorepo setup, and more
* [dbt integration overview](/integrations/dbt/index) — Feature overview including dbt Semantic Layer and dynamic schema switching

## Next steps

* [git integration settings reference](/integrations/git/settings) — Full reference for all git configuration options
* [git integration best practices](/integrations/git/best-practices) — Branch protection, monorepo setup, and more
* [dbt integration overview](/integrations/dbt/index) — Feature overview including dbt Semantic Layer and dynamic schema switching
* [Branch Mode](/content/develop/branch-mode) — How branching works for both model and content changes
* [Content Validator](/modeling/develop/content-validator) — How to validate and repair content after model changes


# Connect a chat agent to Omni AI for embed experiences
Source: https://docs.omni.co/guides/embed/ai-chat-agent

Use the Omni AI API or MCP Server to connect a custom chat agent that queries data on behalf of embed users, scoped to each user's permissions.

<GuideSidebar />

<GuideTitle title="Connect a chat agent to Omni AI for embed experiences" />

If you're building a chat agent that serves your users, you can connect it to Omni's AI so that each user's queries are scoped to their Omni permissions. Omni provides two integration paths:

* **REST API (recommended)** — Submit prompts, poll for status, and retrieve results using Omni's AI Jobs API. This gives you full control over the request lifecycle and is the easiest path to integrate into most backend architectures.
* **MCP Server** — Connect an MCP-compatible agent to Omni's MCP endpoint. This is a good fit if your agent framework already supports the [Model Context Protocol](https://modelcontextprotocol.io/). Managing the user authentication can be trickier.

Both approaches support the `userId` parameter, which is **required for embed** to ensure queries run with the correct user's permissions.

## Prerequisites

* An [Omni API key](/api/authentication) with organization-level access
* Embed users provisioned in your Omni instance
* A model ID for the model your chat agent will query against
* For MCP: the [MCP server AI setting](/ai/mcp/authentication#requirements) enabled for your organization

## Get the embed user ID

Each embed user in Omni has a unique user ID. Your chat agent needs this ID to run queries with that user's permissions.

The [List embed users](/api/users/list-embed-users) endpoint depends on the embed user already existing in Omni. By default, embed users are created when they first authenticate into an iframe — but your chat agent may need to look up a user before they've ever loaded an iframe.

To avoid this dependency, use the [2-step SSO](/embed/setup/two-step-sso) login flow to pre-create embed users. The `generate-session` endpoint **upserts** the embed user, creating them if they don't already exist:

```bash theme={null}
curl -X POST "https://<YOUR_OMNI_INSTANCE>/api/unstable/embed/sso/generate-session" \
  -H "Authorization: Bearer <OMNI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contentPath": "/my",
    "externalId": "<EXTERNAL_ID>",
    "name": "<USER_NAME>"
  }'
```

This ensures the embed user exists in Omni. You can then retrieve their Omni user ID using the [List embed users](/api/users/list-embed-users) endpoint:

```bash theme={null}
curl -X GET "https://<YOUR_OMNI_INSTANCE>/api/v0/users/embed" \
  -H "Authorization: Bearer <OMNI_API_KEY>"
```

The response includes the `id` for each embed user. You'll pass this value as the `userId` query parameter (REST API) or the `X-MCP-User-ID` header (MCP Server).

<Tip>
  Do not hardcode a single user ID. In a production embed setup, pre-create the embed user via [2-step SSO](/embed/setup/two-step-sso), and then retrieve the appropriate embed user ID at the start of each session using the [List embed users](/api/users/list-embed-users) endpoint.
</Tip>

## Option 1: REST API (recommended)

The AI Jobs API lets you submit a natural language prompt, poll for completion, and retrieve the full result, all through standard HTTP requests. This is the recommended approach because it integrates into any backend without requiring MCP client support.

### How it works

1. **Create a job** — Submit a prompt with `modelId` and the embed user's `userId`
2. **Poll for status** — Check the job status every 2–5 seconds until it reaches a terminal state, or configure a webhook to be notified on completion
3. **Stream results** — Retrieve the full result, including any queries the AI ran and the final answer

### Step 1: Create an AI job

Use the [Create AI job](/api/ai/create-ai-job) endpoint. Pass the embed user's ID as the `userId` query parameter so the job runs with that user's permissions:

```bash theme={null}
curl -X POST "https://<YOUR_OMNI_INSTANCE>/api/v1/ai/jobs?userId=<EMBED_USER_ID>" \
  -H "Authorization: Bearer <OMNI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "<MODEL_ID>",
    "prompt": "What were total sales last quarter?"
  }'
```

<Warning>
  The `userId` parameter only works with Organization API keys. It cannot be used with Personal Access Tokens (PATs).
</Warning>

The response includes a `jobId` and `conversationId`:

```json theme={null}
{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "conversationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "omniChatUrl": "https://myorg.omni.co/chat/b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

To send follow-up messages in the same conversation, pass the `conversationId` in subsequent requests:

```bash theme={null}
curl -X POST "https://<YOUR_OMNI_INSTANCE>/api/v1/ai/jobs?userId=<EMBED_USER_ID>" \
  -H "Authorization: Bearer <OMNI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "<MODEL_ID>",
    "prompt": "Break that down by region",
    "conversationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }'
```

#### Optional parameters

| Parameter        | Description                                                                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `topicName`      | Scope query generation to a specific topic. If omitted, the AI selects the best topic automatically.                                                                                                                     |
| `branchId`       | Query against an in-progress model branch instead of the shared model. When using the [Create AI job API](/api/ai/create-ai-job), also serves as the write target for any model edits the AI makes during job execution. |
| `conversationId` | Continue an existing conversation thread.                                                                                                                                                                                |
| `webhookUrl`     | Receive a `POST` notification when the job completes instead of polling.                                                                                                                                                 |

### Step 2: Poll for job status

Use the [Get AI job status](/api/ai/get-ai-job-status) endpoint to check progress. Poll every 2–5 seconds until the job reaches a terminal state (`COMPLETE`, `FAILED`, or `CANCELLED`):

```bash theme={null}
curl -X GET "https://<YOUR_OMNI_INSTANCE>/api/v1/ai/jobs/<JOB_ID>" \
  -H "Authorization: Bearer <OMNI_API_KEY>"
```

A completed job response includes a `resultSummary`:

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "COMPLETE",
  "resultSummary": "Total sales last quarter were $1.2M, up 15% from the previous quarter.",
  "conversationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "userId": "9e8719d9-276a-4964-9395-a493189a247c",
  "omniChatUrl": "https://myorg.omni.co/chat/b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

<Note>
  The `resultSummary` is a short markdown summary. For the full result including query details and data, use the Stream AI job results endpoint in the next step.
</Note>

### Step 3: Stream the full result

Once the job is complete, use the [Stream AI job results](/api/ai/stream-ai-job-results) endpoint to retrieve the full response, including all queries the AI ran and the final answer:

```bash theme={null}
curl -X GET "https://<YOUR_OMNI_INSTANCE>/api/v1/ai/jobs/<JOB_ID>/result" \
  -H "Authorization: Bearer <OMNI_API_KEY>"
```

The response includes the AI's actions and final message:

```json theme={null}
{
  "actions": [
    {
      "type": "generate_query",
      "message": "I'll query total sales for last quarter.",
      "timestamp": "2025-01-15T10:00:10.000Z",
      "result": {
        "resultId": "928c5838-000d-4943-b305-f6242c1b4922",
        "queryName": "Total Sales Last Quarter",
        "status": "success",
        "query": { "fields": ["orders.quarter", "orders.total_sales"] },
        "csvResult": "Quarter,Total Sales\nQ4 2024,\"1,200,000.00\"",
        "totalRowCount": 1,
        "hasResults": true,
        "csvResultWasTruncated": false
      }
    }
  ],
  "message": "Total sales last quarter were $1.2M, up 15% from the previous quarter.",
  "topic": "order_items",
  "omniChatUrl": "https://myorg.omni.co/chat/b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

The `message` field contains the AI's final answer in markdown, which you can render directly in your chat interface. The `actions` array provides the underlying query details if you want to show the data behind the answer.

### Cancel a job

If a user cancels a request in your chat interface, use the [Cancel AI job](/api/ai/cancel-ai-job) endpoint to stop the job:

```bash theme={null}
curl -X POST "https://<YOUR_OMNI_INSTANCE>/api/v1/ai/jobs/<JOB_ID>/cancel" \
  -H "Authorization: Bearer <OMNI_API_KEY>"
```

### Using webhooks instead of polling

Instead of polling for status, you can pass a `webhookUrl` when creating the job. Omni will send a `POST` request to your URL when the job reaches a terminal state:

```bash theme={null}
curl -X POST "https://<YOUR_OMNI_INSTANCE>/api/v1/ai/jobs?userId=<EMBED_USER_ID>" \
  -H "Authorization: Bearer <OMNI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "<MODEL_ID>",
    "prompt": "What were total sales last quarter?",
    "webhookUrl": "https://your-app.com/webhooks/omni",
    "webhookSigningSecret": "<YOUR_SIGNING_SECRET>"
  }'
```

The webhook payload includes the job status and a result summary:

```json theme={null}
{
  "event_id": "evt_550e8400_COMPLETE_1706123456",
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETE",
  "result_summary": "Total sales last quarter were $1.2M",
  "completed_at": "2025-01-24T10:30:00Z"
}
```

To retrieve the full result with query data, call the [Stream AI job results](/api/ai/stream-ai-job-results) endpoint after receiving the webhook.

### Example: end-to-end integration

Here's a simplified example of how to wire this together in a backend service:

```python theme={null}
import requests
import time

OMNI_BASE_URL = "https://<YOUR_OMNI_INSTANCE>"
API_KEY = "<OMNI_API_KEY>"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def ask_omni(prompt, model_id, embed_user_id, conversation_id=None):
    """Submit a prompt to Omni AI on behalf of an embed user."""

    # Step 1: Create the job with the embed user's ID
    body = {"modelId": model_id, "prompt": prompt}
    if conversation_id:
        body["conversationId"] = conversation_id

    resp = requests.post(
        f"{OMNI_BASE_URL}/api/v1/ai/jobs",
        headers=HEADERS,
        params={"userId": embed_user_id},
        json=body,
    )
    resp.raise_for_status()
    job = resp.json()
    job_id = job["jobId"]

    # Step 2: Poll until the job completes
    while True:
        status_resp = requests.get(
            f"{OMNI_BASE_URL}/api/v1/ai/jobs/{job_id}",
            headers=HEADERS,
        )
        status_resp.raise_for_status()
        status = status_resp.json()

        if status["state"] in ("COMPLETE", "FAILED", "CANCELLED"):
            break
        time.sleep(3)

    if status["state"] != "COMPLETE":
        raise Exception(f"Job {status['state']}: {status.get('error', {}).get('message')}")

    # Step 3: Get the full result
    result_resp = requests.get(
        f"{OMNI_BASE_URL}/api/v1/ai/jobs/{job_id}/result",
        headers=HEADERS,
    )
    result_resp.raise_for_status()
    result = result_resp.json()

    return {
        "answer": result["message"],
        "conversation_id": job["conversationId"],
        "actions": result.get("actions", []),
    }
```

## Option 2: MCP Server

If your agent framework supports the Model Context Protocol, you can connect it directly to Omni's MCP endpoint. The MCP Server exposes tools that let your agent pick models, select topics, and query data through natural language.

### Configure the MCP Server

Point your chat agent's MCP client at your Omni instance. Set the `X-MCP-User-ID` header to the embed user's ID so that all queries run with that user's permissions:

```json title="MCP configuration" theme={null}
{
  "mcpServers": {
    "Omni": {
      "url": "https://<YOUR_OMNI_INSTANCE>/mcp/https",
      "headers": {
        "Authorization": "Bearer <OMNI_API_KEY>",
        "X-MCP-User-ID": "<EMBED_USER_ID>",
        "X-MCP-User-Required": "true",
        "X-MCP-Model-ID": "<OPTIONAL_MODEL_ID>",
        "X-MCP-Topic-Name": "<OPTIONAL_TOPIC_NAME>"
      }
    }
  }
}
```

### Header reference

| Header                | Required | Description                                                              |
| --------------------- | -------- | ------------------------------------------------------------------------ |
| `Authorization`       | Yes      | Your Omni API key, prefixed with `Bearer`                                |
| `X-MCP-User-ID`       | Yes      | The embed user's Omni user ID. Queries run with this user's permissions. |
| `X-MCP-User-Required` | Yes      | Set to `true` to enforce that a user ID is provided for every query      |
| `X-MCP-Model-ID`      | No       | Scope the MCP Server to a specific model                                 |
| `X-MCP-Topic-Name`    | No       | Scope the MCP Server to a specific topic                                 |

### Dynamic user ID assignment

In a production embed setup, retrieve the embed user ID at the start of each session rather than hardcoding it:

1. A user starts a chat session in your embedded application
2. Your application identifies the user (from a session token or external ID)
3. Your backend calls the [List embed users](/api/users/list-embed-users) endpoint to resolve the user's Omni user ID
4. Your backend passes the user ID in the `X-MCP-User-ID` header when connecting to the MCP Server

## User permissions in embed

Both integration paths enforce the embed user's Omni permissions on every query. This includes:

* **Access grants** — Users only see data they're authorized to access
* **Row-level security** — Query results are filtered to the user's allowed rows
* **Topic-level restrictions** — Users can only query topics they have access to

This means you can expose a single chat interface to all embed users, and Omni handles permission scoping automatically based on the `userId` you provide.


# Embed environment architecture
Source: https://docs.omni.co/guides/embed/embed-development-production-setup

How to structure staging and production Omni instances for external embed, including the CI/CD workflow, content promotion, and permission guardrails.

<GuideSidebar />

<GuideTitle title="Embed environment architecture" />

This guide covers how to structure your Omni instances for external embed: the recommended two-instance staging-to-production setup, how changes flow between environments, and the permission configuration to lock down before going live. It also notes what to watch out for if a second instance isn't feasible right away.

**This is especially relevant if:**

* You're running a production embed instance and want a safe place to build and test changes before they reach customers
* You're planning a CI/CD workflow for model and content changes across environments
* You want to understand how embed permissions work and what to validate before launch

## Prerequisites

Before following this guide, make sure you have:

* An existing Omni instance with external embed configured or in progress
* Admin permissions on both your staging and production Omni instances
* Access to a git repository that both instances can connect to
* The ability to generate API keys on each instance (required for the [Content Migration API](https://community.omni.co/t/content-migration-move-dashboards-between-models-connections/254))

## Two-instance setup: staging and production

The recommended pattern is two separate Omni instances (one for staging and development, one for production), using [**Git Follower Mode**](/integrations/git/follower-mode/setup) to keep the data model in-sync and the [**Content Migration API**](https://community.omni.co/t/content-migration-move-dashboards-between-models-connections/254) to move dashboards and workbooks between them.

### How Git Follower connects the two instances

Git Follower keeps a production instance's data model automatically in-sync with a development instance through a shared git repository.

The staging instance acts as the **leader**: all model development happens here, and changes are published by merging pull requests into the main branch.

The production instance acts as the **follower**: it's pointed at a separate branch (e.g., `prod`) and picks up model changes automatically when that branch is updated.

Developers never touch the production instance directly. All changes flow through git.

Git Follower can be configured either across two separate Omni instances or across two models within the same instance. For embed customers, separate instances are strongly preferred. This fully isolates production from staging, preventing accidental changes and allowing independent instance-level configuration.

### Setup

#### Instance and database connections

Connect the staging instance to your staging database and the production instance to your production database.

#### Git integration

On the staging instance, connect to your git repository pointed at the main branch (this is the leader). On the production instance, connect to the same repository, enable Git Follower Mode, and point it at a separate branch (e.g., `prod`).

Enable the **Always create branches** setting on the production instance. This ensures that when a release branch is created in git, Omni automatically opens a matching branch on the follower.

#### Development workflow on staging

All model and content development happens on the staging instance:

<Steps>
  <Step title="Open a new branch in the Omni model IDE" />

  <Step title="Make model and/or content changes" />

  <Step title="Open a pull request">
    Click **Create Pull Request** from the branch header to open a PR against `main` in git.
  </Step>

  <Step title="Merge the PR">
    Changes are published and live on staging.
  </Step>

  <Step title="Validate">
    Run the [Content Validator](/modeling/develop/content-validator), test queries, and optionally embed the branch into your staging app environment to verify end-to-end.
  </Step>
</Steps>

### Promoting changes to production

Once staging is validated:

<Steps>
  <Step title="Trigger the Content Migration API">
    Move dashboards and workbooks from the staging instance to the production instance. Migrate into a **validation folder**, not the embed-accessible folder (see the next section).
  </Step>

  <Step title="Create a release branch">
    In git, create a release branch off `main` (e.g., `release-to-prod-YYYYMMDD`).
  </Step>

  <Step title="Open a PR">
    Open a PR to merge the release branch into `prod`.
  </Step>

  <Step title="Open the matching branch on production">
    On the production instance, open the release branch.
  </Step>

  <Step title="Validate">
    Run the Content Validator to confirm nothing is broken.
  </Step>

  <Step title="Merge the PR">
    Model changes are now live on the production instance.
  </Step>

  <Step title="Move content to the embed-accessible folder">
    Once validated, move content out of the validation folder and into the embed-accessible folder.
  </Step>
</Steps>

<img alt="Visual step-by-step for staging and prod deployment workflow" />

<Note>
  On the first deployment, manually trigger a schema refresh on the production instance after enabling follower mode, before running the Content Validator for the first time. This ensures the follower's schema is aligned with the leader's and avoids validation errors.
</Note>

<Note>
  **Order matters.** Trigger the Content Migration API after staging is fully validated, but before merging the git release PR to `prod`. This keeps model logic and content in-sync on the production instance.
</Note>

### Using a validation folder to gate content visibility

On a fully locked-down embed instance, external users only see content that has been explicitly shared with them, typically through an **All Embed Users** group with Viewer access to a designated folder.

Use this to your advantage: have the Content Migration API target a validation folder that is not shared with the embed users group. Your team can then log into the production instance as admins and review the migrated content before granting end-user visibility.

## Locking down permissions before launch

Beyond content visibility, several permission layers need to be configured correctly on your production embed instance before customers are live.

### Embed users get only the permissions you pass in the URL

Embed user permissions come exclusively from the [`connectionRoles`](/embed/setup/url-parameters/connectionRoles) and `modelRoles` parameters passed in the embed URL at login time. Base access roles on the connection or model do not apply to embed users.

Every embed URL generation must explicitly pass the correct, minimally-permissive role. That said, it's still recommended practice to set the base connection role to **No Access** and grant access only via URL parameters.

### Use Restricted Querier or Viewer for embed users

The `connectionRoles` parameter accepts standard roles or custom roles that resolve to either **Viewer** or **Restricted Querier**. These are the two intended tiers for embed users:

* **Restricted Querier:** lets users create and view content through topics, keeping all model-layer permissions intact
* **Viewer:** lets users view dashboards only

Users with Querier access can write raw SQL that bypasses [access grants](/modeling/models/access-grants) and field-level security. Omni does not automatically block higher-privileged roles from being passed through `connectionRoles`. If a Querier-based custom role is passed, embed users genuinely receive that access. This needs to be controlled at URL generation time.

<Warning>
  If you have a custom role based on Querier (rather than Restricted Querier) and it's being passed through `connectionRoles`, your embed users have raw SQL access. Replace it with a role based on Restricted Querier immediately.
</Warning>

### Build all embed content on topics, not raw SQL

Embed users with Restricted Querier access can only query through topics. Any dashboard tile or workbook query built directly on raw SQL will be inaccessible to them. Before promoting content to the embed-accessible folder, confirm that every query in every dashboard is backed by a topic. This is also what makes [access filters](/modeling/topics/parameters/access-filters) and field-level permissions enforceable: those controls live at the model layer and only apply when queries go through topics.

### Apply access filters to every topic embed users can reach

Every topic accessible to embed users should have access filters implemented. These enforce row-level security at the model layer and cannot be bypassed with Restricted Querier access, making them the foundation of multi-tenant isolation.

### Use model roles over connection roles for model-level permissions

When setting permissions on models in admin, prefer model roles over connection roles where possible. Connection roles cascade to all child models on the connection, which can produce unintended permission grants.

### Test resolved permissions for a real embed user before launch

Permission resolution can produce unexpected results when a user belongs to multiple groups, since the highest-privilege role across all groups wins. Before going live, use the admin area to inspect the **Resolved Permissions** for a test embed user to ensure they have access to exactly what they need and nothing more.

## Things to be aware of as you operate

A few operational points worth keeping in mind:

* **Content promotion requires scripting.** The Content Migration API has no native one-click sync between instances. Plan for this in your workflow.
* **Be careful when deleting dashboards.** Deleting a dashboard removes its associated schedules and custom identifiers, and these can't be recovered once the dashboard clears trash.
* **Git Follower covers the model only.** Dashboards and workbooks must be managed separately through the Migration API.
* **Two instances means two sets of auth and permissions to maintain.** User attributes, user groups, and authentication protocols are configured independently on each instance. Admin access is also instance-specific.
* **Always do a schema refresh on the follower** before running the Content Validator. This ensures the follower's schema is aligned with the leader's before you validate.

## If a second instance isn't feasible right now

<Note>
  This is a fallback option for teams where a second instance isn't practical yet. It reduces operational overhead but comes with real tradeoffs for embed customers. You can start here and move to separate instances later.
</Note>

It's possible to run staging and production as two separate models within the same Omni instance, with Git Follower keeping the production model in-sync with the staging model. The promotion workflow remains the same, but all changes happen in a single instance.

The main concerns with this approach for embed customers:

* **Human error risk.** Developers working on staging share the same instance as production. An accidental publish or permission change can reach your external customers.
* **Instance-level settings bleed.** Feature flags, AI settings, dashboard themes, and Slack delivery configuration can't be managed independently per environment.
* **Developer velocity.** Internal developers are subject to the same locked-down controls as the embedded production environment, which slows iteration.
* **IDE schema errors.** When the two connections point to different databases, the follower model shows schema validation errors in the IDE.
* **Harder to test embed end-to-end.** You can't fully simulate the production embed experience from within staging when they share an instance.

For embed use cases where misconfigured access rules or accidental model changes have real customer impact, the two-instance separation is worth the added complexity.

## Next steps

* [Set up Git Follower Mode](/integrations/git/follower-mode/setup) on your production instance
* [Review Git Follower best practices](/integrations/git/follower-mode/best-practices), including the schema refresh and branch settings
* [Configure access filters](/modeling/topics/parameters/access-filters) on every topic before promoting content to production
* [Review the fully locked-down embed setup](/administration/users/permissions-scenarios#fully-locked-down) to confirm your permission model is correct


# Embedding Omni into internal applications
Source: https://docs.omni.co/guides/embed/omni-in-internal-app

Embed Omni into internal apps such as wikis, Salesforce, Notion, or any other website that supports iframes.

<GuideSidebar />

<GuideTitle title="Embedding Omni into internal applications" />

Your team already has internal tools - wikis, admin panels, CRMs, custom apps - where they spend most of their day. Embedding Omni dashboards into those tools puts live data in front of people where they're already working, so they don't have to bounce between apps to get answers.

This guide covers the general approach to embedding Omni content in any internal application that supports iframes. If you're working with a specific tool, we also have step-by-step guides for:

* [Notion](/guides/embed/omni-in-notion)
* [Salesforce](/guides/embed/omni-in-salesforce)

## Requirements

To follow this guide, you'll need permissions in Omni that allow you to access the workbook or dashboard you want to embed.

Additionally, users who view the Omni iframe in your internal application must have permissions in Omni that allow them to view the dashboard being embedded. Viewers of the content will be prompted to log in using the iframe and if they have sufficient permissions, the content will display.

<Steps>
  <Step title="Generate an embed URL">
    1. In a [published](/content/develop/drafts#publishing-drafts) Omni workbook or dashboard, click the **Share** button to open the share modal. You can also navigate to **File > Document settings**.

    2. Click **Embed**.

    3. If desired, use the options in this tab to customize what content is embedded and how it displays for users. For example, you could embed a dashboard and only display it in dark mode. See [Customize embedded content](/share#customize-embed-content) for more information.

       <img alt="Omni share modal with embed options" />

    4. Click the **Copy** button to copy the iframe URL. The example iframe URL below is for an Omni instance named `blobsrus` and includes settings for **Light/dark mode** (`prefersDark`) and **Theme** (`theme`):

       ```html wrap theme={null}
       <iframe src="https://blobsrus.omniapp.co/dashboards/a0554a7e?prefersDark=true&theme=dawn"></iframe>
       ```
  </Step>

  <Step title="Embed and test the iframe">
    Add the iframe to your internal application to embed Omni.

    Before you share your work with other users, use the iframe to log into Omni. This allows you to check that the workbook or dashboard displays correctly after authentication.
  </Step>

  <Step title="Share your work">
    Share your work with other users in your internal application.

    **Note**: Users will have to log into Omni with the iframe before they can view the workbook or dashboard content.
  </Step>
</Steps>


# Embedding Omni in your Notion instance
Source: https://docs.omni.co/guides/embed/omni-in-notion

Embed Omni dashboards in Notion documents using iframes.

<GuideSidebar />

<GuideTitle title="Embedding Omni in your Notion instance" />

If your team runs on Notion - wikis, project docs, team pages - embedding Omni dashboards lets you incorporate live data right alongside the context that explains it. Instead of linking out to a separate BI tool, readers can see the numbers inline as they scroll through a planning doc, team update, or KPI page.

This guide walks through embedding an Omni dashboard in a Notion document using an iframe.

## Limitations

While not required, viewing the Omni iframe in Notion works best on the **web** version of Notion.

## Requirements

To follow this guide, you'll need:

* Permissions in Omni that allow you to access the dashboard you want to embed
* Permissions in Notion that allow you to create and edit documents

Additionally, users who view the Omni iframe in Notion must have permissions in Omni that allow them to view the dashboard being embedded. Viewers of the content will be prompted to log in using the iframe and if they have sufficient permissions, the content will display.

<Steps>
  <Step title="Retrieve the dashboard's embed URL">
    1. In a [published](/content/develop/drafts#publishing-drafts) Omni workbook or dashboard, click the **Share** button to open the share modal. You can also navigate to **File > Document settings**.

    2. Click **Embed**.

    3. If desired, use the options in this tab to customize what content is embedded and how it displays for users. For example, you could embed a dashboard and only display it in dark mode. See [Customize embedded content](/share#customize-embed-content) for more information.

       <img alt="Omni share modal with embed options" />

    4. Click the **Copy** button to copy the iframe URL. The example iframe URL below is for an Omni instance named `blobsrus` and includes settings for **Light/dark mode** (`prefersDark`) and **Theme** (`theme`):

       ```html wrap theme={null}
       <iframe src="https://blobsrus.omniapp.co/dashboards/a0554a7e?prefersDark=true&theme=dawn"></iframe>
       ```

    5) In a text editor, only copy the Omni URL. For example, if you copied a string like the following:

       ```html wrap theme={null}
       <iframe src="https://blobsrus.omniapp.co/dashboards/a0554a7e"></iframe>
       ```

       You will only want the URL:

       ```txt wrap theme={null}
       https://blobsrus.omniapp.co/dashboards/a0554a7e
       ```
  </Step>

  <Step title="Create an embed component in Notion">
    1. In a Notion document, use the `/embed` command to create an embed component.
    2. Paste the Omni URL into the field:
       <img alt="Notion embed component with the Omni dashboard URL pasted into the link field" />
    3. Click **Embed link**.
  </Step>

  <Step title="Test the iframe">
    Your Omni dashboard should now be embedded in Notion! 🎉

    Before you share the Notion document with other users, use the iframe to log into Omni. This allows you to check that the workbook or dashboard displays correctly after authentication.

    <img alt="An Omni dashboard embedded and rendered inside a Notion document" />
  </Step>

  <Step title="Share the Notion document">
    Share the Notion document with other users in your Notion instance. **Note**: Users will have to log into Omni with the iframe before they can view the workbook or dashboard content.
  </Step>
</Steps>


# Embedding Omni in your Salesforce instance
Source: https://docs.omni.co/guides/embed/omni-in-salesforce

Embed static and dynamic Omni dashboards in Salesforce using Visualforce pages and tabs.

<GuideSidebar />

<GuideTitle title="Embedding Omni in your Salesforce instance" />

Want to put Omni analytics right where your sales team already spends their day? Embedding dashboards directly in Salesforce means reps can see account-level metrics, pipeline trends, or usage data without switching tabs - and dynamic dashboards can automatically filter to whichever record they're viewing.

In this guide, we'll walk through two approaches: embedding a static dashboard as its own Visualforce page, and embedding a dynamic dashboard that parameterizes filters based on the current Salesforce record.

## Requirements

To follow this guide, you'll need:

* Permissions in Omni that allow you to access the dashboard you want to embed
* Permissions in Salesforce that allow you to create Visualforce pages and modify Salesforce objects

## Embedding static dashboards

In this example, you'll embed a static dashboard into a new Visualforce page. Unlike [dynamic (parameterized) dashboards](#embedding-dynamic-dashboards), the content of static dashboards doesn't change.

<Steps>
  <Step title="Create a new Visualforce page">
    1. In your Salesforce instance, navigate to the Developer Console:
       <img alt="Salesforce Developer Console menu option" />
    2. Create a new Visualforce page:
       <img alt="Creating a new Visualforce page in the Salesforce Developer Console" />

    Leave the page open for now - you'll need it later in the guide.
  </Step>

  <Step title="Retrieve the dashboard's embed URL">
    1. In a [published](/content/develop/drafts#publishing-drafts) Omni workbook or dashboard, click the **Share** button to open the share modal. You can also navigate to **File > Document settings**.

    2. Click **Embed**.

    3. If desired, use the options in this tab to customize what content is embedded and how it displays for users. For example, you could embed a dashboard and only display it in dark mode. See [Customize embedded content](/share#customize-embed-content) for more information.

       <img alt="Omni share modal with embed options" />

    4. Click the **Copy** button to copy the iframe URL. The example iframe URL below is for an Omni instance named `blobsrus` and includes settings for **Light/dark mode** (`prefersDark`) and **Theme** (`theme`):

       ```html wrap theme={null}
       <iframe src="https://blobsrus.omniapp.co/dashboards/a0554a7e?prefersDark=true&theme=dawn"></iframe>
       ```
  </Step>

  <Step title="Add the iframe to the Visualforce page">
    In Salesforce, add your `iframe` code to the Visualforce page you created.

    In this example, we added styling elements that will allow the dashboard to fill the whole page:

    ```html wrap title="Visualforce page with added styling elements" theme={null}
    <apex:page sidebar="false">
      <style>
        html { 
          width: 100%; 
          height: 100%;
        }
      </style>   
      
      <apex:iframe scrolling="true" width="100%" height="100%" src="https://blobsrus.omniapp.co/dashboards/a0554a7e">
      </apex:iframe>
    </apex:page>
    ```
  </Step>
</Steps>

## Embedding dynamic dashboards

To make your dashboards dynamic, you can parameterize the filters in the iframe URL with Apex variables. In this example, you'll embed a dashboard that dynamically filters data based on the Salesforce account that is currently being viewed and add it to an existing Salesforce object.

<Steps>
  <Step title="Prepare your dashboard for embedding">
    1. In your Omni dashboard, add a filter on the field you want to parameterize (for example, **Account ID**). This filter should **not** be one of your default filters.
    2. Click **Share** to open the share modal.
    3. Check the **Include current filters** option.
    4. Copy the `<iframe>` embed code.
    5. In a text editor, locate the filter value in the URL and replace it with the Apex variable you want Salesforce to pass through.

       For example, replace the hard-coded **Account ID** with `{!Account.Id}`:

       ```html wrap highlight={4} theme={null}
       <apex:page standardController="Account">
         <apex:iframe
           scrolling="true"
           src="https://blobsrus.omniapp.co/dashboards/a0554a7e?f--salesforce__account.id=%28%27kind%21%27EQUALS%27%7Etype%21%27string%27%7Evalues%21%5B%27{!Account.Id}%27%5D%7Eis_negative%21false%29O_O">
         </apex:iframe>
       </apex:page>
       ```

    Keep the code handy - you'll need it to complete the next step.
  </Step>

  <Step title="Create a new Visualforce page">
    1. In your Salesforce instance, navigate to the Developer Console:
       <img alt="Salesforce Developer Console menu option" />
    2. Create a new Visualforce page:
       <img alt="Creating a new Visualforce page in the Salesforce Developer Console" />
    3. Paste the `iframe` code you created in the previous step and save the page.
  </Step>

  <Step title="Optional: Create a Visualforce tab">
    If you want the dashboard to appear as its own tab in Salesforce:

    1. In Salesforce, navigate to **Setup > Tabs**:
       <img alt="Salesforce Setup Tabs page for creating a new Visualforce tab" />
    2. Create a new **Visualforce Tab**, selecting the Visualforce page you created in the previous step.

    The tab will now be available to users and will open an interactive, embedded dashboard.
  </Step>

  <Step title="Add the embedded dashboard to an existing Salesforce object">
    1. In Salesforce, navigate to **Setup > Object Manager**:
       <img alt="Salesforce Setup Object Manager page" />
    2. Select the object where you want the dashboard to appear (for example, **Account**).
    3. Open the **Page Layouts** section and choose the layout you want to edit.
    4. Add a new section to the layout to hold the embedded dashboard:
       <img alt="A new, blank section added to a Salesforce page layout" />
    5. Drag the **Visualforce Page** component into the new section:
       <img alt="Dragging the Visualforce Page component into a Salesforce page layout section" />
       <Tip>
         Click the <Icon icon="wrench" type="solid" /> wrench icon to adjust the size of the iframe.
       </Tip>
  </Step>

  <Step title="Confirm the embedded dashboard works">
    Your dashboard should now load dynamically, using the Salesforce record's ID to parameterize the embedded Omni dashboard. 🎉

    Visit a record (e.g., an **Account** page) and verify that the correct data displays.
  </Step>
</Steps>


# Triage 'Failed to fetch' browser errors
Source: https://docs.omni.co/guides/errors/failed-to-fetch

Diagnose and resolve Failed to fetch browser errors caused by extensions, firewalls, proxies, or VPNs.

<GuideSidebar />

<GuideTitle title="Triage Failed to fetch browser errors" />

`Failed to fetch` is a browser-level network error — it means your browser blocked or dropped a request before it reached Omni.

If a page refresh fixes it, the cause was likely a brief internet drop. If the error is consistent or reproducible, work through the steps below to find the cause.

## Scope the problem first

Before troubleshooting, answer these questions — they'll tell you which step to start with and what to tell support if you need to escalate.

| Question                                                | Why it matters                                                                                                               |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Is it one user or multiple?                             | Multiple users points to a network or Omni configuration issue, not a browser extension                                      |
| Is it one dashboard or everywhere in Omni?              | Scoped to one dashboard suggests a specific query or data connection; everywhere suggests a browser or network issue         |
| Is it in an embedded context or directly on omniapp.co? | Embed adds iframe and cookie restrictions that can trigger this error                                                        |
| Is it consistent or intermittent?                       | Intermittent errors often indicate network instability (VPN drops, weak Wi-Fi); consistent errors point to a blocked request |

## Steps

<Steps>
  <Step title="Disable browser extensions">
    Ad blockers, privacy tools, and VPN browser extensions are the most common cause of `Failed to fetch` errors. They intercept network requests and can silently block calls to Omni's servers.

    1. Open a **private or incognito window** — extensions are disabled by default in most browsers' private modes.
    2. Log in to Omni and reproduce the action that caused the error.
    3. If the error is gone, a browser extension is the cause. Re-enable your extensions one at a time in a normal window to identify the specific culprit.

    Common offenders include uBlock Origin, Privacy Badger, Ghostery, and any extension marketed as an ad blocker or tracker blocker.
  </Step>

  <Step title="Test on a different network">
    Corporate networks — including firewalls, proxies, and content filters — can block requests to Omni's servers even when Omni is working correctly.

    1. Connect to a **mobile hotspot** or a non-corporate network.
    2. Log in to Omni and reproduce the action.
    3. If the error is gone on a different network, the issue is with your corporate network. Your IT team will need to allowlist Omni's IP addresses in your firewall or proxy.

    Omni's IP addresses are listed on each connection's settings page. Navigate to **Settings > Connections**, click a connection, and copy the IP addresses shown. See [Allowlisting Omni's IP addresses](/administration/security/omni-ip-addresses) for details.

    <Note>
      VPNs can cause intermittent `Failed to fetch` errors even outside a corporate network. If the error appears and disappears, try disabling your VPN first.
    </Note>
  </Step>

  <Step title="Inspect the browser Network tab">
    If the first two steps don't resolve the error, use your browser's developer tools to capture exactly which request is failing and why.

    **To open the Network tab:**

    * **Chrome / Edge**: Press `F12` (or `Cmd+Option+I` on Mac), then click the **Network** tab
    * **Firefox**: Press `F12`, then click **Network**
    * **Safari**: Enable the Develop menu under **Safari > Settings > Advanced**, then press `Cmd+Option+I` and click **Network**

    **What to look for:**

    1. Clear the Network tab log, then reproduce the error.
    2. Filter by **XHR** or **Fetch** requests.
    3. Look for requests with a red status, `(canceled)`, `(blocked)`, or status codes in the `4xx`/`5xx` range.
    4. Click the failing request and open the **Headers** tab.

    **What to capture for escalation:**

    * The full request URL
    * The response status (or the error message if blocked)
    * Any `net::ERR_*` message shown in the status column (e.g. `net::ERR_BLOCKED_BY_CLIENT` typically indicates a browser extension or firewall block)
  </Step>
</Steps>

## Escalating to support

If the steps above don't resolve the error, contact Omni support with the following:

* **Browser and version** (e.g. Chrome 125, Safari 17.4)
* **List of browser extensions** installed, or a screenshot of your extensions list
* **Network tab screenshot** showing the failing request, with the Headers panel open (request URL, response status, and any error message visible)
* **Scope**: whether the error is on one dashboard or everywhere, and whether it affects one user or multiple
* **Network context**: whether it reproduces on a different network or with VPN disabled

## Next steps

* [Allowlisting Omni's IP addresses](/administration/security/omni-ip-addresses)
* [Embedding limitations](/embed/limitations)
* [Troubleshooting connection issues](/connect-data/troubleshooting)


# Resolve 'Join fans out data without primary key' errors
Source: https://docs.omni.co/guides/errors/fan-out-without-pk

Learn to account for fan out in table joins.

<GuideSidebar />

<GuideTitle title="Resolve Join fans out data without primary key errors" />

If you receive the `Join fans out data without primary key` error while you're building a workbook query, you may be trying to calculate an aggregation (sum, count, average, etc.) on a table that's being "fanned out" by a join.

## Why this happens

This happens when you're joining two tables and one row in the first table is joined onto multiple rows in the other table. For example, you have an `orders` table and an `order_items` table. Joining these tables on `order_id` will fan out the `orders` table since multiple items in `order_items` will match the same order in `orders`:

```mermaid theme={null}
flowchart LR
    subgraph orders["orders"]
        o1["order_id: 101<br/>total: $50"]
    end

    subgraph order_items["order_items"]
        i1["order_id: 101<br/>item: Shirt"]
        i2["order_id: 101<br/>item: Pants"]
        i3["order_id: 101<br/>item: Socks"]
    end

    subgraph joined["Joined result (fan out)"]
        j1["order_id: 101, total: $50, item: Shirt"]
        j2["order_id: 101, total: $50, item: Pants"]
        j3["order_id: 101, total: $50, item: Socks"]
    end

    o1 --> i1
    o1 --> i2
    o1 --> i3

    i1 --> j1
    i2 --> j2
    i3 --> j3
```

In this example, a single row in `orders` with `total: $50` is duplicated three times in the joined result. If you summed `total` without accounting for the fan out, you'd incorrectly get `$150` instead of `$50`.

Omni uses a method called [*symmetric aggregates*](/analyze-explore/sql/symmetric-aggregates) to prevent inadvertently miscalculating aggregations - such as sums, counts, and averages - when a table is fanned out. Before Omni calculates an aggregation on a fanned out table, it'll look at that table's primary key — its unique ID per row — to ensure values aren't double-counted in the aggregation.

Omni surfaces this error when a fanned out table doesn't have a defined primary key. Without a primary key, Omni won't know how to correctly calculate the aggregation.

## How to fix it

Defining a primary key for a view will resolve this error. A primary key is a column that contains a unique identifier per row. This is usually an ID column.

Primary keys can be defined in a workbook or the model IDE.

<Note>
  Remember to promote your changes to the shared model if you want to make them generally available.
</Note>

### Workbook

1. In the workbook field browser, right click on the field you want to define as the primary key.
2. Click **Modeling > Primary Key**.

### Model IDE

1. Open the model IDE.
2. Locate the view and click to open its YAML definition.
3. Add the [`primary_key`](/modeling/dimensions/parameters/primary-key) parameter to the appropriate dimension:
   ```yaml theme={null}
   id:
     primary_key: true
   ```

**If your table has a compound (composite) primary key**, add the [`custom_compound_primary_key_sql`](/modeling/views/parameters/custom-compound-primary-key-sql) parameter to the view file:

```yaml theme={null}
custom_compound_primary_key_sql: [ id, date ]
```


# Guides
Source: https://docs.omni.co/guides/index

Step-by-step tutorials and best practices for getting the most out of Omni.

<div>
  <h1>Guides</h1>

  <p>
    Step-by-step tutorials and best practices for getting the most out of Omni.
  </p>

  <GuidesFilter />
</div>


# Migrating Looker dashboards to Omni
Source: https://docs.omni.co/guides/migrations/looker-to-omni-skill

Programmatically migrate Looker dashboards to Omni with Python, agent skills, and the Omni CLIs.

<GuideSidebar />

<GuideTitle title="Migrating Looker dashboards to Omni" />

This guide covers how to migrate Looker dashboards to Omni using a scripted API approach — a Python builder script, the Omni CLI, `omni-sync`, and Claude Code with custom agent skills. Rather than rebuilding dashboards by hand, the toolset lets you inspect source dashboards programmatically, translate fields and filters, and create Omni dashboards via the API in a workflow that gets faster with every dashboard you migrate.

This is especially relevant if you:

* Are migrating multiple Looker dashboards and want a repeatable, scriptable approach
* Are comfortable working in Claude Code or Cursor and want to run most of the migration autonomously with agent skills
* Need to handle complex Looker patterns — dynamic fields, pivots, `parameter` fields — that don't map directly to Omni

## How the tools fit together

The migration involves six tools. Knowing what each one does before you start saves a lot of back-and-forth later.

<Steps>
  <Step title="Looker API" icon="code">
    The Looker API is the starting point for every dashboard. The `dashboard_dashboard_elements` and `dashboard_dashboard_filters` endpoints return everything you need: fields, filters, sorts, pivots, dynamic fields, layout position, and filter-listen wiring. You can call these directly using the inspect script below, or let the agent skill handle it.
  </Step>

  <Step title="Omni CLI" icon="terminal">
    The Omni CLI (`@omni-co/cli`) handles branching, field management, model validation, and more. It's what the `omni-model-builder` agent skill calls under the hood. You can also use it directly for one-off operations.
  </Step>

  <Step title="omni-sync (@omni-co/model-local-editor)" icon="rotate">
    The `omni-sync` (`@omni-co/model-local-editor`) package is your live feedback loop for model changes. It watches local YAML files, pushes every save to your Omni branch, and streams validation errors back to the terminal in real time.

    Keep it running in a background terminal throughout the migration — it's what lets you (or Claude Code) iterate on the model without leaving the terminal.
  </Step>

  <Step title="omni-model-builder agent skill" icon="hammer">
    The `omni-model-builder` agent skill is a Claude Code / Cursor task definition from the [Omni agent skills repo](https://github.com/exploreomni/omni-agent-skills).

    Give it an instruction like *"add this missing dimension to the orders view"* and it handles the YAML edits, pushes via the CLI, reads the `omni-sync` validation output, and iterates until the model is clean.
  </Step>

  <Step title="omni_dashboard_builder.py Python script" icon="python">
    The `omni_dashboard_builder.py` file is the Python script that creates Omni dashboards via the API. You write a `build_<name>()` function per dashboard that assembles tiles from queries, register it in a `DASHBOARDS` dict, and run the script. It handles the API mechanics that would otherwise be tedious: layout via the export/import cycle, filter wiring, and visualization configs that the direct create API drops.

    See the [Appendix](#omni-dashboard-builder-py) for the full file contents.
  </Step>

  <Step title="looker-to-omni-dashboard agent skill" icon="forward">
    The `looker-to-omni-dashboard` agent skill orchestrates the full migration workflow in Claude Code. You give it a Looker dashboard ID and then it:

    * Calls the Looker API
    * Maps fields to Omni equivalents
    * Writes the `build_<name>()` function
    * Wires filters and layout
    * Runs the builder script
    * Opens the result URL for you to inspect

    See the [Appendix](#looker-to-omni-dashboard-skill-md) for the full file contents.
  </Step>
</Steps>

## Part 1: Get set up

The first step is to install the required packages and configure your tooling. You'll need to complete all of the steps in this section to follow the remaining sections in this guide.

<Steps>
  <Step title="Install Python 3.9+">
    You'll need Python 3.9 or later to follow the steps in this guide. See the [official Python downloads](https://www.python.org/downloads/) to download the correct version for your operating system.

    You can check what version of Python is installed, if any, by running:

    ```bash theme={null}
    python --version
    python3 --version
    python -V
    ```

    If the first command returns an error or a legacy version, try `python3`. Some systems explicitly require `python3`.
  </Step>

  <Step title="Install the Looker SDK">
    Install the [Looker SDK](https://pypi.org/project/looker-sdk/) by running:

    ```bash theme={null}
    pip install looker-sdk requests
    ```
  </Step>

  <Step title="Install Omni Agent Skills">
    1. Use the [Omni agent skills installation guide](/developers/agent-skills/install) to install the official plugin for Claude Code.
    2. Copy the [`looker-to-omni-dashboard-skill.md`](#looker-to-omni-dashboard-skill-md) file from this guide's appendix into `.claude/agents/` in your repo.

       <Note>
         The migration skill is distinct from the official plugin and needs to be placed there manually.
       </Note>
    3. Save the file as `looker-to-omni-dashboard.md`.
  </Step>

  <Step title="Install the Omni CLI">
    1. Use the [CLI installation guide](/developers/cli/install) to install the CLI.
    2. After installing, run `omni config init` once to configure your profile and set up authentication.
  </Step>

  <Step title="Install the model editor CLI (omni-sync)">
    <Note>
      See the [Local development with the model editor CLI guide](/guides/modeling/local-development) for more information about this CLI.
    </Note>

    Install the `@omni-co/model-local-editor` package globally:

    ```bash theme={null}
    npm install -g @omni-co/model-local-editor
    ```
  </Step>

  <Step title="Set environment variables">
    Set the following in the shell you'll run the migration scripts from:

    ```bash theme={null}
    export LOOKERSDK_BASE_URL="https://<your-instance>.looker.com"
    export LOOKERSDK_CLIENT_ID="<your-looker-client-id>"
    export LOOKERSDK_CLIENT_SECRET="<your-looker-client-secret>"
    export OMNI_BASE_URL="<your-omni-instance-url>"
    ```

    `looker_dashboard_inspect.py` and `omni_dashboard_builder.py` (both in the [Appendix](#companion-files)) read these directly — set them before running either script.
  </Step>

  <Step title="Start omni-sync">
    Before making any model changes, start a migration branch and keep the watcher running in a dedicated terminal throughout:

    ```bash theme={null}
    omni-sync init <your_model_id> --branch looker-migration --create-branch
    omni-sync start <your_model_id>
    ```
  </Step>
</Steps>

## Part 2: Configure Omni Git settings

1. Open your model in Omni by navigating to the model IDE.
2. Click **Model > Git Settings**.
3. Verify the following settings are enabled:

   * **Pull request required** — Prevents direct promotion of branch changes to the shared model
   * **Always create branches** — Ensures PRs created outside Omni automatically create a corresponding Omni branch

Open pull requests through the Omni web UI, not directly in GitHub. In the Omni IDE, click **Open Pull Request** in the branch selector.

<Warning>
  Don't push branches or pull requests directly to GitHub. Changes pushed outside of Omni won't be properly validated and may break the model.
</Warning>

## Part 3: The migration workflow

This approach works best when you start with your simplest dashboards. The first few teach you the failure modes specific to your Looker model, such as field prefix conventions, which dynamic fields translate cleanly, and how your filter patterns map to Omni. By the time you get to complex dashboards with 50+ tiles and intricate filter wiring, you'll have the playbook down and they'll go much faster.

<Steps>
  <Step title="Inspect the source dashboard">
    Run the [Looker inspect script](#looker-dashboard-inspect-py) against your Looker dashboard ID:

    ```bash theme={null}
    python3 looker_dashboard_inspect.py <dashboard_id>
    ```

    This calls `dashboard_dashboard_elements` and `dashboard_dashboard_filters` and prints a structured summary of every tile in visual order — fields, filters, sorts, pivots, dynamic fields, hidden fields, and filter-listen mappings — plus a ready-to-copy `tile_order` list at the end.

    If you're using Claude Code with the [`looker-to-omni-dashboard` skill](#looker-to-omni-dashboard-skill-md), this step runs automatically when you give it the dashboard ID. Read the output carefully before writing anything.

    See the [Appendix](#looker-dashboard-inspect-py) for the full Python script contents.
  </Step>

  <Step title="Verify and build missing model fields">
    Compare what the Looker dashboard requires against what's in your Omni model. For each tile, you need the topic to exist, every field to be present in the view YAML, and any joins to be in `relationships.yaml`. If anything's missing, add it before writing the build function.

    With `omni-sync` running, every YAML save validates immediately. With the `omni-model-builder` skill active in Claude Code, you can describe what's missing and let the agent handle the edits and validation cycle.
  </Step>

  <Step title="Write the build function and run the script">
    Add a `build_<name>()` function to [`omni_dashboard_builder.py`](#omni-dashboard-builder-py) using the `query()`, `tile()`, and visualization config helpers in the script, register it in `DASHBOARDS`, and run:

    ```bash theme={null}
    python3 scripts/omni_dashboard_builder.py
    ```

    `main()` builds every dashboard registered in `DASHBOARDS`. To build a subset, comment out the others. The script prints the dashboard URL when it finishes — open it immediately and check visually. Broken charts, missing filters, and wrong tile order are all obvious at a glance.

    See the [Appendix](#omni-dashboard-builder-py) for the script file, which includes all the details needed for writing build functions, translating visualizations, wiring filters, and handling edge cases.

    <Warning>
      The script calls `delete_existing_by_name()` before every create, which deletes every document accessible to your API token with that exact name across all folders. Use unique, script-managed names for dashboards built with this script and avoid reusing those names for anything built by hand.
    </Warning>

    <Note>
      Layout, filter wiring, and visualization configs are applied via an export/import cycle using `/api/unstable/` endpoints — confirmed still in beta as of this writing, per [Omni's API docs](/api/content-migration/export-dashboard). This is a field-tested workaround for limitations in the stable create API.

      Omni's newer v2 Documents API (`/v2/documents`) supports layout and dashboard filters natively via `containers` and `controls`. This script will be updated to the v2 create/patch/publish flow instead of the export/import round-trip. Until then, it's worth regression-testing after Omni upgrades if dashboard creation starts breaking.
    </Note>
  </Step>

  <Step title="Iterate">
    Fix what's wrong, rebuild, repeat. The script deletes and recreates cleanly on every run, so there's no stale state to manage.

    If you're in Claude Code, feed errors back to the agent and ask it to update the skill file, as that learning carries forward to every subsequent dashboard automatically.
  </Step>

  <Step title="Merge your migration branch">
    Once you've built and verified all the dashboards you're migrating, merge the branch you started in Part 1:

    ```bash theme={null}
    omni-sync merge-branch <your_model_id> looker-migration --delete-branch
    ```

    If **Pull request required** is enabled in your git settings (see [Part 2](#part-2-configure-omni-git-settings)), open the pull request through the Omni web UI first, then run the command above once it's merged to delete the local branch reference.

    If your environment doesn't require pull requests, skip the PR and merge directly with `--force-override-git-settings`:

    ```bash theme={null}
    omni-sync merge-branch <your_model_id> looker-migration --delete-branch --force-override-git-settings
    ```
  </Step>
</Steps>

## Part 4: Finish the cleanup in Omni

A few things can't be set programmatically and require manual work in the Omni UI after each dashboard is created:

* **KPI tile styling** — Font sizes and alignment must be set in the UI. The field and label persist through rebuilds, but visual styling does not.
* **Markdown and text tiles** — Not migratable; recreate manually
* **Chart color themes** — Must be applied in the UI after creation

<Note>
  Visualization configuration — axis assignment, series colors, chart formatting — has limited API coverage when building dashboards programmatically. Chart type hints set via the API may be overridden by Omni's automatic visualization logic, and detailed axis configs set through the UI won't be reproduced by the builder script.

  For the visual layer, use Omni's built-in AI assistant, accessible from the sidebar in any dashboard, to refine chart formatting after the dashboard structure is in place. Describe what each tile should look like and the Omni Agent will execute the changes.
</Note>

## Next steps

* [Set up local model development](/guides/modeling/local-development)
* [Explore the full Omni agent skills library](/developers/agent-skills)
* [Learn about branch-based model workflows](/content/develop/branch-mode)

## Appendix: Companion files

The following files contain everything needed to run the migration. Click to open and copy the contents.

<AccordionGroup>
  <Accordion title="looker_dashboard_inspect.py" description="Looker dashboard inspector script">
    Run this first against your Looker dashboard ID to get a structured summary of every tile before writing any build functions.

    ```python expandable theme={null}
    """
    Looker Dashboard Inspector
    ==========================
    Fetches ground-truth metadata for a Looker dashboard and prints a structured
    summary of every tile — fields, filters, sorts, pivots, dynamic fields,
    hidden fields, layout position, and filter-listen mappings.

    Run this before writing any build function in omni_dashboard_builder.py.
    The output tells you exactly what each tile needs and in what visual order.

    Usage:
      python3 looker_dashboard_inspect.py <dashboard_id>

    Requirements:
      pip install looker-sdk

    Environment variables (set in shell before running):
      LOOKERSDK_BASE_URL       https://<your-instance>.looker.com
      LOOKERSDK_CLIENT_ID      your Looker API client ID
      LOOKERSDK_CLIENT_SECRET  your Looker API client secret
    """

    import json
    import os
    import sys

    try:
        import looker_sdk
        from looker_sdk import models40 as models
    except ImportError:
        raise SystemExit(
            "looker-sdk is required. Install it with: pip install looker-sdk"
        )

    # ── Config ────────────────────────────────────────────────────────────────────

    for var in ("LOOKERSDK_BASE_URL", "LOOKERSDK_CLIENT_ID", "LOOKERSDK_CLIENT_SECRET"):
        if not os.environ.get(var):
            raise SystemExit(
                f"Missing required environment variable: {var}\n"
                "Set LOOKERSDK_BASE_URL, LOOKERSDK_CLIENT_ID, and "
                "LOOKERSDK_CLIENT_SECRET before running."
            )

    # ── Helpers ───────────────────────────────────────────────────────────────────

    def _j(obj) -> str:
        """Pretty-print a value as compact JSON."""
        return json.dumps(obj, default=str)


    def _section(title: str):
        print(f"\n{'─' * 60}")
        print(f"  {title}")
        print('─' * 60)


    def inspect(dashboard_id: str):
        sdk = looker_sdk.init40()

        # ── Dashboard top-level ───────────────────────────────────────────────────
        dashboard = sdk.dashboard(dashboard_id)
        _section(f"Dashboard: {dashboard.title}  (id={dashboard_id})")
        print(f"  folder:      {getattr(dashboard.folder, 'name', None)}")

        # ── Dashboard-level filters ───────────────────────────────────────────────
        filters = sdk.dashboard_dashboard_filters(dashboard_id)
        if filters:
            _section("Dashboard filters")
            for f in filters:
                print(f"\n  [{f.name}]")
                print(f"    title:         {f.title}")
                print(f"    type:          {f.type}")
                print(f"    dimension:     {f.dimension}")
                print(f"    explore:       {f.explore}  model: {f.model}")
                print(f"    default_value: {f.default_value!r}")
        else:
            print("\n  (no dashboard-level filters)")

        # ── Tiles ─────────────────────────────────────────────────────────────────
        elements = sdk.dashboard_dashboard_elements(dashboard_id)

        # Sort by visual layout order: top-to-bottom, left-to-right
        elements = sorted(elements, key=lambda e: (e.row or 0, e.column or 0))

        _section(f"Tiles ({len(elements)} total, sorted by layout position)")

        for el in elements:
            # Skip text/markdown tiles — no Omni equivalent
            if el.type == "text":
                print(f"\n  ── [TEXT TILE — skip] title={el.title!r}")
                continue

            print(f"\n  ══ {el.title!r}")
            print(f"     type:     {el.type}")
            print(f"     layout:   row={el.row}  col={el.column}  w={el.width}  h={el.height}")

            q = None
            if el.result_maker and el.result_maker.query:
                q = el.result_maker.query
            elif el.query:
                q = el.query

            if q:
                print(f"\n     model/explore:  {q.model}.{q.view}")
                print(f"     fields:         {_j(q.fields)}")

                if q.filters:
                    print(f"     filters:")
                    for k, v in q.filters.items():
                        print(f"       {k}: {v!r}")

                if q.filter_expression:
                    print(f"     filter_expression: {q.filter_expression}")

                if q.sorts:
                    print(f"     sorts:          {_j(q.sorts)}")

                if q.pivots:
                    print(f"     pivots:         {_j(q.pivots)}")

                if q.hidden_fields:
                    print(f"     hidden_fields:  {_j(q.hidden_fields)}")
                    print(f"     ⚠  hidden_fields are computation-only — do NOT include in Omni tile fields")

                if q.dynamic_fields:
                    try:
                        dfs = json.loads(q.dynamic_fields)
                    except (TypeError, json.JSONDecodeError):
                        dfs = q.dynamic_fields
                    print(f"     dynamic_fields:")
                    for df in (dfs if isinstance(dfs, list) else [dfs]):
                        category = df.get("category", df.get("calculation_type", "unknown"))
                        label    = df.get("label", df.get("label_short", ""))
                        based_on = df.get("based_on", "")
                        df_filters = df.get("filters", {})
                        print(f"       category={category!r}  label={label!r}  based_on={based_on!r}")
                        if df_filters:
                            print(f"         filters: {_j(df_filters)}")

                if q.limit:
                    print(f"     limit:          {q.limit}")

                if q.vis_config:
                    vis_type = q.vis_config.get("type") if isinstance(q.vis_config, dict) else None
                    print(f"     vis_type:       {vis_type}")

            # Filter-listen mappings
            if el.result_maker and el.result_maker.filterables:
                for filterable in el.result_maker.filterables:
                    listens = [l.dashboard_filter_name for l in (filterable.listen or [])]
                    if listens:
                        print(f"     listens_to:     {listens}")

        # ── Summary: tile order ───────────────────────────────────────────────────
        _section("tile_order (copy into DASHBOARDS dict)")
        visible = [el for el in elements if el.type != "text"]
        print("\n  tile_order = [")
        for el in visible:
            print(f"      {el.title!r},")
        print("  ]")


    # ── Entry point ───────────────────────────────────────────────────────────────

    if __name__ == "__main__":
        if len(sys.argv) < 2:
            raise SystemExit("Usage: python3 looker_dashboard_inspect.py <dashboard_id>")
        inspect(sys.argv[1])
    ```
  </Accordion>

  <Accordion title="looker-to-omni-dashboard-skill.md" description="Claude Code / Cursor agent skill">
    <Note>
      Copy the full contents into `.claude/agents/looker-to-omni-dashboard.md` in your repo.
    </Note>

    ````markdown expandable theme={null}
    description: Migrate a Looker dashboard to Omni by adding a build function to scripts/omni_dashboard_builder.py. Covers the full workflow — Looker API inspection, field mapping, filter wiring, layout, and tile ordering. Use this whenever someone wants to migrate, rebuild, or recreate a Looker dashboard in Omni.
    argument-hint: "<looker_dashboard_id>"
    ---

    # /looker-to-omni-dashboard

    Migrate a Looker dashboard to Omni by adding a `build_<name>()` function to `scripts/omni_dashboard_builder.py`. Never write a standalone script. Never reconstruct field lists from manifest files.

    ---

    ## Configuration

    - Script: `scripts/omni_dashboard_builder.py`
    - Model ID: `<your-omni-model-id>`
    - Looker base URL: `$LOOKERSDK_BASE_URL` (already in shell — never source a file)
    - Omni base URL: `$OMNI_BASE_URL`

    ---

    ## Step 1 — Inspect the Looker Dashboard

    Always fetch ground-truth data from the Looker API. Run `looker_dashboard_inspect.py <dashboard_id>` to get every tile's fields, filters, sorts, pivots, dynamic fields, and filter-listen mappings sorted by visual layout order (row, column).

    Read the output carefully before writing any code. Note:
    - Tile titles (these become tile `name` args and drive `tile_order`)
    - Fields per tile (`model.explore` maps to Omni `view.field`)
    - Filter keys and values per tile
    - Which dashboard filters each tile listens to (`listens_to:` lines)
    - Any `dynamic_fields` — classify each one (see Step 1c below)
    - Any `hidden_fields` — fields in the query for computation only; do not include them in the Omni tile's `fields:` list
    - Any `pivots:` lines — must be translated (see Step 1d below)
    - Any `type == "text"` elements — skip them entirely (no Omni equivalent)

    ---

    ## Step 1b — Looker Parameters and Templated Filters

    Looker `parameter` fields map to Omni **templated filters**:

    ```yaml
    filters:
      my_filter_name:
        type: number
        label: My Filter
        suggest_from_field: users.user_id

    my_dimension:
      sql: |
        CASE
          WHEN {{# users.my_filter_name.filter }} field_name {{/ users.my_filter_name.filter }}
          THEN 'Matches'
          ELSE 'No Match'
        END
    ```

    Only Mustache block syntax (`{{# ... }}`) is supported. `{{ }}` and `{% %}` are not.

    **Multi-alias problem:** use the view's canonical `schema__table` name in the Mustache reference — not a join alias. An unset block collapses to `TRUE`, so OR-connected blocks make every row match.

    ---

    ## Step 1c — Classifying Dynamic Fields

    | `category` / `calculation_type` | What to do |
    |---|---|
    | `calculation_type: group_by` | Translate to a CASE WHEN dimension in the view |
    | `category: measure` — filters reference only fields in the same view | Translate to a view measure using `filters:` block |
    | `category: measure` — filters reference fields from other joined views | Build a PDT |
    | `category: table_calculation` — simple arithmetic between two native measures | Translate to a view measure |
    | `category: table_calculation` — uses `pivot_where()` as the primary metric | Translate whole tile to pre-aggregated measure + grouped bar chart |
    | `category: table_calculation` — references other table calcs or Looker runtime values | Skip |
    | `category: dimension` with raw LookML expression | Translate if CASE WHEN or string ops; skip if references `${measure}` fields |

    ---

    ## Step 1d — Translating Pivots

    - **Table tiles** — add `"pivots": ["view.field"]` to the query dict
    - **Chart tiles** — pivot is handled by the `vis_spec` color field; no explicit pivot needed

    A Looker chart pivot always maps to a stacked bar in Omni. Never use `_stack: "group"` for a chart that has `pivots:` in the inspect output.

    ---

    ## Step 2 — Verify Fields Exist in Omni

    1. Confirm the topic exists and its `base_view:` matches what you expect
    2. Confirm each `view.field` exists in the corresponding view YAML
    3. Confirm filter fields exist in the view YAML
    4. Confirm any joins are in `relationships.yaml` and in the topic's `joins:` block

    **Field prefix rules:** base view fields use `schema__table` format; joined view fields use the join alias as-is.

    If anything is missing, use the `omni-model-builder` skill to add it before writing the build function.

    ---

    ## Step 3 — Write the Build Function

    ```python
    def build_my_dashboard() -> list[dict]:
        tiles: list[dict] = []

        tiles.append(tile(
            "Total Orders", "1",
            query(view="analytics__orders", topic="orders", fields=["orders.order_count"]),
            config=cfg_kpi("orders.order_count", "Total Orders"),
        ))

        tiles.append(tile(
            "Revenue by Region", "2",
            query(
                view="analytics__orders", topic="orders",
                fields=["orders.region", "orders.total_revenue"],
                sorts=[sort_desc("orders.total_revenue")],
            ),
            vis_spec=cfg_bar(x_field="orders.region", series_fields=["orders.total_revenue"]),
        ))

        return tiles
    ```

    ### Visualization approach

    | Tile type | Use |
    |---|---|
    | KPI / single value | `config=cfg_kpi(field, label)` |
    | Stretch table | `config=cfg_table()` |
    | Line chart | `vis_spec=cfg_line(x_field, measure_field, color_field)` |
    | Bar / stacked bar | `vis_spec={...}` (see patterns below) |
    | Area chart | `chart_type="areaColor"` |

    **Stacked bar (use when inspect output shows `pivots:`):**

    ```python
    vis_spec={
        "x": {"field": {"name": "view.x_dim"}},
        "mark": {"type": "bar"},
        "color": {"field": {"name": "view.color_dim"}, "_stack": "stack", "legendPosition": "bottom"},
        "series": [{"field": {"name": "view.measure"}, "yAxis": "y", "mark": {"type": "bar"}, "color": {"_stack": "stack"}}],
        "version": 0, "behaviors": {"stackMultiMark": False},
        "configType": "cartesian", "_dependentAxis": "y",
    }
    ```

    **Grouped multi-measure bar (no pivot):**

    ```python
    vis_spec={
        "x": {"field": {"name": "view.x_dim"}},
        "y": {"color": {"_stack": "group"}}, "y2": {"color": {"_stack": "group"}},
        "mark": {"type": "bar"}, "color": {"_stack": "group"},
        "series": [
            {"field": {"name": "view.measure_1"}, "yAxis": "y", "mark": {"type": "bar"}, "color": {"_stack": "group"}},
            {"field": {"name": "view.measure_2"}, "yAxis": "y", "mark": {"type": "bar"}, "color": {"_stack": "group"}},
        ],
        "version": 0, "behaviors": {"stackMultiMark": False},
        "configType": "cartesian", "_dependentAxis": "y",
    }
    ```

    ---

    ## Step 4 — Define Layout

    Grid is 24 units wide. Use fixed heights: KPI = 23, table = 26, chart = 30.

    ```python
    MY_LAYOUT = [
        {"i": "1", "x":  0, "y":  0, "w":  8, "h": 23},
        {"i": "2", "x":  8, "y":  0, "w":  8, "h": 23},
        {"i": "3", "x":  0, "y": 23, "w": 24, "h": 30},
    ]
    ```

    ---

    ## Step 5 — Wire Dashboard Filters

    ```python
    MY_FILTER_CONFIG = {
        "date_filter": {
            "type": "date", "label": "Date range",
            "fieldName": "orders.created[date]",
            "kind": "TIME_FOR_INTERVAL_DURATION",
            "left_side": "6 months ago", "right_side": "6 months",
            "is_negative": False,
        },
    }
    MY_FILTER_ORDER = ["date_filter"]
    MY_TILE_FILTER_MAP = {
        "1": {"date_filter": "orders.created[date]"},
        "2": {"date_filter": False},
    }
    ```

    Every `fid` in `filterConfig` must appear in every tile's entry. Use `False` to exclude. Never use `[fiscal_quarter]` or `[quarter]` as filter keys — use `[date]` or `[month]`.

    ---

    ## Step 6 — Register in DASHBOARDS

    ```python
    DASHBOARDS = {
        "my-dash": {
            "name":            "My Dashboard",
            "build":           build_my_dashboard,
            "layout":          MY_LAYOUT,
            "folder":          "dashboards/folder",
            "filter_config":   MY_FILTER_CONFIG,
            "filter_order":    MY_FILTER_ORDER,
            "tile_filter_map": MY_TILE_FILTER_MAP,
            "tile_order":      ["Total Orders", "Revenue by Region"],
        },
    }
    ```

    ---

    ## Step 7 — Run It

    ```bash
    python3 scripts/omni_dashboard_builder.py
    ```

    `main()` builds every dashboard in `DASHBOARDS`. Comment out entries you don't want to run.

    ---

    ## Step 8 — Post-creation Manual Steps

    - **KPI tile styling** — font sizes and alignment must be set in the UI
    - **Markdown tiles** — not migratable; recreate manually
    - **Chart color themes** — set in the UI after creation

    ---

    ## Common Errors

    | Error | Cause | Fix |
    |-------|-------|-----|
    | `e.values.join is not a function` | Raw string/array passed as filter value | Use `f_str(["val"])`, `f_bool(True)`, etc. |
    | `No such view` | `table` field uses display label or wrong format | Use `schema__table` double-underscore format |
    | `fields outside of topic` | Field prefix uses view file name instead of join alias | Check topic YAML `joins:` — use join alias, not view file name |
    | Filter silently ignored | `tileFilterMap` entry missing a filter ID | Add every `fid` to every tile's entry; use `False` to exclude |
    | Tile returns 0 rows silently | Date filter key uses `[fiscal_quarter]` or `[quarter]` | Use `[date]` or `[month]` for filter key |
    | "No chart available" | `visType: "basic"` set with an empty spec | Only set `visType: "basic"` when a non-empty `vis_spec` fills the spec |
    | Wrong tile order | `tile_order` list doesn't match tile `name` exactly | Names are case-sensitive |

    ---

    ## Related Skills

    - **omni-model-builder** — add missing fields/topics before building
    - **omni-sync** — sync model file changes to the remote branch
    ````
  </Accordion>

  <Accordion title="omni_dashboard_builder.py" description="Python builder script">
    Add your `build_<name>()` functions and register them in `DASHBOARDS`, then run with `python3 scripts/omni_dashboard_builder.py`.

    ```python expandable theme={null}
    """
    Omni Dashboard Builder (public/example version)
    ================================================
    Programmatically create/rebuild Omni dashboards via the API.

    Usage:
      OMNI_BASE_URL=https://<tenant>.omniapp.co \
      OMNI_API_KEY=<your-key> \
      OMNI_MODEL_ID=<your-model-id> \
      python3 scripts/omni_dashboard_builder.py
    """

    import json
    import ssl
    import urllib.request
    import urllib.error
    import urllib.parse
    import os
    from typing import Any

    BASE_URL        = os.environ.get("OMNI_BASE_URL", "https://<tenant>.omniapp.co")
    API_KEY         = os.environ.get("OMNI_API_KEY", "")
    SHARED_MODEL_ID = os.environ.get("OMNI_MODEL_ID", "")

    if not API_KEY or not SHARED_MODEL_ID:
        raise SystemExit("Set OMNI_BASE_URL, OMNI_API_KEY, and OMNI_MODEL_ID before running.")

    _ctx = ssl.create_default_context()
    # SSL troubleshooting: if you see CERTIFICATE_VERIFY_FAILED in a corporate environment,
    # set SSL_CERT_FILE to your CA bundle path. Never disable TLS verification in production.

    def api(method, path, body=None, params=None):
        url = f"{BASE_URL}/api{path}"
        if params:
            url += "?" + urllib.parse.urlencode(params)
        data = json.dumps(body).encode() if body else None
        req = urllib.request.Request(url, data=data, method=method, headers={
            "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json",
        })
        try:
            with urllib.request.urlopen(req, context=_ctx) as r:
                return json.loads(r.read())
        except urllib.error.HTTPError as e:
            print(f"HTTP {e.code}: {e.read().decode()[:400]}")
            return None

    def delete_document(doc_id):
        if api("DELETE", f"/v1/documents/{doc_id}") is not None:
            print(f"Deleted {doc_id}")

    def delete_existing_by_name(name):
        """WARNING: deletes every accessible document with this exact name across all folders.
        Use unique, script-managed names and never reuse them for hand-built content."""
        cursor = None
        while True:
            params = {"pageSize": "100"}
            if cursor:
                params["cursor"] = cursor
            data = api("GET", "/v1/documents", params=params)
            if not data:
                break
            for doc in data.get("records", []):
                if doc.get("name") == name:
                    delete_document(doc["identifier"])
            page = data.get("pageInfo", {})
            if not page.get("hasNextPage"):
                break
            cursor = page.get("nextCursor")

    def export_document(doc_id):
        """Uses /api/unstable/ endpoints — field-tested workaround for layout, tileFilterMap,
        and vis config persistence, still beta per docs.omni.co as of this writing. Move to the
        v2 documents create/patch/publish flow (containers/controls) once that schema is public.
        Regression-test after Omni upgrades if creation breaks."""
        req = urllib.request.Request(
            f"{BASE_URL}/api/unstable/documents/{doc_id}/export",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(req, context=_ctx) as r:
            return json.loads(r.read())

    def create_dashboard(name, tiles, layout=None, folder_path=None, model_id=SHARED_MODEL_ID,
                        filter_config=None, filter_order=None, tile_filter_map=None, tile_order=None):
        delete_existing_by_name(name)
        if tile_order is not None:
            order_index = {n: i for i, n in enumerate(tile_order)}
            tiles = sorted(tiles, key=lambda t: order_index.get(t["name"], 9999))
        old_to_new = {t["queryIdentifierMapKey"]: str(i + 1) for i, t in enumerate(tiles)}
        for t in tiles:
            t["queryIdentifierMapKey"] = old_to_new[t["queryIdentifierMapKey"]]
        if layout is not None:
            layout = [{**item, "i": old_to_new[item["i"]]} for item in layout if item["i"] in old_to_new]
        if tile_filter_map is not None:
            tile_filter_map = {old_to_new[k]: v for k, v in tile_filter_map.items() if k in old_to_new}

        post_body = {"modelId": model_id, "name": name, "queryPresentations": tiles}
        if filter_config:
            post_body["filterConfig"] = filter_config
            post_body["filterOrder"]  = filter_order or list(filter_config.keys())
        result = api("POST", "/v1/documents", post_body)
        if not result:
            return None
        doc_id = result["workbook"]["identifier"]

        if layout is None and tile_filter_map is None and folder_path is None:
            print(f"Created: {BASE_URL}/dashboards/{doc_id}")
            return doc_id

        if layout is not None:
            pos_by_key = {item["i"]: (item["y"], item["x"]) for item in layout}
            tiles_sorted = sorted(tiles, key=lambda t: pos_by_key.get(t["queryIdentifierMapKey"], (9999, 9999)))
            old_to_new = {t["queryIdentifierMapKey"]: str(i + 1) for i, t in enumerate(tiles_sorted)}
            for t in tiles_sorted:
                t["queryIdentifierMapKey"] = old_to_new[t["queryIdentifierMapKey"]]
            layout = [{**item, "i": old_to_new[item["i"]]} for item in layout if item["i"] in old_to_new]
            if tile_filter_map is not None:
                tile_filter_map = {old_to_new[k]: v for k, v in tile_filter_map.items() if k in old_to_new}
            post_body["queryPresentations"] = tiles_sorted
            result2 = api("POST", "/v1/documents", post_body)
            if not result2:
                return None
            delete_document(doc_id)
            doc_id = result2["workbook"]["identifier"]

        exp = export_document(doc_id)
        if layout is not None:
            exp["dashboard"]["metadata"]["layouts"]["lg"] = layout
        if tile_filter_map is not None:
            exp["dashboard"]["metadata"]["tileFilterMap"] = tile_filter_map

        vis_spec_map   = {t["name"]: t["vis_spec"]   for t in tiles if "vis_spec" in t}
        vis_type_map   = {t["name"]: t["visType"]    for t in tiles if t.get("visType")}
        chart_type_map = {t["name"]: t["chart_type"] for t in tiles if t.get("chart_type")}
        if vis_spec_map or vis_type_map or chart_type_map:
            memberships = (exp["dashboard"].get("queryPresentationCollection", {})
                          .get("queryPresentationCollectionMemberships", []))
            for m in memberships:
                qp = m.get("queryPresentation", m)
                tile_name = qp.get("name")
                if tile_name in vis_spec_map:
                    if "visConfig" not in qp or qp["visConfig"] is None:
                        qp["visConfig"] = {}
                    spec = vis_spec_map[tile_name]
                    qp["visConfig"]["spec"] = spec
                    if "markdownConfig" in spec:
                        qp["visConfig"]["chartType"] = "kpi"
                        qp["visConfig"]["visType"]   = "omni-kpi"
                    else:
                        qp["visConfig"]["chartType"] = None
                        qp["visConfig"]["visType"]   = "basic"
                    qp["automaticVis"] = False
                elif tile_name in vis_type_map:
                    if "visConfig" not in qp or qp["visConfig"] is None:
                        qp["visConfig"] = {}
                    qp["visConfig"]["visType"] = vis_type_map[tile_name]
                if tile_name in chart_type_map:
                    qp["prefersChart"] = True
                    qp["automaticVis"] = True

        import_body = {
            "baseModelId": model_id, "exportVersion": "0.1",
            "document": exp["document"], "dashboard": exp["dashboard"],
            "queryModels": exp.get("queryModels", {}), "workbookModel": exp.get("workbookModel"),
        }
        if filter_config:
            import_body["filterConfig"] = filter_config
            import_body["filterOrder"]  = filter_order or list(filter_config.keys())
        if folder_path is not None:
            import_body["folderPath"] = folder_path

        imported = api("POST", "/unstable/documents/import", import_body)
        if not imported:
            return None
        ident = imported["workbook"]["identifier"]
        delete_document(doc_id)
        print(f"Created: {BASE_URL}/dashboards/{ident}")
        return ident

    # ── Filter helpers ─────────────────────────────────────────────────────────────

    def f_str(values):         return {"type": "string",  "kind": "EQUALS",                   "values": values,  "is_negative": False}
    def f_str_neg(values):     return {"type": "string",  "kind": "EQUALS",                   "values": values,  "is_negative": True}
    def f_str_contains(values):return {"type": "string",  "kind": "CONTAINS",                 "values": values,  "is_negative": False}
    def f_str_contains_neg(v): return {"type": "string",  "kind": "CONTAINS",                 "values": v,       "is_negative": True}
    def f_bool(value):         return {"type": "boolean", "is_negative": not value, "treat_nulls_as_false": False}
    def f_num(values):         return {"type": "number",  "kind": "EQUALS",                   "values": values,  "is_negative": False}
    def f_not_null():          return {"type": "null",    "is_negative": True}
    def f_date_after(rel):     return {"type": "date",    "kind": "ON_OR_AFTER",              "left_side": rel,  "is_negative": False}
    def f_date_duration(s, d): return {"type": "date",    "kind": "TIME_FOR_INTERVAL_DURATION","left_side": s, "right_side": d, "is_negative": False}

    def sort_asc(col):  return {"column_name": col, "sort_descending": False}
    def sort_desc(col): return {"column_name": col, "sort_descending": True}

    # ── Query builder ──────────────────────────────────────────────────────────────

    def query(view, topic, fields, filters=None, sorts=None, limit=500):
        return {
            "table": view, "join_paths_from_topic_name": topic,
            "fields": fields, "filters": filters or {}, "sorts": sorts or [],
            "limit": limit, "version": 8, "modelId": SHARED_MODEL_ID,
            "metadata": {}, "row_totals": {}, "pivots": [], "calculations": [],
            "fill_fields": [], "join_via_map": {}, "column_totals": {},
            "custom_summary_types": {}, "rewriteSql": True, "default_group_by": True,
            "dbtMode": False, "dimensionIndex": 0, "column_limit": 50, "userEditedSQL": "",
        }

    def cfg_kpi(field, label):
        import uuid
        return {
            "alignment": "left", "fontKPISize": "", "fontBodySize": "", "fontLabelSize": "",
            "verticalAlignment": "top",
            "markdownConfig": [{"id": str(uuid.uuid4()), "type": "number", "config": {
                "field": {"row": "_first", "field": {"name": field, "pivotMap": {}}, "label": {"value": label}},
                "descriptionBefore": "",
            }}],
        }

    def cfg_table():
        return {"tableType": "stretch", "rowBanding": {"enabled": False, "bandSize": 1},
                "expandedRows": {}, "hideIndexColumn": False, "truncateHeaders": True,
                "showDescriptions": True, "visColumnDisplay": "hide-view-name"}

    def cfg_line(x_field, measure_field, color_field):
        return {
            "x": {"field": {"name": x_field}}, "mark": {"type": "line"},
            "color": {"field": {"name": color_field}},
            "series": [{"field": {"name": measure_field}, "yAxis": "y"}],
            "tooltip": [{"field": {"name": x_field}}, {"field": {"name": measure_field}}, {"field": {"name": color_field}}],
            "version": 0, "behaviors": {"stackMultiMark": False}, "configType": "cartesian", "_dependentAxis": "y",
        }

    _X_HORIZ = {"axis": {"label": {"format": {"angle": 0}}}}

    def cfg_bar(x_field, series_fields, stack=False):
        color = {"_stack": "stack"} if stack else {}
        return {
            "x": {"field": {"name": x_field}, **_X_HORIZ}, "mark": {"type": "bar"}, "color": color,
            "series": [{"field": {"name": f}, "yAxis": "y"} for f in series_fields],
            "tooltip": [{"field": {"name": x_field}}] + [{"field": {"name": f}} for f in series_fields],
            "version": 0, "behaviors": {"stackMultiMark": False}, "configType": "cartesian", "_dependentAxis": "y",
        }

    def tile(name, key, q, chart_type=None, prefers_chart=None, config=None, vis_spec=None):
        if chart_type:
            q = {**q, "visConfig": {"chartType": chart_type}}
        is_kpi   = isinstance(config, dict) and "markdownConfig" in config
        is_table = isinstance(config, dict) and "tableType" in config
        if is_kpi:
            vis_spec, config, vis_type = config, None, "omni-kpi"
        elif is_table:
            vis_type = "omni-table"
        elif vis_spec is not None:
            vis_type = "basic"
        else:
            vis_type = None
        prefers = prefers_chart if prefers_chart is not None else (vis_spec is not None or chart_type is not None)
        t = {"name": name, "prefersChart": prefers, "visType": vis_type,
            "queryIdentifierMapKey": key, "topicName": q.get("join_paths_from_topic_name"), "query": q}
        if chart_type is not None: t["chart_type"] = chart_type
        if config is not None:     t["config"] = config
        if vis_spec is not None:   t["vis_spec"] = vis_spec
        return t

    # ── Example dashboard ──────────────────────────────────────────────────────────

    ORDERS_VIEW, ORDERS_TOPIC = "analytics__orders", "orders"

    SALES_FILTER_CONFIG = {"date_filter": {
        "type": "date", "label": "Date range",
        "fieldName": f"{ORDERS_TOPIC}.created[date]",
        "kind": "TIME_FOR_INTERVAL_DURATION",
        "left_side": "6 months ago", "right_side": "6 months", "is_negative": False,
    }}
    SALES_FILTER_ORDER = ["date_filter"]
    SALES_LAYOUT = [
        {"i": "1", "x":  0, "y":  0, "w":  8, "h": 23},
        {"i": "2", "x":  8, "y":  0, "w":  8, "h": 23},
        {"i": "3", "x": 16, "y":  0, "w":  8, "h": 23},
        {"i": "4", "x":  0, "y": 23, "w": 24, "h": 30},
        {"i": "5", "x":  0, "y": 53, "w": 24, "h": 26},
    ]
    _F_DATE = {"date_filter": f"{ORDERS_TOPIC}.created[date]"}
    SALES_TILE_FILTER_MAP = {str(i): _F_DATE for i in range(1, 6)}

    def build_sales_overview():
        tiles = []
        tiles.append(tile("Total Orders",  "1", query(ORDERS_VIEW, ORDERS_TOPIC, ["orders.order_count"]),  config=cfg_kpi("orders.order_count",  "Total Orders")))
        tiles.append(tile("Total Revenue", "2", query(ORDERS_VIEW, ORDERS_TOPIC, ["orders.total_revenue"]), config=cfg_kpi("orders.total_revenue", "Total Revenue")))
        tiles.append(tile("Revenue by Region", "3",
            query(ORDERS_VIEW, ORDERS_TOPIC, ["orders.region", "orders.total_revenue"], sorts=[sort_desc("orders.total_revenue")]),
            vis_spec=cfg_bar("orders.region", ["orders.total_revenue"])))
        tiles.append(tile("Orders by Status", "4",
            query(ORDERS_VIEW, ORDERS_TOPIC, ["orders.status", "orders.order_count", "orders.total_revenue"],
                  filters={"orders.status": f_not_null()}, sorts=[sort_desc("orders.order_count")]),
            config=cfg_table()))
        return tiles

    DASHBOARDS = {
        "sales-overview": {
            "name":            "Sales Overview (example)",
            "build":           build_sales_overview,
            "layout":          SALES_LAYOUT,
            "folder":          "examples",
            "filter_config":   SALES_FILTER_CONFIG,
            "filter_order":    SALES_FILTER_ORDER,
            "tile_filter_map": SALES_TILE_FILTER_MAP,
        },
    }

    def main():
        for key, cfg in DASHBOARDS.items():
            print(f"\n── Building {key} ──")
            tiles = cfg["build"]()
            create_dashboard(
                name=cfg["name"], tiles=tiles, layout=cfg.get("layout"),
                folder_path=cfg.get("folder"), filter_config=cfg.get("filter_config"),
                filter_order=cfg.get("filter_order"), tile_filter_map=cfg.get("tile_filter_map"),
                tile_order=cfg.get("tile_order"),
            )

    if __name__ == "__main__":
        main()
    ```
  </Accordion>
</AccordionGroup>


# Improving date flexibility with templated filters
Source: https://docs.omni.co/guides/modeling/date-flexibility-templated-filters

A guide to going beyond the out of the box controls to give users more flexibility to manipulate dates by utilizing templated filters.

<GuideSidebar />

<GuideTitle title="Improving date flexibility with templated filters" />

Omni provides powerful, built-in options for manipulating dates on a dashboard, such as [time frame switchers](/visualize-present/dashboards/controls) and [period over period analysis](/visualize-present/dashboards/controls).

However, if you want to give your users even more control, [templated filters](/modeling/templated-filters) are the answer. This guide walks through two advanced patterns for date flexibility:

1. **Granularity control with automated filtering:** A single control that changes the granularity of time series charts (e.g., month to quarter) while simultaneously filtering to the "last complete" period.
2. **The "everything" toggles:** Giving you the ability to swap the underlying date field, timeframe granularity, and date range all from a single dashboard interface using multiple filters.

Implementing these patterns allows you to create a system where you can redefine the context of your data on the fly.

## Requirements

To follow the steps in this guide, you'll need:

* **Modeler** or **Connection Admin** permissions for the model you want to work with
* A basic understanding of [templated filters](/modeling/templated-filters)

## Pattern 1: Dynamic charts with "last complete period" logic

When looking at data over time, comparing a partial current month against a full previous month can be misleading. This pattern creates a dimension that automatically nulls out the current, incomplete period based on the granularity you've selected.

<Steps>
  <Step title="Create a filter-only field for granularity">
    In your model, define a string filter that will act as the toggle:

    ```yaml theme={null}
      date_granularity:
        type: string
        label: Date Granularity
        description: Select the timeframe for the completion filter
        suggestion_list:
          - value: Month
          - value: Quarter
          - value: Year
        filter_single_select_only: true
    ```
  </Step>

  <Step title="Build the dynamic date dimension">
    Next, create a custom dimension using templated filters. This dimension will evaluate the user's selection and apply the "last complete" logic.

    For example, when `Quarter` is selected, the `CASE` statement returns `NULL` for the current (incomplete) quarter and truncates to the quarter otherwise. The same pattern applies for `Year` and `Month`.

    Use the following code to add the dimension, replacing `saas__opportunities.created_date` with your own view and date field:

    ```yaml wrap theme={null}
      created_date_completed_periods:
        sql: |-
          CASE
            WHEN {{# saas__opportunities.date_granularity.filter }} 'Quarter' {{/ saas__opportunities.date_granularity.filter }}
              THEN CASE
                WHEN DATE_TRUNC('quarter', ${saas__opportunities.created_date}) >= DATE_TRUNC('quarter', CURRENT_DATE)
                  THEN NULL
                ELSE DATE_TRUNC('quarter', ${saas__opportunities.created_date})
              END
            WHEN {{# saas__opportunities.date_granularity.filter }} 'Year' {{/ saas__opportunities.date_granularity.filter }}
              THEN CASE
                WHEN DATE_TRUNC('year', ${saas__opportunities.created_date}) >= DATE_TRUNC('year', CURRENT_DATE)
                  THEN NULL
                ELSE DATE_TRUNC('year', ${saas__opportunities.created_date})
              END
            ELSE CASE
              WHEN DATE_TRUNC('month', ${saas__opportunities.created_date}) >= DATE_TRUNC('month', CURRENT_DATE)
                THEN NULL
              ELSE DATE_TRUNC('month', ${saas__opportunities.created_date})
            END
          END
        label: Created Date (Completed Periods)
    ```
  </Step>

  <Step title="Implement on a dashboard">
    1. In a workbook, **select** the `Created Date (Completed Periods)` dimension for your time series charts.
    2. Navigate to your dashboard and click **Add > Filter**.
    3. Configure the filter to point at your `date_granularity` field.

    Now when the filter is used, the connected tiles will automatically update to use the selected granularity:

    <Frame>
      <img alt="Date Granularity" />
    </Frame>
  </Step>
</Steps>

## Pattern 2: The "everything" toggles

This pattern gives you three independent dashboard controls: the date field (e.g., switching from **Created Date** to **Shipped Date**), the granularity, and the date range window.

<Steps>
  <Step title="Define the selection filters">
    In your model, create two [filter-only fields](/modeling/templated-filters/parameters): one for the field choice and one for the granularity.

    ```yaml wrap theme={null}
      as_of_date_field:
        type: string
        label: As of Date
        suggestion_list:
          - value: Created At
          - value: Shipped At
          - value: Delivered At
          - value: Returned At
        default_filter:
          is: Created At
        filter_single_select_only: true

      as_of_date_field_granularity:
        type: string
        label: Date Granularity
        suggestion_list:
          - value: Daily
          - value: Weekly
          - value: Monthly
        default_filter:
          is: Daily
        filter_single_select_only: true
    ```
  </Step>

  <Step title="Create the dynamic logic">
    This pattern requires two dimensions to work: one to swap the raw date field, and the second to truncate that field based on the selected granularity.

    <Tabs>
      <Tab title="Dimension 1: Swap raw date field">
        The `dynamic_date` dimension uses a `CASE` statement to swap the underlying source column (for example, `created_at` vs. `shipped_at`) based on the filter selection:

        ```yaml wrap theme={null}
          dynamic_date:
            sql: |-
              CASE
                WHEN {{# order_items.as_of_date_field.filter }} 'Created At' {{/ order_items.as_of_date_field.filter }} THEN ${order_items.created_at}
                WHEN {{# order_items.as_of_date_field.filter }} 'Shipped At' {{/ order_items.as_of_date_field.filter }} THEN ${order_items.shipped_at}
                WHEN {{# order_items.as_of_date_field.filter }} 'Delivered At' {{/ order_items.as_of_date_field.filter }} THEN ${order_items.delivered_at}
                WHEN {{# order_items.as_of_date_field.filter }} 'Returned At' {{/ order_items.as_of_date_field.filter }} THEN ${order_items.returned_at}
              ELSE ${order_items.created_at}
              END
            label: Dynamic Date
        ```
      </Tab>

      <Tab title="Dimension 2: Truncate field">
        The `dynamic_date_granularity` dimension takes the result of `dynamic_date` and applies the truncation level (daily, weekly, or monthly) that you've selected:

        ```yaml wrap theme={null}
          dynamic_date_granularity:
            sql: |-
              CASE
                WHEN {{# order_items.as_of_date_field_granularity.filter }} 'Daily' {{/ order_items.as_of_date_field_granularity.filter }} THEN ${order_items.dynamic_date[date]}
                WHEN {{# order_items.as_of_date_field_granularity.filter }} 'Weekly' {{/ order_items.as_of_date_field_granularity.filter }} THEN ${order_items.dynamic_date[week]}
                WHEN {{# order_items.as_of_date_field_granularity.filter }} 'Monthly' {{/ order_items.as_of_date_field_granularity.filter }} THEN ${order_items.dynamic_date[month]}
              ELSE ${order_items.dynamic_date[date]}
              END
            label: Dynamic Date Granularity
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Build the view">
    1. In a workbook, build your charts using the `Dynamic Date Granularity` dimension.
    2. When finished, complete the following on the document's dashboard:
       1. Add filters to the dashboard for both `As of Date` and `Date Granularity`.
       2. Add a standard date range filter and [map it](/visualize-present/dashboards/filters#map-different-fields) to the `Dynamic Date Granularity` field to control the window of time.

    <Frame>
      <img alt="Everything Toggle" />
    </Frame>
  </Step>
</Steps>

## Next steps

* Learn more about [filter-only fields](/modeling/templated-filters/parameters) to create more interactive toggles.
* Learn how to [map dashboard filters to different tile fields](/visualize-present/dashboards/filters) to ensure your filters apply correctly across tiles.


# Customizing filter suggestions
Source: https://docs.omni.co/guides/modeling/filter-suggestions

Learn where filter suggestion values come from, and how to change their source, faceting, and caching behavior.

<GuideSidebar />

<GuideTitle title="Customizing filter suggestions" />

When you filter on a field in Omni, you get a list of suggested values to pick from. That list isn't a static lookup — it's a query Omni runs against your warehouse, which is why suggestions can load slowly, include values that don't fit the rest of your query, or go stale.

This guide covers where those values come from and the model parameters that change that behavior: where suggestions are sourced from, whether they narrow in response to other filters, and how long they're cached.

## How suggestions are sourced

By default, Omni populates up to 2,000 suggestions (not configurable) by querying the field's distinct values in the context of the topic the field belongs to:

```sql theme={null}
  SELECT field_filter_is_based_on
    FROM table
GROUP BY 1
   LIMIT 2000
```

Depending on the specifics of the model — for example, if the field is in a view other than the topic's base view — you may also see the relevant `JOIN` or `WHERE` clauses in the suggestion query.

## Changing the suggestion source

Three dimension parameters override the default query. Setting any of them means suggestions no longer come from the field's own distinct values.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
      <th>Available on measures?</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`suggest_from_field`](/modeling/dimensions/parameters/suggest-from-field)</td>
      <td>Pulls suggestions from a different field, usually one that queries faster</td>
      <td><CheckIcon /> [Yes](/modeling/measures/parameters/suggest-from-field)</td>
    </tr>

    <tr>
      <td>[`suggest_from_topic`](/modeling/dimensions/parameters/suggest-from-topic)</td>
      <td>Routes the suggestion query to a different topic</td>
      <td><XCircleIcon /> No</td>
    </tr>

    <tr>
      <td>[`suggestion_list`](/modeling/dimensions/parameters/suggestion-list)</td>
      <td>Sets the list of options explicitly, bypassing the query. Also allows you to set a display label separate from the underlying value, which is helpful when the stored value isn't intuitive.</td>
      <td><CheckIcon /> [Yes](/modeling/measures/parameters/suggestion-list)</td>
    </tr>
  </tbody>
</table>

<Note>
  `suggest_from_field` and `suggest_from_topic` can't be used with [`faceting`](/modeling/dimensions/parameters/faceting) on the same dimension.
</Note>

## How other filters affect suggestions

When faceting is enabled, selecting values in one filter narrows the suggestions shown in other filters to values that exist alongside your current selections.

### Customizing per-dimension suggestion behavior

The [`faceting`](/modeling/dimensions/parameters/faceting) parameter lets you customize how suggestions behave on a per-dimension basis.

<Tabs>
  <Tab title="Independent of selections">
    To make suggestions independent of all other filter selections, add `depends_on: []` as a child to `faceting`. In this example, `gender` suggestions will be available regardless of other filter selections:

    ```yaml wrap highlight={4,5} Suggestions are independent of other filter selections theme={null}
    dimensions:
      gender:
        sql: ${users.gender}
        faceting:
          depends_on: []
    ```

    **Note**: `depends_on` cannot be used with `exclude`.
  </Tab>

  <Tab title="Depend on specified fields">
    To make a dimension's suggestions dependent only on specific fields, specify a field list in `depends_on`. In this example, `city` suggestions should only be filtered by `country` and `state` selections, ignoring all other active filters:

    ```yaml wrap highlight={4-7} Suggestions are filtered only by specified fields theme={null}
    dimensions:
      city:
        sql: ${users.city}
        faceting:
          depends_on:
            - country
            - state

      country:
        sql: ${users.country}

      state:
        sql: ${users.state}
    ```

    **Note**: `depends_on` cannot be used with `exclude`.
  </Tab>

  <Tab title="Exclude specified fields">
    You can also configure a list of fields that will not affect suggestions using `exclude`. In this example, `first_name` suggestions should be filtered by all fields except `state`:

    ```yaml wrap highlight={4-6} Suggestions are filtered by all fields except those excluded theme={null}
    dimensions:
      first_name:
        sql: ${users.first_name}
        faceting:
          exclude:
            - state
    ```

    **Note**: `exclude` cannot be used with `depends_on`.
  </Tab>
</Tabs>

### Enabling faceting across the workbook

[`facet_workbook_filters`](/modeling/models/facet-workbook-filters) is disabled by default. Set it to `true` to turn faceting on for every filter in the workbook. When enabled, all filter suggestions in the workbook will be faceted based on the current filter selection.

<Warning>
  Enabling this setting can make suggestion queries more complex and less cacheable, so they may run slower or return nothing where suggestions were expected.
</Warning>

## Caching and refreshing

Filter suggestions are retained for 30 days, independent of the model's [cache policy](/modeling/models/cache-policies). To make them obey the policy's `max_cache_age` instead, set [`filter_suggestions_must_obey_policy`](/modeling/models/cache-policies#param-filter-suggestions-must-obey-policy) to `true` on the cache policy:

```yaml wrap Obey cache policy & retain for 24 hours theme={null}
cache_policies:
  cache_for_a_day:
    max_cache_age: 24 hours
    filter_suggestions_must_obey_policy: true
```

<Warning>
  Once `filter_suggestions_must_obey_policy` is set, it can't be removed, though its value can be changed.
</Warning>

### Refreshing stale filter suggestions

In rare circumstances, suggestions may be cached in a stale state. To enable the refresh option for a specific query:

* **Mac** - Hold `Command + Shift`
* **Windows** - Hold `Control + Shift`

A <RefreshIcon /> icon will appear. Click it to refresh the filter suggestions.

This will refresh suggestions for the current query. If other queries have stale suggestions, you will need to repeat these steps on that query's filter.

<Frame>
  <img alt="The filter suggestion menu with the refresh option enabled" />
</Frame>

## Next steps

* Adding and configuring [filters](/analyze-explore/queries/filters) on workbook queries
* [Troubleshooting filters](https://community.omni.co/t/why-doesnt-my-filter-show-all-possible-values-as-suggestions/54) not showing all expected values


# Join to the same table twice
Source: https://docs.omni.co/guides/modeling/join-to-same-table

Use aliases to build tables named with language already familiar to your users.

<GuideSidebar />

<GuideTitle title="Join to the same table twice" />

When modeling topics, simplicity in naming conventions is key. Aliasing table joins allows you to build out tables based on logical concepts, using language your users will recognize.

## The scenario: Buyers and sellers

In this example, we'll focus on **buyers** and **sellers**.

Our model has an `orders` table containing fields like `seller_id` and `buyer_id` and a `users` table where individual users are identified by a unique `id`:

```mermaid theme={null}
erDiagram
    orders {
        int buyer_id
        int seller_id
    }
    users {
        int id
    }
```

To segment the `users` table into buyers and sellers, we need to join either the `buyer_id` or `seller_id` field with the `id` field in the `users` table. Essentially, our goal is to join the same tables **twice** but in **different ways** each time:

```mermaid theme={null}
erDiagram
    order_items {
        int buyer_id FK
        int seller_id FK
    }
    buyers["users (as buyers)"] {
        int id PK
    }
    sellers["users (as sellers)"] {
        int id PK
    }
    order_items }o--|| buyers : "buyer_id = id"
    order_items }o--|| sellers : "seller_id = id"
```

This is where aliasing becomes necessary. If we attempt to make both joins without aliasing, Omni will surface the following validation error in the model IDE:

```markdown wrap theme={null}
Relationship duplication: there are multiple relationships between "order_items" and "users". This may lead to surprising results. Use a different alias for one of the relationships.
```

## Implementing aliases in the relationships file

In the model's [relationships file](/modeling/relationships), we'll define two joins: one for buyers and the other for sellers.

There are three parts to defining aliased joins:

* The [`join_to_view_as` parameter](/modeling/relationships/parameters/join-to-view-as), which creates the alias for referencing the join in the modeling layer.
* The [`join_to_view_as_label` parameter](/modeling/relationships/parameters/join-to-view-as-label), which creates the label for the view in the workbook layer.
* The [`on_sql` parameter](/modeling/relationships/parameters/on-sql), which creates the join condition. **Use the alias when defining the condition** or you'll encounter errors. For example, the `buyers` alias is used as the prefix in `${order_items.buyer_id} = ${buyers.id}`.

```yaml title="buyers join" highlight={3,4,6} theme={null}
- join_from_view: order_items
  join_to_view: users
  join_to_view_as: buyers
  join_to_view_as_label: Buyers
  join_type: always_left
  on_sql: ${order_items.buyer_id} = ${buyers.id}
  relationship_type: assumed_many_to_one
```

```yaml title="sellers join" highlight={3,4,6} theme={null}
- join_from_view: order_items
  join_to_view: users
  join_to_view_as: sellers
  join_to_view_as_label: Sellers
  join_type: always_left
  on_sql: ${order_items.seller_id} = ${sellers.id}
  relationship_type: assumed_many_to_one
```


# Local development with the model editor CLI
Source: https://docs.omni.co/guides/modeling/local-development

Edit Omni model YAML files locally in your preferred editor with real-time sync back to Omni.

<GuideSidebar />

<GuideTitle title="Local development with the model editor CLI" />

The [`@omni-co/model-local-editor`](https://www.npmjs.com/package/@omni-co/model-local-editor) CLI tool lets you edit Omni model YAML files in your local environment with real-time synchronization back to Omni. Changes you save locally are automatically pushed to your Omni branch and validated against the model, giving you full IDE support for syntax highlighting, autocomplete, and version control.

<Note>
  The Omni model editor CLI is currently in beta and under active development.
</Note>

## How it works

When you start the sync, your model's YAML files are fetched from Omni and written to your local directory. From there, the CLI watches for file changes — any time you save, the updated file is pushed to your Omni branch and validated. When you're ready, merging the branch promotes your changes to the shared model and syncs to git.

```mermaid theme={null}
sequenceDiagram
    participant IDE as Local IDE
    participant CLI as omni-sync CLI
    participant Branch as Omni branch
    participant Shared as Shared model

    CLI->>Branch: omni-sync start
    Branch-->>CLI: Return all model YAML files
    CLI-->>IDE: Write to local directory

    loop While syncing
        IDE->>CLI: Save file
        CLI->>Branch: Push change
        Branch-->>CLI: Validate & return formatted YAML
        CLI-->>IDE: Write server-formatted file
    end

    CLI->>Branch: omni-sync merge-branch
    Branch->>Shared: Merge branch + sync to git
```

## Prerequisites

Before starting local development:

* **Node.js** version 16.0.0 or higher
* **Git integration is not required**, but if you're using it, the following settings are recommended:
  * [**Pull request required**](/integrations/git/settings#pull-request-required) – Require all changes to be made through a pull request, preventing direct promotion of branch changes to the shared model.
  * [**Always create branches**](/integrations/git/settings#always-create-branches) – When enabled, pull requests created outside Omni will automatically create a corresponding Omni branch.

## Set up the CLI

Start by creating a new empty directory and opening it in your IDE. This is where the CLI will sync your model YAML files to — you don't need to add any files yourself.

### 1. Install the package

Install the `@omni-co/model-local-editor` package globally:

```bash theme={null}
npm install -g @omni-co/model-local-editor
```

### 2. Set up environment variables

The CLI requires an [API key](/api/authentication) and your Omni instance URL. Set them as environment variables:

```bash theme={null}
export OMNI_API_KEY="your-api-key"
export OMNI_BASE_URL="https://your-org.omniapp.co"
```

For persistence, add these to your `~/.bashrc`, `~/.zshrc`, or equivalent.

You'll also need your **model ID**. Navigate to your model in Omni and copy the UUID from the URL.

### 3. Create a branch and initialize the sync

If you don't already have a branch, you can create one and initialize in a single step:

```bash theme={null}
omni-sync init your_model_id --branch your-branch --create-branch
```

If you already have a branch you want to use, pass it directly:

```bash theme={null}
omni-sync init your_model_id --branch your-branch
```

### 4. Start syncing

```bash theme={null}
omni-sync start your_model_id
```

Once started, any changes you save are pushed to your Omni branch and run through the model validator. Errors and warnings surface in the terminal in real time.

### 5. Merge your changes

When you're ready to promote your changes to the shared model, use the `merge-branch` command. This merges the branch into the shared model and syncs the changes to git.

```bash theme={null}
omni-sync merge-branch your_model_id your-branch
```

By default, the CLI will prompt you to confirm whether to delete the branch after merging. You can skip the prompt with one of the following flags:

* `--delete-branch` – Delete the branch after a successful merge
* `--no-delete-branch` – Keep the branch after merging

You can also pass a custom commit message for the git sync:

```bash theme={null}
omni-sync merge-branch your_model_id your-branch --delete-branch --commit-message "Your commit message"
```

<Note>
  If your model has **Pull request required** enabled in git settings, the CLI will not sync the merge to git. You can use `--force-override-git-settings` to allow the merge, but note that git will not be synced when this flag is used. To keep git in sync, merge via a pull request in your git provider instead.
</Note>

## AI tools for local development

You can extend your local development workflow with Omni's AI integrations:

* [**Agent skills**](/developers/agent-skills) – Omni's Cursor and Claude Code plugins bring analytics capabilities directly into your editor. Use them to explore models, run queries, and manage content without switching contexts.
* [**MCP Server**](/ai/mcp) – Query your Omni data using natural language from AI tools like Cursor and Claude. Useful for validating changes by querying the model as you develop.

## Troubleshooting

### Missing schemas or tables

If schemas or tables you can see in the Omni IDE aren't appearing in your local files, they may need to be activated. Make a small change to any file in that schema (such as updating a field description) and save it. This activates the schema and it will be included in subsequent syncs.

## Additional resources

* [Git integration](/integrations/git) – Connect a git repository for version control and pull request workflows
* [Branch Mode](/content/develop/branch-mode) – Use branches to develop and test model changes before sharing them
* [AI optimization](/modeling/develop/ai-optimization) – Curate your models for better results with Omni's AI features


# Organize fields with nested groups
Source: https://docs.omni.co/guides/modeling/nested-field-groups

Keep workbook field browsers navigable by grouping related fields.

<GuideSidebar />

<GuideTitle title="Organize fields with nested groups" />

Grouping related fields together ensures that the field browser in workbooks is tidy and easily navigable.

## Limitations

**[Dimensions](/modeling/dimensions) and [measures](/modeling/measures) can't be grouped together.** Applying the same group label to a dimension and a measure will result in two groups displaying in the field browser, not one group with both fields.

## Group creation

Group structures are created by using the greater-than symbol (`>`) in a dimension or measure `group_label` parameter, which must have whitespace on either side. Each segment will become a collapsible group level in the field browser.

For example, to create the following structure in the field browser:

```markdown title="Field browser structure for Location group" theme={null}
▾ Location
  ▾ Address
      street_address
      city
  ▾ Coordinates
      latitude
      longitude
```

You would add the following `group_label` parameters to the `street_address`, `city`, `latitude`, and `longitude` dimensions:

```yaml title="Create a Location group with Address & Coordinates subgroups" theme={null}
dimensions:
  street_address:
    group_label: Location > Address

  city:
    group_label: Location > Address

  latitude:
    group_label: Location > Coordinates

  longitude:
    group_label: Location > Coordinates
```

This example used dimensions, but you can also create group structures for measure fields the same way. Nested groups are especially helpful for measures that answer the same question in slightly different ways, as it lets you start broad and drill into more specific definitions only when needed.

<Note>
  Aggregation types have been omitted in the following example to keep the focus on group creation.
</Note>

```yaml title="Grouping measures in a support_tickets view" theme={null}
measures:
  first_response_breach_by_day:
    group_label: SLA breaches > First response

  first_response_breach_by_month:
    group_label: SLA breaches > First response

  breach_resolution_by_day:
    group_label: SLA breaches > Resolution

  breach_resolution_by_month:
    group_label: SLA breaches > Resolution
```

Which will create the following structure in the field browser:

```markdown title="Field browser structure for SLA breaches group" theme={null}
▾ SLA breaches
  ▾ First response
      first_response_breach_by_day
      first_response_breach_by_month
  ▾ Resolution
      breach_resolution_by_day
      breach_resolution_by_month
```

## Nesting depth

Groups can be nested:

<Tabs>
  <Tab title="YAML">
    ```yaml theme={null}
    dimensions:
      detailed_address:
        group_label: Geography > Location > Address > Details
    ```
  </Tab>

  <Tab title="File browser result">
    ```markdown theme={null}
    ▾ Geography
      ▾ Location
        ▾ Address
          ▾ Details
            detailed_address
    ```
  </Tab>
</Tabs>

## Field browser collapse and expand behavior

Field groups will behave as follows:

* **Click a group header** to expand or collapse its contents
* **Nested groups** only appear when their parent group is expanded
* **Fields** only appear when all ancestor groups are expanded
* When you **select or filter** a field, its parent groups show an indicator so you can see which groups contain active selections even when collapsed


# Preview dbt changes in Omni before merging to production
Source: https://docs.omni.co/guides/modeling/preview-dbt-changes

Preview dbt model changes, including net-new tables and views, in an Omni development environment before merging to production.

<GuideSidebar />

<GuideTitle title="Preview dbt changes in Omni before merging to production" />

This guide explains how to preview dbt model changes, including net-new tables and views, within an Omni development environment. By decoupling the Omni git branch from the dbt branch selector, you can safely validate data and assess downstream impacts before merging changes to your production branch.

## Requirements

To follow the steps in this guide, you'll need:

* A [dbt integration](/integrations/dbt/index) configured on your connection
* A dbt dev environment configured in Omni's dbt settings
* An Omni model branch created for development

## How it works

Omni's model IDE maintains two independent branch controls to help you manage your development workflow:

1. **Omni git branch**: The branch of your Omni model, including field definitions and joins.
2. **dbt branch selector**: Tells Omni which dbt branch's manifest to read from when syncing metadata and resolving schemas.

These are decoupled by design. Switching your Omni git branch doesn't automatically update the dbt branch Omni reads from; you must set both explicitly.

## Steps

<Steps>
  <Step title="Run your dbt model in dev">
    Execute the model in your dbt development environment and confirm it completes successfully before proceeding.
  </Step>

  <Step title="Commit your dbt changes">
    **Commit** to your dbt branch before continuing, as uncommitted changes are not visible to Omni.
  </Step>

  <Step title="Create or switch to an Omni branch">
    In the model IDE, navigate to **Model > Branch > New branch**. You can also switch to an existing branch.
  </Step>

  <Step title="Activate the dbt dev environment">
    In the Omni model IDE, open the **dbt settings panel** and **Select** your dbt development environment (e.g., `dev`).
  </Step>

  <Step title="Set the dbt branch">
    In the same dbt settings panel, enter the name of your dbt branch. This tells Omni to read the manifest from your feature branch rather than `main`. This step is required for net-new models to appear.

    <Frame>
      <img alt="Screenshot 2026 04 28 At 15 36 35" />
    </Frame>
  </Step>

  <Step title="Refresh the schema">
    In the model IDE, navigate to **Model > Refresh Schema**. Omni will pull the updated manifest and table structures from your dev environment.

    <Tip>
      Omni reads the dbt manifest at the time of schema refresh. If your dbt run hasn't finished when you trigger the refresh, new models may not appear. Wait for the dbt run to complete before refreshing.
    </Tip>
  </Step>

  <Step title="Validate your changes">
    New tables and updated fields should now be visible in the model IDE. Use the [Content Validator](/modeling/develop/content-validator) to check for downstream impacts on existing [dashboards](/visualize-present/dashboards/index).
  </Step>

  <Step title="Merge when ready">
    Once validated, merge your dbt pull request to `main`. Then, merge your [Omni branch](/content/develop/branch-mode) to promote model changes to production.
  </Step>
</Steps>

<Note>
  **New tables vs. field changes**: Field changes to existing models may appear after a schema refresh without setting the dbt branch. However, net-new tables and views require the dbt branch to be explicitly set in step 5.
</Note>

## Next steps

Now that you've validated your dbt changes, you can continue refining your data model:

* **Audit downstream content**: Use the [Content Validator](/modeling/develop/content-validator) to ensure your changes didn't break existing documents.
* **Merge to production**: Once your dbt PR is merged to `main`, update your Omni branch settings to point back to the production dbt branch and merge your Omni changes.

If you run into issues with models not appearing, double-check that your **dbt branch selector** matches your active dbt feature branch exactly.


# Push Omni topics to Databricks as metric views
Source: https://docs.omni.co/guides/modeling/push-to-databricks-metric-views

Use the Omni Python SDK to generate Databricks metric view DDL from an Omni topic.

<GuideSidebar />

<GuideTitle title="Push Omni topics to Databricks as metric views" />

If you've built a [topic](/modeling/topics) in Omni that you want to formalize as a governed metric view in Databricks Unity Catalog, you can use the [Omni Python SDK](https://github.com/exploreomni/omni-python-sdk) to generate the required DDL.

The SDK fetches your topic definition from the Omni API, converts its dimensions and measures into Databricks' YAML-based metric view format, and outputs a `CREATE VIEW ... WITH METRICS` statement that you can run directly in Databricks.

## How it works

The script calls the Omni API endpoint [Retrieve a topic API](/api/topics/retrieve-a-topic) to retrieve the full topic definition, including its views, dimensions, measures, and relationships. It then:

1. Identifies the base view (fact table) and its fully qualified table name as the metric view source.
2. Maps each dimension and measure to the Databricks metric view YAML format, transforming Omni's `${field_name}` SQL references into Databricks-compatible syntax.
3. Wraps the YAML in a `CREATE OR REPLACE VIEW ... WITH METRICS LANGUAGE YAML` DDL statement.

## Requirements

* Python 3.9 or later. Additionally, this guide uses pip to install Python dependencies, but you can use a different package manager.
* A Databricks connection
* An [Omni API key](/api/authentication)
* Permissions in Omni that allow you to access the model you want to export
* The model ID and topic name for the topic you want to export

## Steps

<Steps>
  <Step title="Install the Omni Python SDK">
    1. In the terminal, clone the SDK repository and install its dependencies:

       ```bash theme={null}
       git clone https://github.com/exploreomni/omni-python-sdk.git
       cd omni-python-sdk
       pip install .
       ```

    2. Next, create a `.env` file in the SDK directory with your Omni [API key](/api/authentication) and [base URL](/api/base-url):

       ```bash theme={null}
       OMNI_API_KEY=your_api_key
       OMNI_BASE_URL=https://your-org.omni.co
       ```
  </Step>

  <Step title="Find your model ID and topic name">
    You'll need two values from Omni:

    * **Model ID**: Open the model IDE and copy the model ID from the URL. The model ID is the UUID in the URL after `/models`. In the following URL, for example, the model IDE is `abcd1234-5678-90ab-cdef-1234567890ab`:

      ```text theme={null}
      https://your-org.omni.co/ide/models/abcd1234-5678-90ab-cdef-1234567890ab`
      ```

    * **Topic name**: The name of the topic as it appears in the model, such as `order_items`.
  </Step>

  <Step title="Run the script">
    The SDK includes a script that fetches the topic definition and generates Databricks DDL. The script takes the following arguments:

    * `model_id` - **Required**. The ID of the Omni model.
    * `topic_id` - **Required**. The name of the topic you want to export.
    * `default_catalog` - **Optional**. The name of the Databricks catalog where you want to create the metric view.
    * `default_schema` - **Optional**. The name of the Databricks schema where you want to create the metric view.

    ```bash theme={null}
    python -m examples.databricks_metric_view <model_id> <topic_name> <default_catalog> <default_schema>
    ```

    Run the script from the SDK directory, for example:

    ```bash theme={null}
    python -m examples.databricks_metric_view abcd1234-5678-90ab-cdef-1234567890ab order_items my_catalog my_schema
    ```

    The script outputs a `CREATE OR REPLACE VIEW` statement with the topic's dimensions, measures, and source table formatted as a Databricks metric view.
  </Step>

  <Step title="Execute the DDL in Databricks">
    Copy the generated DDL and run it in your Databricks SQL console. This creates a new metric view in your Unity Catalog with the naming convention `OMNI__<topic_name>`. For example:

    ```sql title="Example generated DDL for Omni topic" theme={null}
    CREATE OR REPLACE VIEW `OMNI__order_items`
    WITH METRICS
    LANGUAGE YAML
    COMMENT 'Generated from Omni topic: order_items'
    AS $$
    version: '1.1'
    source: omni_demo.ecomm.ecomm__order_items
    dimensions:
    - name: Date
      expr: created_at

    measures:
    - name: Order_Transactions_Count
      expr: count(*)
    - name: ecomm__users_Users_Count
      expr: count(*)
    joins:
    - name: ecomm__users
      source: omni_demo.ecomm.ecomm__users
      on: source.user_id = ecomm__users.id

    $$
    ```

    Once created, the metric view is available in Databricks like any other Unity Catalog asset. If you have the [Unity Catalog integration enabled](/connect-data/databricks-unity-catalog-integration), the metric view will also sync back into Omni on the next schema refresh.
  </Step>
</Steps>


# Safely rename a git-connected shared model
Source: https://docs.omni.co/guides/modeling/rename-git-connected-shared-model

Rename a git-connected shared model's display name without breaking its git sync folder or losing synced files.

<GuideSidebar />

<GuideTitle title="Safely rename a git-connected shared model" />

This guide explains how to rename a git-connected shared model's display name without disrupting its git sync folder or losing previously synced files. Renaming a model's display name is safe for saved dashboards and workbooks, but it can silently break git sync if the model's **Model path** setting was never set explicitly.

## Requirements

To follow the steps in this guide, you'll need:

* A shared model with [git integration](/integrations/git/index) enabled
* Admin access to the model's [Git settings](/integrations/git/settings)

## How model path resolution works

Every git-connected model has a **Model path** setting (**Model > Git settings**) that determines the folder in your repository where Omni reads and writes the model's files. This setting has two distinct states:

* **Explicit Model path set**: the sync folder is pinned to that value. Renaming the model's display name has no effect on the sync folder.
* **Model path unset (the default state)**: Omni doesn't use a fixed folder. Instead, it derives the sync folder from the model's *current display name* at sync time (default pattern: `omni/<current-display-name>`). This is re-evaluated live, not a value captured once when the model was created.

<Warning>
  If Model path is unset and you rename the model's display name, the next git sync looks for (and writes to) a *new* folder derived from the new name, while your previously synced files remain in the *old* folder derived from the old name. Omni sees an empty or missing folder at the new path, and the model can appear to lose all of its content.
</Warning>

## What is and isn't affected by renaming

* The model's ID never changes on rename. Saved dashboards and workbooks reference the model by ID, and fields are referenced by view name, not display name, so neither depends on the display name.
* Once Model path is pinned, renaming the display name doesn't break existing saved content.
* Field IDs and view names are unaffected by a model display-name rename.

## Steps

<Steps>
  <Step title="Check whether Model path is already set">
    In the model IDE, go to **Model > Git settings** and check the **Model path** field. If it already contains an explicit path, you can rename the model's display name directly and skip the remaining steps.
  </Step>

  <Step title="Set an explicit Model path">
    If Model path is empty, set it to the model's current folder in your repository, using a leading slash (e.g. `/omni/<current-model-name>`).
  </Step>

  <Step title="Confirm the setting saved">
    Reload the Git settings panel and verify the Model path value persisted and matches your repository's actual folder structure.
  </Step>

  <Step title="Rename the model's display name">
    Use the model rename UI, or the [Rename Model API](/api/models/rename-model), to update the display name.
  </Step>

  <Step title="Verify the git sync">
    Trigger a sync and confirm the model's files still resolve from the pinned folder, with no unexpected file additions or deletions.
  </Step>
</Steps>

<Tip>
  Test this full sequence on a non-production, git-connected model before applying it to a production model with meaningful content.
</Tip>

## Related constraints when renaming a git-connected model

* The new name must be unique among active models with the same model kind and base model.
* The name must match the git-compatible pattern (word characters, hyphens, and forward slashes only).
* The new name can't conflict with an existing git ref path (for example, renaming to `team` when `team/project` already exists).
* You can't rename a branch model that has an open pull request — doing so would desync Omni from the git remote.

## Next steps

* Review [Git integration troubleshooting](/integrations/git/troubleshooting) if files appear missing after a rename.
* See [Model management](/modeling/develop/model-management) for broader model lifecycle guidance.


# Apply a filter to a single measure
Source: https://docs.omni.co/guides/modeling/single-field-filter

Add a filter to just one measure in a given query.

<GuideSidebar />

<GuideTitle title="Apply a filter to a single measure" />

Filtered measures allow you to apply a filter to a single measure in a given query. For example, filtered measures are equivalent to a SQL statement like:

```sql theme={null}
COUNT(DISTINCT
    CASE
      WHEN status = 'Complete' THEN order_id
      ELSE NULL
    END)
```

However, filtered measures have the added benefit of intelligent passing through the filter value when you drill.

## Option 1: Use the Create filtered measure workbook option

1. In a workbook query tab, create a query with a measure you want to filter.
2. Add a pivot on the dimension that contains the value you want to filter.
3. In the results table, right click on the measure you want to filter.
4. Select **Create filtered measure**.

<img alt="" />

## Option 2: Create a duplicate measure or a quick aggregate

1. In a workbook query tab, create a query with a measure you want to filter.
2. Create a new measure. You can do this by either right clicking on the field and selecting **Aggregates** or by duplicating an existing measure.
3. In the field browser, right click on the measure you just created and select **Modeling > Edit**.
4. In the **Edit field** panel, click **Add filter** to apply a filter to the measure.

<img alt="" />

## Option 3: Use the model IDE

You can also create filtered measures in the model IDE using [filter syntax](/modeling/measures/parameters/filters):

```yaml theme={null}
order_items_count_status_complete:
  aggregate_type: count
  filters:
    status:
      is: Complete

margin_sum:
  sql: ${order_items.margin}
  label: Completed Order Margin Sum
  aggregate_type: sum
  filters:
    status:
      is: Complete
```


# Using Level of Detail functions for cohorting analysis
Source: https://docs.omni.co/guides/patterns/build-cohort-analysis-using-level-of-detail

Utilize Level of Detail fields to create a cohort analysis for determining how different cohorts of user perform over time.

<GuideSidebar />

<GuideTitle title="Using Level of Detail functions for cohorting analysis" />

You can use [Level of Detail](https://omni.co/demos/20250523#level-of-detail-fields) (LoD) calculations to perform cohort analysis without creating query views or complex joins. This guide shows you how to identify a user's first order date to track behavior and retention over time.

## Requirements

To follow the steps in this guide, you'll need:

* Access to a **dataset** with an `Order Date` and `User ID`.
* Restricted Querier or above connection permissions to build in the workbook.

<Steps>
  <Step title="Create the LoD field">
    First, define the aggregation that identifies the first order for each user.

    1. In the field browser in a workbook, find the `Order Date` field.
    2. Hover over the field and click the <Icon icon="ellipsis-vertical" /> that displays, then **Modeling > New Level of Detail field**:

       <img alt="New level of Detail Field" />
  </Step>

  <Step title="Configure the calculation">
    Set the scope of the calculation to ensure the date is fixed to the user regardless of other filters in your query.

    1. In the editing pane, select **Fixed LoD Grouping**.
    2. Under **Fixed Dimension(s)**, select `User ID` to isolate each individual user's activity. This sets the aggregation to find the minimum (first) `Order Date` for each `User ID`.

       <img alt="Level of Detail field configuration pane showing Fixed LoD Grouping, User ID grouping, and minimum Order Date aggregation" />
  </Step>

  <Step title="Visualize the cohort">
    Once the field is defined, you can build your cohort grid to analyze user patterns.

    1. Using the field browser, select the new LoD field to serve as your cohort date.
    2. Select the original `Order Date` and `Order Count`.
    3. [Pivot](/visualize-present/visualizations/types/table#working-with-pivots) the LoD field by clicking the <Icon icon="ellipsis-vertical" /> icon next to the Level of Detail field header in the workbook, then select **Pivot**. This will allow you to see how these cohorts have purchased products over time.

       <img alt="Level of Detail Cohort Visualization" />
  </Step>
</Steps>

## Video walkthrough

<iframe title="Building Cohort Analysis with Level of Detail field" />

## Next steps

Now that you have built your cohort using LoD, you can further refine your analysis:

* [Learn more about table visualizations](/visualize-present/visualizations/types/table) to further customize your view.
* [Explore advanced querying](/analyze-explore/querying) to add filters or custom calculations to your cohort.
* Review [Cohort analysis using a thin spine](/guides/patterns/spine-cohort-analysis) for an alternative approach.


# Using AI to build a cohort analysis with month offset
Source: https://docs.omni.co/guides/patterns/cohort-analysis-month-offset-ai

Use the Omni Agent to create a cohort analysis that tracks user behavior over time using monthly offsets.

<GuideSidebar />

<GuideTitle title="Using AI to build a cohort analysis with month offset" />

## Requirements

To follow the steps in this guide, you'll need:

* **Permissions in Omni** that allow you to use the [Omni Agent](/ai/queries).
* **A dataset that includes at least two date fields** — a fixed user attribute date (e.g., account creation date) and an activity or event date. These should be accessible from a single Omni topic.

<Steps>
  <Step title="Define cohort and activity dates">
    To start, you need to establish the fixed date for your users and the activity date you are measuring.

    1. Select the user creation date (for example, `Created At`). This serves as your fixed dimension for the X-axis.
    2. Select the date field representing user activity or transactions:

       <img alt="Cohort Date" />
  </Step>

  <Step title="Calculate the month offset with AI">
    Instead of writing complex SQL, use the Omni Agent to calculate the time difference between your two dates.

    1. Click **AI calcs** (<Icon icon="sparkles" /> icon) in the workbook toolbar.
    2. In the Omni Agent prompt, enter: `"Calculate the difference in months between column a and b."`

       <img alt="Create AI Field" />
    3. After the calculation generates, hover over the column and click the <Icon icon="ellipsis-vertical" /> icon.
    4. Click **Save to workbook** to make the field available for your analysis.

       <img alt="Promote to Workbook" />
    5. Rename the new field to something clear, such as `Months since Created`, by clicking the <Icon icon="ellipsis-vertical" /> icon next to the field name in the field picker and opening the Edit Field view.

    <Tip>
      This can also be done via double clicking on the header of the new column.
    </Tip>

    <img alt="Rename Field" />
  </Step>

  <Step title="Structure the cohort view">
    Once your offset is calculated, you can arrange your data to see the "cohort triangle" pattern.

    1. Create a pivot on the new `Months since Created` field.

       <img alt="Pivot" />
    2. Select a measure to track, such as a **Count** of users or **Count Distinct** of specific behaviors.
    3. The results will automatically format into a cohort-style visualization:

       <img alt="Results" />
  </Step>

  <Step title="Add conditional formatting">
    Enhance your table to visually highlight performance trends across different cohorts.

    1. Navigate to the **Visualizations** tab and click the **Table** visualization.
    2. Click the **Conditional Formatting** tab in the **Chart Options** panel.
    3. Choose **Color Scale**.
    4. Select your primary measure to apply the color scale:

       <img alt="Visualization" />

    <Tip>
      Use a sequential color scale (e.g., light to dark blue) to make it easier to see where retention or activity drops off in later months.
    </Tip>
  </Step>
</Steps>

## Video walkthrough

<iframe title="Building a Cohort Analysis with Month Offset using AI" />

## Next steps

Now that you've built your AI-driven cohort, you can:

* Explore more advanced [AI formulas](/analyze-explore/calculations#ai-generated) to calculate retention percentages.
* Learn more about [Table visualization options](/visualize-present/visualizations/types/table#conditional-formatting-options) to further customize your reports.


# Building a dynamic pivot query view
Source: https://docs.omni.co/guides/patterns/dynamic-pivot-query-view

Build a query view that cross-joins sparse key-value data so every entity has a row for every attribute, then exposes it as a pivotable query view.

<GuideSidebar />

<GuideTitle title="Building a dynamic pivot query view" />

This guide walks through building a query view in Omni that takes sparse key-value data and fills in the gaps so the result can be cleanly pivoted in a workbook.

It covers setting up the SQL using a cross join, wiring up a scoped templated filter, and defining the YAML dimensions and measures that make pivoting work.

This is especially relevant if:

* Your source table has rows shaped like `entity_id | attribute_name | attribute_value`, and not every entity has a row for every attribute name
* You want to pivot attribute names into columns in an Omni workbook without missing rows collapsing silently
* You need a dynamic filter that scopes the query to a subset of data (for example, by a parent ID) and populates its dropdown from the database

## Understanding the pattern

If your data looks like this:

| entity\_id | attribute\_name | attribute\_value |
| ---------- | --------------- | ---------------- |
| abc        | Evidence A      | Pass             |
| abc        | Evidence C      | Fail             |
| xyz        | Evidence B      | Pass             |

A direct pivot would silently drop the missing combinations. The cross-join pattern fills them in first, so the result looks like this before pivoting:

| entity\_id | Evidence A | Evidence B | Evidence C |
| ---------- | ---------- | ---------- | ---------- |
| abc        | Pass       | NULL       | Fail       |
| xyz        | NULL       | Pass       | NULL       |

The query view does this by cross-joining all distinct entity IDs against all distinct attribute names, then left-joining back to the source table to pick up values where they exist.

<Note>
  The [`fill_fields`](/modeling/query-views/parameters/fill-fields) query view parameter solves a related but different problem. It fills missing values from an enumerated or date series. The cross-join approach here is for cases where both the entities and attributes are dynamic and sourced from the data itself.
</Note>

## Requirements

To follow the steps in this guide, you'll need:

* **Modeler** or **Connection Admin** permissions on the model
* The fully qualified path to your table (`DATABASE.SCHEMA.TABLE_NAME`)
* A table with sparse key-value rows

  <Note>
    This guide uses Snowflake to walk through examples. If using a different database, you may need to adjust the SQL to your database's syntax.
  </Note>

## Building the query view

<Steps>
  <Step title="Confirm the table path">
    Before you start working in Omni, confirm the fully qualified path to your table in Snowflake. If you're unsure, run the following in Snowflake:

    ```sql wrap theme={null}
    SHOW TABLES LIKE '%YOUR_TABLE_NAME%' IN ACCOUNT;
    ```

    Then confirm the exact database and schema:

    ```sql wrap theme={null}
    SELECT table_catalog, table_schema, table_name
    FROM information_schema.tables
    WHERE table_name = 'YOUR_TABLE_NAME';
    ```

    Your full table path will be: `DATABASE.SCHEMA.TABLE_NAME`
  </Step>

  <Step title="Create the query view file">
    Query views can be created two ways in Omni: through the model IDE (recommended), or from a workbook.

    <Tabs>
      <Tab title="In the IDE (recommended)" icon="code">
        1. Open the Omni model IDE.
        2. Create a file named `your_query_view.query.view` (the `.query.view` extension is required).
        3. Paste the YAML from the [next section](#add-yaml) into the file.
        4. Click **Save**.
      </Tab>

      <Tab title="In the workbook" icon="book">
        1. Build an initial query in a workbook.
        2. Click **Model > Save query as view**.
        3. Enter the name for your view (for example, `your_query_view`).
        4. Click **Create query view**. A new View tab will open.
        5. Replace the auto-generated YAML with the template from the next step, then click **Save changes to view**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the YAML template">
    Paste the following template into your query view file. Every value in `ALL_CAPS` is a placeholder you'll replace with a real value in the next step — except `CREATED_AT`, which is an optional column you can rename or remove (see the inline comment in the template).

    <Note>
      The placeholder table in the next step covers all substitutions. For example, if your scoping column is `ACCOUNT_ID`, replace every instance of `SCOPE_COLUMN` with `ACCOUNT_ID` and rename `scope_id_dim` to `account_id_dim` everywhere it appears — including in `suggest_from_field`.
    </Note>

    ```yaml title="your_query_view.query.view" expandable wrap theme={null}
    # Replace "your_query_view" everywhere — including inside the templated filter references in the SQL.
    # Example: if your file is my_pivot_view.query.view, use my_pivot_view here and in the SQL.
    sql: |-
      WITH all_attribute_names AS (
        SELECT DISTINCT "ATTRIBUTE_NAME_COLUMN"
        FROM DATABASE.SCHEMA.YOUR_TABLE
        WHERE {{# your_query_view.scope_filter.filter }} "SCOPE_COLUMN" {{/ your_query_view.scope_filter.filter }}
      ),
      all_entity_ids AS (
        SELECT DISTINCT "ENTITY_ID_COLUMN"
        FROM DATABASE.SCHEMA.YOUR_TABLE
        WHERE {{# your_query_view.scope_filter.filter }} "SCOPE_COLUMN" {{/ your_query_view.scope_filter.filter }}
      ),
      all_combinations AS (
        SELECT
          c."ENTITY_ID_COLUMN",
          a."ATTRIBUTE_NAME_COLUMN"
        FROM all_entity_ids c
        CROSS JOIN all_attribute_names a
      ),
      filled AS (
        SELECT
          ac."ENTITY_ID_COLUMN",
          ac."ATTRIBUTE_NAME_COLUMN",
          t."ATTRIBUTE_VALUE_COLUMN",
          t."CREATED_AT",
          -- Selects the scope column from the source row. NULL for cross-join rows with no matching source data.
          t."SCOPE_COLUMN" AS "SCOPE_COLUMN"
        FROM all_combinations ac
        LEFT JOIN DATABASE.SCHEMA.YOUR_TABLE t
          ON t."ENTITY_ID_COLUMN" = ac."ENTITY_ID_COLUMN"
          AND t."ATTRIBUTE_NAME_COLUMN" = ac."ATTRIBUTE_NAME_COLUMN"
          AND {{# your_query_view.scope_filter.filter }} t."SCOPE_COLUMN" {{/ your_query_view.scope_filter.filter }}
      )
      SELECT * FROM filled
      ORDER BY "ENTITY_ID_COLUMN", "ATTRIBUTE_NAME_COLUMN"

    dimensions:
      entity_id:
        sql: '"ENTITY_ID_COLUMN"'
        label: "Entity ID"

      # Right-click this field in the Omni workbook and select "Pivot"
      attribute_name:
        sql: '"ATTRIBUTE_NAME_COLUMN"'
        label: "Attribute Name"

      # The _dim suffix avoids a naming collision with the measure defined below
      attribute_value_dim:
        sql: '"ATTRIBUTE_VALUE_COLUMN"'
        label: "Attribute Value"

      # The _dim suffix avoids a naming collision with the scope_filter defined below.
      # This dimension exists so scope_filter can use suggest_from_field to populate
      # its dropdown dynamically. If you rename this, update suggest_from_field below to match.
      scope_id_dim:
        sql: '"SCOPE_COLUMN"'
        label: "Scope ID"

      # Remove this block (and t."CREATED_AT" from the SQL above) if you don't need a date filter.
      created_at:
        sql: '"CREATED_AT"'
        label: "Created At"

    measures:
      count:
        aggregate_type: count

      attribute_value:
        sql: ${attribute_value_dim}
        aggregate_type: max
        label: "Attribute Value (Aggregated)"

    filters:
      scope_filter:
        type: string
        default_filter:
          is: your-default-value-here
        suggest_from_field: your_query_view.scope_id_dim
    ```

    <Note>
      Setting a default filter value is important. Without one, the cross-join CTEs will scan the entire source table on first load.
    </Note>
  </Step>

  <Step title="Replace placeholders in YAML">
    Replace each placeholder in the YAML using the table below:

    | Placeholder                                              | Replace with                                                                             | Example                                |
    | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------- |
    | `your_query_view`                                        | The name of the query view file (without `.query.view`)                                  | `my_pivot_view`                        |
    | `DATABASE.SCHEMA.YOUR_TABLE`                             | The fully qualified Snowflake table path                                                 | `ANALYTICS.PROD.FACT_EVENTS`           |
    | `ENTITY_ID_COLUMN`                                       | The column that identifies each unique entity (the rows in your pivot)                   | `PRODUCT_ID`                           |
    | `ATTRIBUTE_NAME_COLUMN`                                  | The column whose distinct values become the pivot column headers                         | `METRIC_NAME`                          |
    | `ATTRIBUTE_VALUE_COLUMN`                                 | The column containing the values to show in each pivot cell                              | `METRIC_VALUE`                         |
    | `SCOPE_COLUMN`                                           | The column used to filter the data down to a relevant subset                             | `ACCOUNT_ID`                           |
    | `CREATED_AT`                                             | **Optional**. The timestamp column to expose as a date dimension - remove if not needed. | `EVENT_CREATED_AT`                     |
    | `scope_id_dim`                                           | Rename to match your scope column, keeping the `_dim` suffix                             | `account_id_dim`                       |
    | `your_query_view.scope_id_dim` (in `suggest_from_field`) | Update to match your renamed `scope_id_dim` value                                        | `my_pivot_view.account_id_dim`         |
    | `your-default-value-here`                                | The default value to pre-populate the scope filter                                       | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

    Once all placeholders are replaced, your query view is ready to test.
  </Step>

  <Step title="Enable pivoting in the workbook">
    Omni requires at least one measure on a query to enable pivoting, which is why this view defines `attribute_value` as a `max` measure.

    <Note>
      This pattern assumes at most one value per entity + attribute (+ scope) combination. If your source has multiple rows for the same combination, the `max` measure returns only the highest value lexically and drops the others. De-duplicate upstream or change the aggregation if that isn't what you want.
    </Note>

    Once the query view is saved and the model is valid:

    1. Open a workbook and select your query view as the data source.
    2. Add **Entity ID** as a dimension.
    3. Add **Attribute Value (Aggregated)** as a measure.
    4. Right-click **Attribute Name** in the field browser and select **Pivot**.

    Each unique attribute name will become its own column, with `NULL` shown where no value existed.

    To change the scope (for example, to view a different parent ID), apply the **Scope Filter** filter-only field that appears in the field browser under this view's filters.
  </Step>

  <Step title="Promote to the shared model">
    Once you've confirmed the query view works as expected in the workbook, promote it to make it available across all workbooks.

    In a published workbook, click **Model > View & promote changes**, review the changes, and click **Promote to shared**.
  </Step>
</Steps>

## Next steps

* [Query view parameters](/modeling/query-views/parameters) — Full reference for query view syntax and options
* [Templated filters](/modeling/templated-filters) — How filter templating works in Omni SQL
* [Promoting model changes](/modeling/develop/promotion) — How to move changes from a draft to the shared model


# Choosing between LOD fields, window functions, CTEs, and Excel
Source: https://docs.omni.co/guides/patterns/level-of-detail-build-comparison

Compare Omni LOD fields, SQL window functions, CTEs, and Excel for multi-level aggregation and cohort analysis.

<GuideSidebar />

<GuideTitle title="Choosing between LOD fields, window functions, CTEs, and Excel" />

Some aggregations don't fit a simple `GROUP BY`. For example, you may want to show each customer's lifetime spend on a row-level breakout by product category, or compute each region's percentage of a grand total. Omni gives you four ways to handle these: an LOD field, a SQL window function, a CTE or derived table, or a spreadsheet.

In this guide, you'll learn about each of these methods, how they compare to each other, and when to choose each one.

## Before you start

If you're new to LOD fields, read [Level of detail fields](/analyze-explore/custom-fields/level-of-detail) first — this guide assumes basic familiarity with the field type.

## Available methods

The right choice usually comes down to whether the calculation needs to be reusable, where you're comfortable writing logic, and how much data is involved. Use the table below as a starting point; the [side-by-side comparison](#comparing-methods) goes deeper on the trade-offs.

| Method               | Use this when...                                                                                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Omni LOD field       | The same calculation will appear in multiple workbooks, when it needs to respond to filters dynamically, or when you'd rather not write SQL. Cohorts, lifetime customer metrics, and percent-of-total calculations are good fits for this approach. |
| SQL window function  | The calculation only matters inside one query and you're comfortable in SQL. Use for one-off analyses that don't need to be reusable.                                                                                                               |
| CTE or derived table | You're working with a large dataset and benefit from materializing the intermediate result in your warehouse, or when the calculation involves multi-step transformations that don't fit cleanly into a single query.                               |
| Excel                | Only when the data already lives in a spreadsheet or for a quick ad-hoc check. Excel isn't scalable and the logic isn't reusable outside the file.                                                                                                  |

## Comparing methods

This table compares the four methods across the traits that usually drive the choice. Use it when you want to compare a specific dimension across all four options.

| Trait              | Omni LOD field                                                                       | SQL window function                                                                              | CTE / derived table                                          | Excel                                                         |
| :----------------- | :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :------------------------------------------------------------ |
| **Primary use**    | Aggregating at a specific level without changing query granularity.                  | Aggregating relative to the current row in a single query pass.                                  | Creating temporary tables to join back to main data.         | Aggregating across a range or within a pivot table.           |
| **Where it lives** | UI or semantic layer; reusable across [workbooks](/analyze-explore/workbook-basics). | Inside a single SQL query.                                                                       | In SQL; can be promoted to a [shared model view](/modeling). | A specific spreadsheet file.                                  |
| **Flexibility**    | Dynamic; responds to other filters while maintaining its fixed level.                | Fixed to the query's current result-set granularity.                                             | Static; requires rewriting SQL to change the grouped level.  | Manual; requires updating ranges or refreshing pivot sources. |
| **Ease of use**    | UI-driven; no code required.                                                         | Requires knowledge of window function parameters such as `OVER`, `PARTITION BY`, and `ORDER BY`. | Requires SQL and manual join logic.                          | Familiar for one-off math; hard to scale.                     |
| **Performance**    | Optimized by Omni as part of query generation.                                       | Database-dependent.                                                                              | Best for massive datasets when pre-materialized.             | Limited by local CPU and memory.                              |
| **Reusability**    | Define once, use everywhere.                                                         | Trapped inside a single query.                                                                   | Reusable if built into a shared model view.                  | Trapped inside a specific file.                               |

<Tip>
  For the best performance on massive datasets, consider using a [derived table](/modeling/query-views/index) which can be materialized in your warehouse.
</Tip>

## Common scenarios

The three scenarios below cover the patterns that come up most often: bucketing customers by lifetime spend, building acquisition cohorts, and computing percent of total. Each is solved with all four methods side by side, so you can take a pattern you already know in one tool and find its equivalent in another.

### Customer lifetime spend

In this scenario, you want "total spend per customer" as a dimension you can use to bucket customers (`$0–100`, `$100–500`, and so on), even when viewing orders by product category.

<Tabs>
  <Tab title="Omni LOD">
    The fields in the workbook's LOD editor would look like the following:

    * **Field to aggregate** - `Sale price`
    * **Aggregation** - `Sum`
    * **Level of Detail Grouping** - `Fixed`
    * **Fixed dimension(s)** - `User ID`
  </Tab>

  <Tab title="SQL window function">
    ```sql theme={null}
    SUM(sale_price) OVER (PARTITION BY user_id)
    ```
  </Tab>

  <Tab title="CTE">
    ```sql theme={null}
    WITH user_spend AS (
      SELECT user_id,
             SUM(sale_price) AS total
      FROM orders
      GROUP BY 1
    )
    SELECT o.*, us.total
    FROM orders o
    JOIN user_spend us ON o.user_id = us.user_id
    ```
  </Tab>

  <Tab title="Excel">
    In Excel, you'd have a formula where `A` is `User ID` and `C` is `Sale Price`:

    ```text theme={null}
    =SUMIFS(C:C, A:A, A2)
    ```
  </Tab>
</Tabs>

### First-touch cohort date

In this scenario, you want each user's first order date so you can analyze performance by acquisition cohort.

<Tabs>
  <Tab title="Omni LOD">
    The fields in the workbook's LOD editor would look like the following:

    * **Field to aggregate** - `Order date`
    * **Aggregation** - `Min`
    * **Level of Detail Grouping** - `Fixed`
    * **Fixed dimension(s)** - `User ID`

    For a full walkthrough using this approach, see [Build cohort analysis using level of detail](/guides/patterns/build-cohort-analysis-using-level-of-detail).
  </Tab>

  <Tab title="SQL window function">
    ```sql theme={null}
    FIRST_VALUE(order_date) OVER (PARTITION BY user_id ORDER BY order_date ASC)
    ```
  </Tab>

  <Tab title="CTE">
    ```sql theme={null}
    WITH first_purchase AS (
      SELECT user_id,
             MIN(order_date) AS first_order_date
      FROM orders
      GROUP BY 1
    )
    SELECT o.*, fp.first_order_date
    FROM orders o
    JOIN first_purchase fp ON o.user_id = fp.user_id
    ```
  </Tab>

  <Tab title="Excel">
    In Excel, you'd have an array formula finding the minimum date (`B`) per user (`A`). In Excel versions without dynamic arrays, enter with `Ctrl+Shift+Enter`.

    ```text theme={null}
    {=MIN(IF(A:A=A2, B:B))}
    ```
  </Tab>
</Tabs>

### Percent of total

In this scenario, you're viewing sales by region and want to know what percentage of the company's total sales each region represents.

<Tabs>
  <Tab title="Omni LOD">
    The fields in the workbook's LOD editor would look like the following:

    * **Field to aggregate** - `Sales`
    * **Aggregation** - `Sum`
    * **Level of Detail Grouping** - `Exclude`
    * **Fixed dimension(s)** - `Region`

    This returns the grand total on every row, so you can divide each row's sales by it to get percent of total.
  </Tab>

  <Tab title="SQL window function">
    ```sql theme={null}
    SUM(sales) OVER ()
    ```
  </Tab>

  <Tab title="CTE">
    ```sql theme={null}
    SELECT region, 
           sales, 
           (
            SELECT SUM(sales)
              FROM orders
           ) AS grand_total
      FROM orders
    ```
  </Tab>

  <Tab title="Excel">
    In Excel, build it as a pivot:

    1. Add `Sales` to **Values** twice.
    2. Set the second to **Show Values As > % of Column Total**.
  </Tab>
</Tabs>

## Next steps

* Create your first LOD field in a [workbook](/analyze-explore/custom-fields/level-of-detail)
* Build a [cohort analysis](/guides/patterns/build-cohort-analysis-using-level-of-detail) using an LOD field
* Promote logic to a [derived table or query view](/modeling/query-views/index)
* Read Omni's [blog post on level of detail fields](https://omni.co/blog/level-of-detail-fields)


# Report opening and closing balances from a ledger
Source: https://docs.omni.co/guides/patterns/opening-closing-balances

Turn a transactional ledger into opening, closing, and movement balances that stay correct across any dimension, using a daily snapshot and omni_dimensionalize.

<GuideSidebar />

<GuideTitle title="Report opening and closing balances from a ledger" />

Most finance reporting comes down to three numbers: the balance at the start of a period, the movements during it, and the balance at the end. A general ledger, a bank account, a loan book, or a work-in-progress (WIP) balance all follow this shape.

This is simple when your warehouse already stores daily balance snapshots. It gets harder when your source is a raw ledger of individual transactions, with no pre-computed balance anywhere. You cannot just sum the amounts, because a balance is not additive across time.

This guide shows a complete pattern for solving this in Omni. You start with raw transactions and finish with self-service opening and closing balances that stay correct no matter which dimensions a user picks, or in what order.

## Where this comes up

The trigger is always the same. Your data records individual movements, but the question people ask is about a position at a point in time.

You will hit this pattern whenever someone asks for a "balance," a "position," or "where we stood" as of a date, and the underlying table only holds transactions:

* Finance closes the month and needs opening and closing cash per entity, with the movements reconciling between them.
* A controller wants WIP or accrued revenue at the start and end of a period, sliced by client, service line, or owner.
* A lending team reports loan book balance by product and vintage, built from drawdowns, repayments, and write-offs.
* An ops lead wants stock on hand by warehouse, built from purchase orders, sales, and adjustments.
* A RevOps team reports ARR or MRR at period start and end, built from subscription change events.

In every case the source is a movement log, and the requirement is a cumulative position that has to roll up cleanly across any combination of dimensions.

### The same pattern across domains

| Domain                         | Balance metric          | Transaction source                      | Entity key                |
| ------------------------------ | ----------------------- | --------------------------------------- | ------------------------- |
| Finance and treasury           | Cash or account balance | Payments, receipts, transfers           | `account_id`              |
| Professional services          | Work-in-progress (WIP)  | Time entries, disbursements, invoicing  | `engagement_id`           |
| Manufacturing and construction | Work-in-progress (WIP)  | Material, labour, and overhead postings | `job_id`                  |
| SaaS and subscriptions         | ARR or MRR              | New, renewal, churn, expansion events   | `subscription_id`         |
| Lending and credit             | Loan book balance       | Drawdowns, repayments, write-offs       | `loan_id`                 |
| Inventory and supply chain     | Stock on hand           | Purchase orders, sales, adjustments     | `sku_id` + `warehouse_id` |
| Insurance                      | Claims reserves         | New claims, payments, re-estimates      | `claim_id`                |
| HR and workforce               | Active headcount        | Hires, terminations, transfers          | `employee_id`             |

The entity key is the thing that accumulates a balance. Every other column is just an attribute of it.

<Note>
  **Work-in-progress shows up in two different industries, and both fit this pattern.** In professional services such as accounting, legal, and consulting, WIP is unbilled time and disbursements: work that has been delivered but not yet invoiced. In manufacturing and construction, WIP is the cost of partially finished goods or a job mid-build, the materials, labour, and overhead accrued before completion. The inputs differ, but the accounting is the same. Each is a running balance built from a transaction log, so both report opening and closing WIP using the steps below.
</Note>

## The problem: semi-additive measures

Most measures are fully additive. You can sum them across any dimension and get a correct result. Revenue, deposits, hours worked, and order count are all additive.

Balances are different. They are semi-additive. You can sum them across dimensions like account, region, or customer, but you cannot sum them across time. A balance of \$10,000 on Monday and \$10,500 on Tuesday is not \$20,500. The balance grew by \$500.

To report a balance you have to do two things in order:

1. Pick a single point in time, the first or last date in the period.
2. Then sum across the other dimensions.

This is exactly what [`omni_dimensionalize`](/modeling/measures#semi-additive-measures-with-omni_dimensionalize) is built for.

## Requirements

To follow this guide you will need:

* A transactional source table with a transaction date, an entity key, the descriptive dimensions you want to slice by, and a signed amount per movement.
* A transformation layer (dbt, scheduled SQL, or similar) to build the snapshot table in Step 1.
* Connection permissions to edit the shared model, or a development branch to work in.

## The three-step pattern

<Steps>
  <Step title="Build a daily snapshot table">
    Your transformation layer computes a daily snapshot with a running balance per entity. The key design decision is the partition key.

    **Partition by the entity key, not by the descriptive dimensions.** The `account_id` (or `loan_id`, `wip_id`, and so on) is the thing that accumulates balance. Customer, region, and account type are attributes of that entity. Partitioning by the entity key is simpler, faster, and correct. If an attribute changes, for example an account moves to a new region, the running balance still tracks against the entity.

    **Materialize this in the transformation layer, do not compute it live.** Build the snapshot once as a table in dbt or a scheduled job and let Omni query the result. A window function that scans the full ledger is expensive to re-run on every query, and materializing it keeps the running balance deterministic and fast. Refresh it on the same cadence as your reporting, which is daily for most balance use cases.

    **Snapshot at the lowest grain that accumulates a balance, which may be finer than the account.** Here, one row per `account_id` per day is enough. In other domains the entity sits below the account: inventory is per `sku_id` + `warehouse_id`, WIP is per `job_id` or `engagement_id`, and a multi-currency account is per `account_id` + `currency`. Build the snapshot at that grain. Omni rolls it up to whatever a user groups by, but it can never recover detail the snapshot has already aggregated away.

    Take a ledger of account transactions:

    | date       | account\_id | region | account\_type | customer   | amount   |
    | ---------- | ----------- | ------ | ------------- | ---------- | -------- |
    | 2025-01-01 | ACC-1001    | APAC   | Savings       | Acme Corp  | \$5,000  |
    | 2025-01-01 | ACC-1002    | EMEA   | Current       | Globex Inc | \$12,000 |
    | 2025-01-01 | ACC-1003    | APAC   | Current       | Acme Corp  | \$8,000  |
    | 2025-01-15 | ACC-1001    | APAC   | Savings       | Acme Corp  | \$2,500  |
    | 2025-01-15 | ACC-1002    | EMEA   | Current       | Globex Inc | -\$3,000 |
    | 2025-02-01 | ACC-1001    | APAC   | Savings       | Acme Corp  | \$1,000  |
    | 2025-02-01 | ACC-1003    | APAC   | Current       | Acme Corp  | -\$2,000 |
    | 2025-02-15 | ACC-1002    | EMEA   | Current       | Globex Inc | \$7,500  |
    | 2025-03-01 | ACC-1001    | APAC   | Savings       | Acme Corp  | -\$500   |
    | 2025-03-01 | ACC-1003    | APAC   | Current       | Acme Corp  | \$4,000  |

    A window function turns it into a daily snapshot with a running balance per `account_id`:

    ```sql theme={null}
    -- account_daily_snapshot: materialize in your transformation layer
    -- (e.g. a dbt model, or a scheduled table in Snowflake or Databricks)
    with daily_movements as (
        select
            transaction_date as snapshot_date,
            account_id,
            region,
            account_type,
            customer,
            sum(amount) as daily_movement
        from stg_account_transactions
        group by all
    )

    select
        *,
        sum(daily_movement) over (
            partition by account_id
            order by snapshot_date
            rows between unbounded preceding and current row
        ) as running_balance
    from daily_movements
    ```

    The result accumulates per entity across time:

    | snapshot\_date | account\_id | region | account\_type | customer   | daily\_movement | running\_balance |
    | -------------- | ----------- | ------ | ------------- | ---------- | --------------- | ---------------- |
    | 2025-01-01     | ACC-1001    | APAC   | Savings       | Acme Corp  | \$5,000         | \$5,000          |
    | 2025-01-01     | ACC-1002    | EMEA   | Current       | Globex Inc | \$12,000        | \$12,000         |
    | 2025-01-01     | ACC-1003    | APAC   | Current       | Acme Corp  | \$8,000         | \$8,000          |
    | 2025-01-15     | ACC-1001    | APAC   | Savings       | Acme Corp  | \$2,500         | \$7,500          |
    | 2025-01-15     | ACC-1002    | EMEA   | Current       | Globex Inc | -\$3,000        | \$9,000          |
    | 2025-02-01     | ACC-1001    | APAC   | Savings       | Acme Corp  | \$1,000         | \$8,500          |
    | 2025-02-01     | ACC-1003    | APAC   | Current       | Acme Corp  | -\$2,000        | \$6,000          |
    | 2025-02-15     | ACC-1002    | EMEA   | Current       | Globex Inc | \$7,500         | \$16,500         |
    | 2025-03-01     | ACC-1001    | APAC   | Savings       | Acme Corp  | -\$500          | \$8,000          |
    | 2025-03-01     | ACC-1003    | APAC   | Current       | Acme Corp  | \$4,000         | \$10,000         |

    ACC-1001 starts at \$5,000, gains \$2,500 on Jan 15 to reach \$7,500, gains \$1,000 on Feb 1 to reach \$8,500, and loses \$500 on Mar 1 to reach \$8,000.
  </Step>

  <Step title="Model the balances with omni_dimensionalize">
    This is where Omni does the work. [`omni_dimensionalize`](/modeling/measures#semi-additive-measures-with-omni_dimensionalize) converts a measure into a dimension within the current query's grouping context. Use it to find the first and last date in any filtered period, per group, then filter the running balance to only those dates.

    ```yaml theme={null}
    dimensions:
      # First and last date WITHIN each GROUP BY combination
      first_date_in_period:
        hidden: true
        sql: omni_dimensionalize(min(${snapshot_date}))

      last_date_in_period:
        hidden: true
        sql: omni_dimensionalize(max(${snapshot_date}))

      is_opening_date:
        hidden: true
        sql: ${snapshot_date[date]} = ${first_date_in_period[date]}

      is_closing_date:
        hidden: true
        sql: ${snapshot_date[date]} = ${last_date_in_period[date]}

    measures:
      # Semi-additive: sum the running balance, but only on the opening date
      opening_balance:
        label: Opening Balance
        sql: ${running_balance}
        aggregate_type: sum
        format: currency_2
        filters:
          is_opening_date:
            is: true

      # Semi-additive: sum the running balance, but only on the closing date
      closing_balance:
        label: Closing Balance
        sql: ${running_balance}
        aggregate_type: sum
        format: currency_2
        filters:
          is_closing_date:
            is: true

      # Additive: movements can be summed freely across time
      period_movement:
        label: Period Movement
        sql: ${daily_movement}
        aggregate_type: sum
        format: currency_2
    ```

    Here is what happens when a user runs a query:

    1. They pick dimensions, for example Region and Account Type, and filter to a date range such as Q1 2025.
    2. `omni_dimensionalize(min(${snapshot_date}))` finds the earliest date within each group in the result set.
    3. `is_opening_date` is true only for rows on that group's first date.
    4. The `opening_balance` measure sums `running_balance` only where `is_opening_date` is true.
    5. Because the snapshot is at the entity grain, Omni's `sum()` rolls up correctly across entities inside each group.

    The hierarchy a user selects is just a `GROUP BY` ordering. As long as the snapshot sits at the lowest grain, one row per entity per day, Omni handles any roll-up automatically.

    The opening and closing measures are [filtered measures](/analyze-explore/custom-fields/filtered-measures). The movement measures need no special handling.
  </Step>

  <Step title="Separate additive from semi-additive measures">
    This is the distinction to make clear to your users.

    | Measure         | Type          | Sum across time? | Sum across dimensions? | Omni approach                               |
    | --------------- | ------------- | ---------------- | ---------------------- | ------------------------------------------- |
    | Daily movement  | Additive      | Yes              | Yes                    | Standard `aggregate_type: sum`              |
    | Deposits        | Additive      | Yes              | Yes                    | Standard `aggregate_type: sum`              |
    | Withdrawals     | Additive      | Yes              | Yes                    | Standard `aggregate_type: sum`              |
    | Opening balance | Semi-additive | No               | Yes                    | Filtered measure with `omni_dimensionalize` |
    | Closing balance | Semi-additive | No               | Yes                    | Filtered measure with `omni_dimensionalize` |

    Derived metrics build on both types. Net change is `closing_balance - opening_balance`. Growth percent is `(closing_balance - opening_balance) / opening_balance`. Define these as standard measures that reference the others.
  </Step>
</Steps>

## Why dimension order does not matter

A common worry is whether the numbers change when a user reorders dimensions. They do not. Here is the proof using the account data above, filtered to Jan 1 to Mar 1 2025.

**Hierarchy A: Region, then Customer, then Account Type**

| Region | Customer   | Account Type | Opening  | Closing  | Movement |
| ------ | ---------- | ------------ | -------- | -------- | -------- |
| APAC   | Acme Corp  | Savings      | \$5,000  | \$8,000  | \$3,000  |
| APAC   | Acme Corp  | Current      | \$8,000  | \$10,000 | \$2,000  |
| EMEA   | Globex Inc | Current      | \$12,000 | \$16,500 | \$4,500  |

**Hierarchy B: Customer, then Account Type, then Region**

| Customer   | Account Type | Region | Opening  | Closing  | Movement |
| ---------- | ------------ | ------ | -------- | -------- | -------- |
| Acme Corp  | Current      | APAC   | \$8,000  | \$10,000 | \$2,000  |
| Acme Corp  | Savings      | APAC   | \$5,000  | \$8,000  | \$3,000  |
| Globex Inc | Current      | EMEA   | \$12,000 | \$16,500 | \$4,500  |

Same numbers, different visual nesting. The `GROUP BY` contains the same columns, so Omni generates identical SQL.

**Rolled up to Region only**

| Region          | Opening      | Closing      | Movement    |
| --------------- | ------------ | ------------ | ----------- |
| APAC            | \$13,000     | \$18,000     | \$5,000     |
| EMEA            | \$12,000     | \$16,500     | \$4,500     |
| **Grand total** | **\$25,000** | **\$34,500** | **\$9,500** |

At the Region level, `omni_dimensionalize` finds the min and max date across all accounts in each region. APAC opening is ACC-1001 (\$5,000) plus ACC-1003 (\$8,000) on Jan 1, which is \$13,000. APAC closing is ACC-1001 (\$8,000) plus ACC-1003 (\$10,000) on Mar 1, which is \$18,000.

The balances aggregate correctly at every level, because the snapshot is at the entity grain and `omni_dimensionalize` adapts to whatever the current `GROUP BY` is.

## Variations and advanced patterns

### Reconciliation: closing equals next period's opening

If users need to confirm that the closing balance for one period equals the opening balance for the next, build a reconciliation view that materializes both values side by side, per period and per dimension combination.

### All-time balance alongside a filtered period

To show an all-time balance next to the filtered period's opening and closing, use [`cancel_query_filters`](/modeling/filters/operators/cancel-query-filter) on a [level of detail](/modeling/dimensions/parameters/level-of-detail) field:

```yaml theme={null}
dimensions:
  all_time_balance:
    sql: ${running_balance}
    group_by:
      aggregate_type: sum
      fixed: [ account_id ]
      cancel_query_filters: true
```

### When you already have snapshot data

If your warehouse already stores daily balance snapshots, skip Step 1 and go straight to the `omni_dimensionalize` pattern in Step 2.

## Next steps

* Validate the model against a known reconciliation period before you publish it.
* Build a workbook with field selectors so users can switch dimensions on the fly.
* Read more on [semi-additive measures and `omni_dimensionalize`](/modeling/measures#semi-additive-measures-with-omni_dimensionalize).
* Review [filtered measures](/analyze-explore/custom-fields/filtered-measures) and [level of detail fields](/modeling/dimensions/parameters/level-of-detail) for the supporting concepts.


# Optimizing AI context for fintech and banking
Source: https://docs.omni.co/guides/patterns/optimizing-ai-context-for-fintech

A hands-on guide to configuring AI context at the model, topic, and view levels using a fintech example.

<GuideSidebar />

<GuideTitle title="Optimizing AI context for fintech and banking" />

In fintech, the difference between a deposit and revenue is fundamental, yet often misinterpreted by LLMs without additional tuning. To provide accurate insights, your model needs to define the "Golden Rules" of your ledger, specifically how signs (positive vs. negative) and transaction statuses are interpreted.

By embedding your fintech-specific logic directly into the model, topic, and view layers, you ensure that Omni's AI operates as a specialized financial analyst. This structured approach reduces hallucinations in critical reporting like AUM, delinquency rates, and net worth calculations.

## Why AI context matters

Fintech data is notoriously nuanced. Without specific context, AI might:

* Treat a loan balance as a positive asset for a customer
* Double-count internal ACH transfers as revenue
* Misinterpret liability-centric ledger conventions

By providing explicit guardrails, you ensure Omni's AI operates as a specialized financial analyst that understands liability-centric ledgers and regulatory risk states.

## The AI context hierarchy

Omni allows you to layer context at different levels of your data model. For fintech, this hierarchy ensures that global rules (like currency) are respected while specific logic (like loan delinquency) is applied only where relevant.

| **Layer**      | **Purpose**                                                                                              | **Example**                                                                       |
| :------------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| **Model**      | **Universal truths.** Global business logic and formatting rules that apply to all queries in the model. | "Inflows are positive and outflows are negative; use USD for all reporting"       |
| **Topic**      | **The persona.** Definitions for specific datasets and how views relate to each other.                   | "AUM includes all positive balances; exclude internal transfers from net volume." |
| **View/Field** | **Field precision.** Specific definitions, synonyms, and allowed values for columns.                     | "This view tracks credit health; 'delinquent' and 'late' statuses are At-Risk."   |

## Requirements

To implement this example in your own Omni instance, you’ll need:

* Familiarity with Omni’s modeling layer
* Permissions in Omni that allow you to edit a shared model
* A connected data source that contains fintech or banking-related data

<Steps>
  <Step title="Setting universal rules in the model file">
    The [model file](/modeling/models) is where you establish your "Golden Rules." These rules apply across every query the AI generates, ensuring consistent handling of inflows, outflows, and reporting currencies.

    ```yaml wrap theme={null}
    # Model File
    ai_context: |
      ## Strategic Overview
      This model serves as the unified ledger and relationship management for a multi-entity financial platform. 
      It bridges Retail Banking (Individual), Commercial Banking (Business), and Lending operations.
      
      ## Financial Guardrails
      - **The Golden Rule of Signs**: In this model, 'Accounts' and 'Transactions' follow a liability-centric ledger. 
        - Credits (deposits/inflows) are POSITIVE. 
        - Debits (spend/outflows/payments) are NEGATIVE. 
        - Loan/Credit Card balances are represented as NEGATIVE (money owed to the institution).
      - **Transaction vs. Settlement**: All dates are 'Transaction Dates'. For 'Settlement' logic, assume a T+2 window unless analyzing 'Card Transactions' which are near-instant.
      - 'Transfer' categories and 'ACH' transactions between a user's own accounts must be excluded from 'Revenue' and 'Net Spend' to avoid double-counting.
      
      ## Entity Relationships
      - All analysis begins with the 'Customer'. A single customer_id may own multiple account_types (Checking, Mortgage, etc.). 
      - 'Product' labels (e.g., 'Mass Affluent' vs. 'Startup') dictate the fee structures and risk profiles. 
      
      ## Regulatory & Risk Context
      - **Delinquency State**: Any account joined to a 'Loan' with a status of 'delinquent' or 'late' should be flagged in 'At-Risk' reporting.
      - **Reporting Currency**: All values are denominated in USD. No FX conversion is required.
    ```
  </Step>

  <Step title="Setting dataset logic in the topic">
    Topics represent the "Customer 360" view. Use the topic-level [`ai_context`](/modeling/topics/parameters/ai-context) to define calculated metrics like `Assets Under Management (AUM)` or `Wallet Share` so the AI doesn't have to guess which accounts to include in a balance check.

    ```yaml expandable wrap theme={null}
    base_view: fintech_dataset_main__customers
    label: Customer & Banking activity

    description: |
      Customer 360 topic for consumer and business banking relationships.
      This topic combines customer profile, account balances, transaction behavior, and lending status so analysts can answer lifecycle questions like: acquisition, activity, wallet share, risk, and profitability.
      
      It is designed for both Retail (high-frequency card/ACH behavior) and
      Business banking (higher-value wire/ACH flows), with loan performance
      included for portfolio risk and delinquency monitoring.
      Typical use cases:
      - Active customer tracking and cohort/vintage analysis
      - AUM and balance composition by customer segment
      - Spend and flow analysis by channel/category
      - Delinquency and at-risk customer identification

    ai_context: |  
      ## Business Guardrails & Logic
      - **Revenue vs. Volume**: 'Revenue' refers to fees/interest earned by the bank. 'Transaction Volume' or 'GTV' refers to the total flow of money through the platform. Do not confuse the two.
      - **Asset vs. Liability**: For the bank, 'Checking/Savings' are liabilities (we owe the customer), and 'Loans/Mortgages' are assets. However, for 'Customer Net Worth' calculations, treat Checking/Savings as (+) and Loans/Credit Card balances as (-).
      - **Active Customers**: Define 'Active' as a customer with at least one transaction in the last 30 days, or a non-zero balance in a 'Checking' or 'Savings' account.
      
      ## Product Context
      - **Individual vs. Business**: Individual accounts are high-volume, lower-balance (Retail). Business accounts (Startups/Enterprise) have higher 'Wire' and 'ACH' volumes.
      - **Churn**: A customer is considered 'Churned' if all their accounts have a 'closed' status and zero balance.
      - **Risk**: Use 'delinquent' status in Loans to identify at-risk portfolios. 'Delinquency Rate' is (Count of Delinquent Loans / Total Active Loans).
     
    ```
  </Step>

  <Step title="Adding precision at the view level">
    [View-level](/modeling/views) context handles the specific quirks of your tables. For example, you can instruct the AI to ignore certain dimensions (like birth years) when analyzing business entities or define which specific statuses represent a "total loss" for the bank.

    ```yaml expandable wrap theme={null}
    catalog: fintech_dataset
    schema: main
    table_name: customers

    description: |
      Master customer entity table. Each row represents a KYC-verified
      individual or business relationship with the institution.
      
      Use this table as the starting point for customer lifecycle, segmentation,
      onboarding cohort, and relationship-level analytics.

    ai_context: |
      The 'Entity' or 'User' master table. This is the starting point for 
      all Relationship Management and Growth analytics.
      
      ## Business Logic
      - 'Individual' types are retail consumers; 'Business' types are commercial entities.
      - 'birth_year' is only valid for 'Individual' types; do not use for Business analysis.
      - 'created_at' represents the completion of KYC (Know Your Customer) and account opening.
      - Use 'created_at' to define 'Customer Vintages' (cohorts based on signup date).

    dimensions:
      customer_id:
        primary_key: true
        type: string
        sql: '"customer_id"'
        description: Unique identifier for the KYC-verified customer entity.
        ai_context: |
          "The unique identifier for the KYC-verified entity."

      type:
        type: string
        sql: '"type"'
        all_values: ['individual', 'business']
        description: Legal customer type indicating whether the account holder is an individual or a business.
        ai_context: |
          "Categorizes the legal nature of the account holder."

      name:
        type: string
        sql: '"name"'
        description: Full legal name of the customer (person or registered business entity).
        ai_context: |
          "The full legal name (Individual) or registered entity name (Business)."

      segment:
        type: string
        sql: '"segment"'
        all_values: ['mass', 'mass_affluent', 'affluent', 'high_net_worth', 'startup', 'small_business', 'mid_market', 'enterprise']
        synonyms: ['wealth bracket', 'tier', 'client profile']
        description: Customer tier used for relationship strategy, service model, and performance analysis (e.g., mass, affluent, startup, enterprise).
        ai_context: |
          Hierarchical value. 
          Individual: mass < mass_affluent < affluent < high_net_worth.
          Business: startup < small_business < mid_market < enterprise.

      state:
        type: string
        sql: '"state"'
        all_values: ['CA', 'TX', 'NY', 'FL', 'IL', 'PA', 'OH', 'GA', 'NC', 'WA']
        description: Two-letter U.S. state code representing the customer’s primary location for geographic analysis and risk concentration.
    	ai_context: |
          "Two-letter US State code for geographic concentration risk."

      created_at:
        type: date
        sql: '"created_at"'
        synonyms: ['onboarding_date', 'activation_date', 'signup_date']
        description: Date the customer relationship was activated (KYC/account onboarding completion).
        ai_context: |
          "The date the customer record was finalized in the system."

      birth_year:
        type: number
        sql: '"birth_year"'
        description: Birth year of the customer for individual records; typically null for business entities.
        ai_context: |
          "Birth year for Individuals; NULL for Business entities."
    ```

    ```yaml expandable wrap theme={null}
    catalog: fintech_dataset
    schema: main
    table_name: transactions

    description: |
      Banking transactions ledger. Each row is a posted money movement event
      for a customer account.
      
      A transaction is either:
      - **Deposit/Credit (positive amount)**: money entering the account
      - **Withdrawal/Debit (negative amount)**: money leaving the account
      This table is used for spend analysis, inflow/outflow trends, channel mix,
      merchant behavior, and customer activity scoring.

    ai_context: |
      The source of truth for transactional flow.
      - Negative amounts = outflows (spend/payments)
      - Positive amounts = inflows (deposits/refunds)
      - Category='Transfer' indicates internal movement; exclude from revenue
      - account_id links each transaction to a specific product/account

    dimensions:
      transaction_id:
    	primary_key: true
        type: string
        sql: '"transaction_id"'
        description: Unique transaction event identifier.
        ai_context: Stable primary key for each posted transaction row.
      
      customer_id:
       	type: string
        sql: '"customer_id"'
        description: Customer who initiated or received the transaction.
        ai_context: Foreign key to customer entity; use for customer-level aggregations.

      account_id:
    	type: string
        sql: '"account_id"'
        description: Account on which the transaction was recorded.
        ai_context: Foreign key to account/product; use for checking vs card vs loan analysis.

      amount_usd:
    	type: number
        sql: '"amount_usd"'
        synonyms: ['value', 'flow', 'transaction_size']
        description: Signed transaction amount in USD.
        ai_context: Positive = deposit/credit (inflow). Negative = withdrawal/debit (outflow).

      category:
    	type: string
        sql: '"category"'
        all_values: ['Groceries', 'Restaurants', 'Transfer', 'Travel', 'Entertainment', 'Utilities', 'Payroll', 'Rent', 'Insurance']
        description: Business classification of transaction purpose.
        ai_context: Use to segment spend/flow; treat 'Transfer' as internal movement.

      merchant:
    	type: string
        sql: '"merchant"'
        description: Counterparty or merchant name associated with the transaction.
        ai_context: Useful for concentration and behavioral analysis; fuzzy matching may be needed.

      channel:
    	type: string
        sql: '"channel"'
        all_values: ['ach', 'wire', 'card', 'mobile', 'web', 'branch']
        description: Payment rail or origination channel for the transaction.
        ai_context: ach/wire/card/mobile/web/branch indicate different customer behaviors.

      date:
    	type: date
        sql: '"date"'
        description: Posting/settlement date of the transaction.
        ai_context: Canonical date for trend and period-over-period analysis.

    ```
  </Step>
</Steps>

## Iterating on AI context

Improving AI quality is an iterative process. As you launch new financial products or change your lending criteria, update your context. Think of AI context as living documentation for your ledger: the more precise you are, the less time your team spends making corrections.

Iteration involves a feedback loop between user queries and model updates:

1. **Monitor**: Use the **AI usage** dashboard in the [**Analytics** section](/administration/analytics) to find queries with negative (👎) feedback.
2. **Identify**: Did the AI fail due to a cryptic name, a missing join, or a lack of business logic?
3. **Tune**: Update the YAML at the appropriate level (model, topic, view).
4. **Verify**: Re-run the prompt in the [**Query Helper**](/ai/queries) to ensure changes work as expected.
5. **Update for product launches**: When your platform introduces a new payment rail like FedNow or a new loan product, update the `all_values` and `ai_context` parameters to reflect the new taxonomy.

<Tip>
  When you correct the AI in a chat session (e.g., `"Actually, always use Fiscal Year"`), click the <Icon icon="brain" /> (brain) icon to have the AI [learn from the conversation](/ai/learn-from-conversation) and propose model changes to incorporate the correction.
</Tip>

## Next steps

* [**Model-level ai\_context**](/modeling/models/ai-context) — Reference for model-level `ai_context` syntax
* [**Topic-level ai\_context**](/modeling/topics/parameters/ai-context) — Reference for topic-level `ai_context` syntax
* [**View-level ai\_context**](/modeling/views/parameters/ai-context) — Reference for view-level `ai_context` syntax
* [**Optimize models for Omni AI**](/modeling/develop/ai-optimization) — Broader guidance on optimizing your model for AI


# Optimizing AI context for retail and ecommerce
Source: https://docs.omni.co/guides/patterns/optimizing-ai-context-for-retail-and-ecommerce

A hands-on guide to configuring AI context at the model, topic, and view levels using a retail and ecommerce example.

<GuideSidebar />

<GuideTitle title="Optimizing AI context for retail and ecommerce" />

This guide provides a hands-on reference for building out AI context within a real-world Omni instance.

By following this retail and orders example, you can see exactly how to move beyond basic schema discovery to a **high-precision setup** where the AI understands your specific business logic, key performance indicators, and reporting nuances.

## Why AI context matters

While Omni automatically understands your schema, `ai_context` allows you to codify company-specific knowledge that isn't captured in table names or column labels.

Think of this as training your AI analyst on your company's specific playbook. In a retail environment, this means:

* Defining which status codes (e.g., "Shipped," "Complete") represent valid revenue
* Specifying which unique identifier to use when counting orders
* Providing preferred dimensions for "top-n" queries

## The AI context hierarchy

To help the AI return accurate, business-aligned answers, you can add context to the underlying data model. For this example, think of the context in three layers: model, topic, and view.

Omni applies this logic from the top down - starting at the model level - allowing you to set universal rules that get more specific as you move toward individual fields.

| **Layer**      | **Purpose**                                                                                              | **Example**                                                                                     |
| :------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| **Model**      | **Universal truths.** Global business logic and formatting rules that apply to all queries in the model. | "Our fiscal year starts in Feb; use USD for all currency."                                      |
| **Topic**      | **The persona.** Definitions for specific datasets and how views relate to each other.                   | "You are a Retail Analyst; use the Order Items table for all sales queries."                    |
| **View/Field** | **Field precision.** Specific definitions, synonyms, and allowed values for columns.                     | "This ID is internal; don't show it unless asked. `'Bought at'` is a synonym for `created_at`." |

## Requirements

To implement this example in your own Omni instance, you'll need:

* Familiarity with Omni's modeling layer
* Permissions in Omni that allow you to edit a shared model
* A connected data source that contains retail-related data

<Steps>
  <Step title="Setting universal rules in the model file">
    The [model file](/modeling/models) defines your universal rules that will exist across the entire model. These rules act as permanent guardrails, ensuring the AI adheres to your core business standards regardless of which topic in the model a user is exploring.

    ```yaml title="Model-level context" wrap theme={null}
    ai_context: |-
      ## Global Business Logic
      - Our Fiscal Year starts in February. If a user asks for "this year" without specifying, assume Fiscal Year.
      - "Revenue" always refers to 'Gross Sales' (before discounts) unless 'Net' is specified.
      - When comparing time periods, always use 'Complete' weeks (Monday-Sunday) to avoid partial-week skew.

      ## Data Handling & Formatting
      - Never display internal database keys or UUIDs in the final result unless explicitly requested for troubleshooting.
      - For any currency output, default to USD.
      - If a query results in zero records, explain that the filters (like 'Status = Shipped') might be too restrictive.

      ## Retail Definitions
      - A "New Customer" is a user whose first_order_date is within the last 30 days.
      - "Active Inventory" refers only to items where 'Stock Count' > 0 and 'Discontinued' is false.
    ```
  </Step>

  <Step title="Setting dataset logic in the topic">
    [Topic-level](/modeling/topics) context defines more specific details scoped to your pre-defined datasets. This example shows how to tell the AI how to handle an ecommerce dataset specifically focused on orders and fulfillment.

    ```yaml title="Topic-level context" wrap theme={null}
    base_view: omni_dbt_ecomm__order_items
    label: Order Transactions
    group_label: Orders & Fulfillment

    # Limit the search space to relevant fields to reduce noise
    ai_fields: [ all_views.*, -tag:exclude_from_AI ]

    ai_context: |-
      You are an expert data analyst with vast experience analyzing ecommerce data to find trends.

      Our data includes order line items (order_items), users (users), inventory (inventory_items), and products (products).

      ## Key Business Logic:
      - Any queries regarding sales should always use the total_sale_price field on the order items table.
      - If asked about drivers of a metric change, start with: country, traffic_source, category, or brand.
      - If asked about "who" or "users", use full_name and email. Never return an ID unless explicitly asked.
      - For total orders or order count, use orders.order_id_count_distinct.
      - For revenue metrics, filter only on valid statuses: Complete, Shipped, Processing.

    sample_queries:
      Monthly Sales by Country:
        query:
          fields:
            [
              "omni_dbt_ecomm__order_items.created_at[month]",
              omni_dbt_ecomm__users.country,
              omni_dbt_ecomm__order_items.total_sale_price
            ]
          base_view: omni_dbt_ecomm__order_items
          filters:
            omni_dbt_ecomm__order_items.status:
              not: [ Returned, Cancelled ]
          pivots: [ omni_dbt_ecomm__users.country ]
        description: A monthly breakdown of all sales by user's country
        prompt: What do our sales look like by country?
    ```

    <Tip>
      **Use sample queries:** Adding `sample_queries` creates a "happy path" for the AI. It ensures high-value KPIs use your exact join logic and filter sets, mirroring how a human analyst would build the report.
    </Tip>
  </Step>

  <Step title="Adding precision at the view level">
    [View-level](/modeling/views) context eliminates ambiguity when two fields have similar names or when a field has a cryptic database label.

    ```yaml title="View and field-level context" wrap theme={null}
    # order_items.view.omni
    dimensions:
      id:
        sql: '"ID"'
        primary_key: true
        ai_context: >
          Generated automatically for each product in an order.
          Do not include this in queries unless specifically requested.

      status:
        sql: '"STATUS"'
        # Prevent hallucinations by defining all possible values
        all_values: [ Complete, Shipped, Processing, Cancelled, Returned ]
        ai_context: Current processing status of the individual item within the order.

      created_at:
        sql: '"CREATED_AT"'
        timeframes: [ date, week, month, quarter, year ]
        synonyms: [ purchase time, bought at ] # Map natural language to the field
        ai_context: >
          Timestamp of record creation. Preferred grains are date, week, and month.
    ```
  </Step>
</Steps>

## Iterating on AI context

Improving AI quality is an iterative process. Use this workflow to refine your instance based on real usage:

1. **Monitor**: Use the **AI usage** dashboard in the [**Analytics** section](/administration/analytics) to find queries with negative (👎) feedback.
2. **Identify**: Did the AI fail due to a cryptic name, a missing join, or a lack of business logic?
3. **Tune**: Update the YAML at the appropriate level (model, topic, view).
4. **Verify**: Re-run the prompt in the [**Omni Agent**](/ai/chat) to ensure the fix worked.

<Tip>
  When you correct the AI in a chat session (e.g., `"Actually, always use Fiscal Year"`), click the <Icon icon="brain" /> (brain) icon to have the AI [learn from the conversation](/ai/learn-from-conversation) and propose model changes to incorporate the correction.
</Tip>

## Next steps

* [Model-level ai\_context](/modeling/models/ai-context) — Reference for model-level `ai_context` syntax
* [Topic-level ai\_context](/modeling/topics/parameters/ai-context) — Reference for topic-level `ai_context` syntax
* [View-level ai\_context](/modeling/views/parameters/ai-context) — Reference for view-level `ai_context` syntax
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Broader guidance on optimizing your model for AI


# Optimizing AI context for SaaS and sales operations
Source: https://docs.omni.co/guides/patterns/optimizing-ai-context-for-saas-and-sales-operations

A hands-on guide to configuring AI context at the model, topic, and view levels using a SaaS and Salesforce example.

<GuideSidebar />

<GuideTitle title="Optimizing AI context for SaaS and sales operations" />

This guide provides a hands-on reference for building out AI context within a SaaS-focused Omni instance, specifically centered on **Salesforce Opportunities**.

By following this example, you can see how to move beyond basic schema discovery to a high-precision setup where the AI understands complex sales logic and terminology like "pipeline," "IQCC," and "weighted forecasts."

## Why AI context matters

While Omni understands your schema, `ai_context` lets you encode sales-specific knowledge — like what 'pipeline' means or how to calculate IQCC — so the AI can answer questions accurately. For example, sales context could look like:

* **Defining terminology:** Does "pipeline" mean every open deal, or only "new business" in specific stages?
* **Handling personas:** Automatically filtering by a manager's specific region or segment when they ask about `my team` using user attributes.
* **Calculating velocity:** Defining terms like IQCC (In-Quarter Create & Close) so the AI can track speed-to-revenue without manual intervention.

## The AI context hierarchy

To help the AI return accurate, business-aligned answers, you can add context to the underlying data model. For this example, think of the context in three layers: model, topic, and view.

Omni applies this logic from the top down - starting at the model level - allowing you to set universal rules that get more specific as you move toward individual fields.

| **Layer**      | **Purpose**                                                                                              | **Example**                                                               |
| :------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| **Model**      | **Universal truths.** Global business logic and formatting rules that apply to all queries in the model. | "All revenue is ARR; our fiscal year begins Feb 1st."                     |
| **Topic**      | **The persona.** The topic level defines more specific details scoped to your pre-defined datasets.      | "You are a Sales Ops Analyst; 'Pipeline' excludes 'Renewals' by default." |
| **View/Field** | **Field precision.** Specific definitions, synonyms, and allowed values for columns.                     | "'Stage' is a synonym for `stage_name`. 'Won' means `is_won = true`."     |

## Requirements

To implement this example in your own Omni instance, you'll need:

* Familiarity with Omni's modeling layer
* Permissions in Omni that allow you to edit a shared model
* A connected data source that contains SaaS or sales-related data

<Steps>
  <Step title="Setting universal rules in the model file">
    The [model file](/modeling/models) defines your universal rules that will exist across the entire model. These rules act as permanent guardrails, ensuring the AI adheres to your core business standards regardless of which topic in the model a user is exploring.

    ```yaml title="Model-level context" wrap theme={null}
    ai_context: |-
      ## Global Business Logic
      - All currency values represent Annual Recurring Revenue (ARR) unless otherwise specified.
      - Our Fiscal Year follows a standard calendar (Jan-Dec), but "Fiscal Quarter" should be used for all board reporting.
      - When users say "My Team" or "My Territory," always reference the `user_attributes` for Segment and Region.

      ## Data Handling & Formatting
      - Always hide internal Salesforce 18-digit IDs from the final visualization unless troubleshooting is requested.
      - Prefer 'Close Date' for any historical revenue analysis and 'Created Date' for pipeline generation analysis.

      ## SaaS Definitions
      - "Net New" refers specifically to 'New Business' + 'Expansion' - 'Churn'.
      - A "Logo" refers to a unique Account. When asked for "Logo Count," use a distinct count on `account_id`.
    ```
  </Step>

  <Step title="Setting dataset logic in the topic">
    [Topic-level](/modeling/topics) context defines more specific details scoped to your pre-defined datasets. This tells the AI how to navigate stages, deal types, and user permissions for Salesforce data.

    ```yaml title="Topic-level context" wrap expandable theme={null}
    base_view: omni_dbt_saas__opportunities
    group_label: Sales & Revenue
    display_order: 5
    description: |
      Sales pipeline and revenue data from Salesforce. This topic enables comprehensive sales analysis including pipeline management, revenue forecasting, sales performance tracking, win/loss analysis, and sales cycle analysis.

    ai_context: |-
      You are an expert sales data analyst.

      When someone asks about their team or how their team is doing or their pipeline or says something like "my team" always filter account.segment = {{ omni_attributes.segment }} and account.region = {{ omni_attributes.region }}

      ## Opportunity Definitions:
      - "Pipeline" means open new opportunities (status = Open Pipeline, type = New Business).
      - "Lost deals": filter on stage_name = Closed Lost and status = Closed.
      - "Won deals": filter on stage_name = Closed Won and status = Closed.
      - "Active trials": filter on stage_name = [Trial, Trial Positive].
      - "IQCC" (In-Quarter Create Close): Type = New Business opportunities that were closed won in the same quarter they were created.

      ## Sales Analysis Logic:
      - Revenue/Sales: Always use omni_dbt_saas__opportunity.amount_sum.
      - Sales Reps: Use the name omni_dbt_saas__user.name. Never return an ID.
      - If asked about risks, show competitors, days since last stage change, and loss_reason.
      - Use close_date for revenue timing and sales cycle analysis.

    sample_queries:
      Active Trials:
        query:
          fields:
            [
              "omni_dbt_saas__opportunities.close_date[date]",
              omni_dbt_saas__opportunities.name,
              omni_dbt_saas__user.name,
              omni_dbt_saas__opportunities.stage_name,
              omni_dbt_saas__opportunities.amount_sum
            ]
          base_view: omni_dbt_saas__opportunities
          filters:
            omni_dbt_saas__opportunities.type:
              is: New Business
            omni_dbt_saas__opportunities.stage_name:
              is: [ Trial, Trial Positive, Negotiate ]
        description: Show a list of all active trials
        prompt: Show me all active trials
        ai_context: "This is a list of all active trials."

      Deals Won this Quarter:
        query:
          fields:
            [
              omni_dbt_saas__opportunities.name,
              omni_dbt_saas__user.name,
              "omni_dbt_saas__opportunities.close_date[date]",
              omni_dbt_saas__opportunities.competitor,
              omni_dbt_saas__opportunities.stage_name,
              omni_dbt_saas__opportunities.amount_sum
            ]
          base_view: omni_dbt_saas__opportunities
          filters:
            omni_dbt_saas__opportunities.type:
              is: [ New Business, Expansion ]
            omni_dbt_saas__opportunities.close_date:
              time_for_duration: [ 1 quarters ago, 1 quarters ]
            omni_dbt_saas__opportunities.stage_name:
              is: Closed Won
        description: List of deals won in this quarter
        ai_context: All the deals that have closed this quarter.

      Won iARR:
        query:
          fields: [ omni_dbt_saas__opportunities.amount_sum ]
          base_view: omni_dbt_saas__opportunities
          filters:
            omni_dbt_saas__opportunities.type:
              is: [ New Business, Expansion ]
            omni_dbt_saas__opportunities.is_won:
              is: true
        description: how much iARR we've won across all time
        prompt: What is our total won iARR?
        ai_context: use this when asked about our total iarr
    ```

    <Tip>
      **Include sample queries**. By including all three `sample_queries` above, you ensure the AI has explicit examples of how to handle trials, quarterly wins, and cumulative revenue.
    </Tip>
  </Step>

  <Step title="Adding precision at the view level">
    [View-level](/modeling/views) context ensures the AI knows the difference between a **lead source** and a **forecast category**, and provides synonyms to catch natural language variations.

    ```yaml title="View-level context" wrap theme={null}
    view: omni_dbt_saas__opportunities
    fields:
      stage_name:
        sql: '"STAGE_NAME"'
        all_values: [Closed Lost, Closed Won, Qualified, Trial Positive, Pre-Qualified, Trial, Negotiate]
        synonyms: [Stage, Pipeline Stage, Opportunity gate]
        ai_context: |
          Early stage deals are prequalified and qualified. Late stage deals are trial positive and negotiate.

      amount:
        sql: '"AMOUNT"'
        synonyms: [deal_amount, contract_value, ARR]
        ai_context: |
          Use this field for revenue forecasting. Use amount_sum measure for aggregated totals.

      type:
        sql: '"TYPE"'
        all_values: [New Business, Expansion, Renewal]
        ai_context: |
          Distinguish between new customer acquisition (New Business), expansion/upsell, and renewals.

      lead_source:
        sql: '"LEAD_SOURCE"'
        all_values: [Referral, Inbound, Outbound, Organic]
        ai_context: |
          The channel the opportunity was generated from. Use this if asked where an opportunity came from.
    ```
  </Step>
</Steps>

## Iterating on AI context

Improving AI quality is an iterative process. Use this workflow to refine your context:

1. **Monitor**: Use the **AI usage** dashboard in the [**Analytics** section](/administration/analytics) to find queries with negative (👎) feedback.
2. **Identify**: Did the AI fail due to a missing synonym or lack of business logic?
3. **Tune**: Update the YAML at the appropriate level (Model, Topic, or View).
4. **Verify**: Re-run the prompt in the [**Omni Agent**](/ai/chat) to ensure the fix worked.

<Tip>
  When you correct the AI in a chat session (e.g., `"Actually, always use Fiscal Year"`), click the <Icon icon="brain" /> (brain) icon to have the AI [learn from the conversation](/ai/learn-from-conversation) and propose model changes to incorporate the correction.
</Tip>

## Next steps

* [Model-level ai\_context](/modeling/models/ai-context) — Reference for model-level `ai_context` syntax
* [Topic-level ai\_context](/modeling/topics/parameters/ai-context) — Reference for topic-level `ai_context` syntax
* [View-level ai\_context](/modeling/views/parameters/ai-context) — Reference for view-level `ai_context` syntax
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Broader guidance on optimizing your model for AI


# Optimizing AI context for support operations
Source: https://docs.omni.co/guides/patterns/optimizing-ai-context-for-support-operations

Configure AI context across model, topic, and view levels to optimize Omni's AI for support operations.

<GuideSidebar />

<GuideTitle title="Optimizing AI context for support operations" />

This guide provides a hands-on reference for building out AI context within an Omni instance focused on customer support and Zendesk tickets.

By following this example, you can see how to move beyond basic schema discovery to a **high-precision setup** where the AI understands complex support logic like SLA targets, ticket lifecycles, and account risk.

## Why AI context matters

In support operations, data is often defined by the "state" of a ticket or the urgency of a customer. While Omni understands your tables, `ai_context` codifies the operational knowledge required for the AI to act as a seasoned support lead. For example, support context could look like:

* **Defining "active issues":** Does "active" mean only 'new' tickets, or does it include those 'pending' a customer response?
* **SLA logic:** Mapping priority levels (urgent vs. normal) to specific response time expectations so the AI can identify breaches.
* **Sentiment and risk:** Helping the AI understand that a high volume of tickets for a single `account_id` isn't just "work" - it's a signal of potential churn or a "customer at risk."

## The AI context hierarchy

To build a high-precision instance, think of your context in three layers. Omni applies this logic from the top down, ensuring universal support standards are respected before field-level definitions.

| **Layer**      | **Purpose**                                                                                                      | **Example**                                                                    |
| :------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| **Model**      | **Universal truths.** The model file defines your universal rules that will exist across your entire Omni model. | "All time durations are in hours; our support week is 24/7."                   |
| **Topic**      | **The persona.** The topic level defines more specific details scoped to your pre-defined datasets.              | "You are a support ops analyst; 'Resolved' means Solved or Closed."            |
| **View/Field** | **Field precision.** Specific definitions, synonyms, and allowed values for columns.                             | "'Urgency' is a synonym for `priority`. 'Bug' is a specific `type` of ticket." |

## Requirements

To implement this example in your own Omni instance, you'll need:

* Familiarity with Omni's modeling layer
* Permissions in Omni that allow you to edit a shared model
* A connected data source that contains support-related data

<Steps>
  <Step title="Set universal rules in the model file">
    The [model file](/modeling/models) defines your universal rules that will exist across your entire Omni model. These rules ensure the AI adheres to your core support standards regardless of which topic a user is exploring.

    ```yaml title="Context that applies to the entire model" wrap theme={null}
    ai_context: |-
      ## Global Business Logic
      - All "Time to Resolve" or "Response Time" metrics should be displayed in decimal hours unless minutes are specifically requested.
      - Our support organization operates on a 24/7 basis; do not exclude weekends from duration calculations unless "Business Hours" are specified.
      - When users ask about "At-Risk Customers," prioritize those with more than 5 'Open' tickets or a CSAT score below 3.

      ## Data Handling & Formatting
      - Always hide internal Zendesk system IDs (like user_id) in the final visualization; use Name or Email instead.
      - For any customer satisfaction (CSAT) analysis, the scale is 1-5, where 5 is the best.
      ## Support Definitions
      - "Technical Debt" refers to tickets where the type is 'bug' or 'incident'.
      - "Self-Service" refers to tickets sourced from the 'web' channel that were closed with a single interaction.
    ```
  </Step>

  <Step title="Set dataset logic in the topic">
    The topic level defines more specific details scoped to your pre-defined datasets. This tells the AI how to navigate ticket statuses, support channels, and engineering links, like those to a Jira instance.

    ```yaml title="Topic-level context" wrap theme={null}
    base_view: omni_dbt_saas__zendesk_tickets
    label: Support Tickets
    group_label: Product Analytics
    description: |
      Customer support tickets from Zendesk. Use this to track team performance,
      identify product issues, and analyze support channel effectiveness.

    ai_context: |-
      This topic focuses on customer support and service operations.

      ## Support Lifecycle definitions:
      - "Open tickets" or "Active issues": filter on status = [new, open, pending].
      - "Resolved tickets": filter on status = [solved, closed].
      - "High priority": filter on priority = [urgent, high].
      - "Feature requests": filter on type = feature_request.
      - "Technical issues": filter on type = problem or bug.

      ## Analysis Logic:
      - Customer Satisfaction (CSAT): Use the satisfaction_score field.
      - Response Time: Use first_response_time_hours.
      - Resolution Time: Use resolution_time_hours.
      - Account Risk: Use account_id to identify customers with high ticket volumes.
      - Engineering Link: Use jira_issue_id to connect support tickets to development work.

      ## Formatting:
      - Always make dimensions (labels/values) the first columns in the table, and measures (counts/sums) after.
    ```
  </Step>

  <Step title="Add precision at the view level">
    The view level ensures the AI knows the operational significance of different fields, such as how `priority` maps to SLAs or how `channel` reflects customer preference.

    ```yaml title="View-level context" wrap theme={null}
    view: omni_dbt_saas__zendesk_tickets
    fields:
      status:
        sql: '"STATUS"'
        all_values: [new, open, pending, solved, closed]
        synonyms: [ticket_status, workflow_status]
        ai_context: |
          New/Open tickets require immediate action. Pending tickets are waiting on a response.
          Solved/Closed represent completed work.

      priority:
        sql: '"PRIORITY"'
        all_values: [urgent, high, normal, low]
        synonyms: [urgency, ticket_priority]
        ai_context: |
          Priority maps to SLA targets: Urgent (<1hr), High (<4hr), Normal (<24hr), Low (<72hr).
          Higher priorities indicate greater business risk.

      type:
        sql: '"TYPE"'
        all_values: [problem, question, task, feature_request, incident, bug]
        ai_context: |
          'Problem' or 'Bug' require engineering attention. 'Feature_request' informs the roadmap.
          'Question' suggests a need for better documentation.

      channel:
        sql: '"CHANNEL"'
        all_values: [web, email, phone, chat, api]
        ai_context: |
          'Phone' is high-cost/urgent. 'Chat' is high-satisfaction/quick.
          'API' represents automated integrations.
    ```
  </Step>
</Steps>

## The feedback loop

Support trends change with every product release. Use this workflow to keep your AI accurate:

1. **Monitor**: Use the **AI usage** dashboard in the [**Analytics** section](/administration/analytics) to see if users are struggling to find bug reports versus feature requests.
2. **Identify**: Did the AI fail because a specific product area wasn't defined in the context?
3. **Tune**: Update the YAML (e.g., add a synonym for "Product Issue" pointing to `type = bug`).
4. **Verify**: Re-run the prompt in the [**Omni Agent**](/ai/chat) to confirm the AI now maps the term correctly.

<Tip>
  **SLA breach tip:** Use `ai_context` in your `resolution_time_hours` field to define a breach.

  For example: `"If priority is urgent and resolution time > 1, this is an SLA breach."`

  This allows users to ask `"How many SLA breaches did we have yesterday?"`
</Tip>

## Next steps

* [Model-level ai\_context](/modeling/models/ai-context) — Reference for model-level `ai_context` syntax
* [Topic-level ai\_context](/modeling/topics/parameters/ai-context) — Reference for topic-level `ai_context` syntax
* [View-level ai\_context](/modeling/views/parameters/ai-context) — Reference for view-level `ai_context` syntax
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Broader guidance on optimizing your model for AI


# Optimizing AI context for Media and AdTech
Source: https://docs.omni.co/guides/patterns/optimizing-ai-context-media-and-adtech

A hands-on guide to configuring AI context at the model, topic, and view levels using a Media and AdTech example.

<GuideSidebar />

<GuideTitle title="Optimizing AI context for Media and AdTech" />

This guide provides a hands-on reference for building out AI context within a real-world Omni instance, focusing on media organizations and advertising technology (AdTech) datasets. Whether you're managing a portfolio of global publications or a high-traffic digital platform, providing clear context ensures Omni's AI accurately interprets metrics across subscriptions, advertising spend, and content engagement.

By defining how your data relates to industry-standard concepts like CPM, audience segments, and multi-channel revenue, you empower your team to ask complex questions and receive reliable, data-driven answers.

## Why AI context matters

While Omni automatically understands your schema, `ai_context` allows you to codify company-specific knowledge that isn't captured in table names or column labels.

Think of this as training your AI analyst on your company's specific playbook. In a retail environment, this means:

* **Defining terminology:** Does *Revenue* refer to gross ad billings, net publisher payout, or recurring subscription MRR?
* **Handling personas:** Automatically filtering by a brand manager's specific publication or a sales rep's assigned advertiser categories when they ask about `my performance`.
* **Calculating yield:** Defining industry-standard formulas like CPM (Cost Per Mille) or ARPU (Average Revenue Per User) so the AI can track monetization efficiency without manual intervention.

## The AI context hierarchy

To help the AI return accurate, business-aligned answers, you can add context to the underlying data model. For this example, think of the context in three layers: model, topic, and view.

Omni applies this logic from the top down - starting at the model level - allowing you to set universal rules that get more specific as you move toward individual fields.

| **Layer**      | **Purpose**                                                                                              | **Example**                                                                                            |
| :------------- | :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
| **Model**      | **Universal truths.** Global business logic and formatting rules that apply to all queries in the model. | Setting the `revenue_by_brand` table as the source of truth for all **Total Revenue** queries.         |
| **Topic**      | **The persona.** The topic level defines more specific details scoped to your pre-defined datasets.      | Instructing the AI to use `minutes_on_site` as the primary metric when a user asks about "stickiness." |
| **View/Field** | **Field precision.** Specific definitions, synonyms, and allowed values for columns.                     | Mapping **Publication** or **Property** as synonyms for the `brand_name` dimension.                    |

## Requirements

To implement this example in your own Omni instance, you'll need:

* Familiarity with Omni's modeling layer
* Permissions in Omni that allow you to edit a shared model
* A connected data source that contains media or AdTech data

<Steps>
  <Step title="Setting universal rules in the model file">
    The [model file](/modeling/models) defines your universal rules that will exist across the entire model. These rules act as permanent guardrails, ensuring the AI adheres to your core business standards regardless of which topic in the model a user is exploring.

    ```yaml title="Model-level context" wrap theme={null}
    ai_context: |-
        ## Global Business Logic
        - Brands are the primary entities.
        - Revenue is diversified across Advertising (Campaign Spend), 				Subscriptions (MRR), and Commerce.
        - Customers are readers/viewers categorized by Segments (Free vs. Subscriber).
        - When asked for 'Total Revenue', default to the 'revenue_by_brand' table as the consolidated source of truth.
        - When users say "My Brands" or "My Vertical," always reference the `user_attributes` for assigned Brand Category.
        
        ## Data Handling & Formatting
        - Traffic and Content Performance measure engagement across formats like Articles and Videos.
        - Always use 'Signup Date' for subscriber cohort analysis and 'Campaign Start Date' for ad performance trends.
        - Hide internal technical IDs from final visualizations unless explicitly asked for "Raw Data" or "ID Level" details.
        
        ## Media & AdTech Definitions
        - "Stickiness" refers primarily to 'minutes_on_site' and session frequency.
        - A "Subscriber" refers to a unique Customer ID with an active 'plan_type'. 
        - "Yield" is calculated by dividing total ad spend by total impressions and multiplying by 1000 to return CPM.
    ```
  </Step>

  <Step title="Setting dataset logic in the topic">
    [Topic-level](/modeling/topics) context defines more specific details scoped to your pre-defined datasets. This tells the AI how to navigate things like your campaign spend, traffic, and customer data.

    ```yaml title="Topic-level context" expandable wrap theme={null}
    base_view: media_dataset_main__brands
    label: Brand Topic

    joins:
    	media_dataset_main__campaign_spend:
    		media_dataset_main__advertisers: {}
    	media_dataset_main__content_performance: {}
    	media_dataset_main__customer_monthly_activity: {}
    	media_dataset_main__customers: {}
    	media_dataset_main__revenue_by_brand: {}
    	media_dataset_main__traffic_by_brand: {}

    ai_context: |
      Use this topic to analyze Brand health, Advertiser spend, and Audience engagement.
      ## Revenue
      - Analyze monetization via 'revenue_by_brand' for high-level totals across all streams. 
      - Use 'campaign_spend' when the user asks about specific Advertisers or Ad Categories (e.g., CPG, Tech). 
      - To calculate 'Yield', always divide spend by impressions and multiply by 1000 to get CPM.
      
      ## Audience
      - Evaluate user growth and retention using the 'customers' and 'customer_monthly_activity' views. 
      - Prioritize 'segment' (Free vs. Subscriber) to understand how different cohorts consume content. 
      - Use 'minutes_on_site' as the primary metric for user "stickiness" and attention.
      
      ## Content
      - Assess editorial performance using 'content_performance' grouped by 'content_type'. 
      - Compare 'total_views' against 'content_pieces' to identify the most efficient formats (e.g., Quizzes vs. Articles). 
      - When analyzing engagement, focus on 'total_engagement' relative to total page views.
    ```
  </Step>

  <Step title="Adding precision at the view level">
    [View-level](/modeling/views) context ensures the AI understands technical identifiers, distinguishes between different types of spend and delivery, and maps editorial jargon like **Properties** or **Verticals** to the correct dimensions.

    ```yaml title="View-level context: Brands view" wrap theme={null}
      view: media_dataset_main__brands
      dimensions:
        brand_id:
          sql: '"BRAND_ID"'
          primary_key: true
          ai_context: Unique 2-3 letter code for the brand.
        
    	brand_name:
          sql: '"BRAND_NAME"'
          synonyms: [ publication, property, title, site ]
          ai_context: The primary display name of the media brand.
        
    	category:
          sql: '"CATEGORY"'
          all_values: [ Lifestyle, Fashion, Tech, Business, Entertainment ]
          synonyms: [ vertical, pillar ]
          ai_context: The industry vertical the brand operates within.
    ```

    ```yaml title="View-level context: Campaign Spend view" wrap theme={null}
      view: media_dataset_main__campaign_spend
      dimensions:
        campaign_id:
          sql: '"CAMPAIGN_ID"'
          primary_key: true
          ai_context: Unique ID for an ad campaign. Do not include in totals unless requested.
        
    	spend_usd:
          sql: '"SPEND_USD"'
          type: number
          synonyms: [ ad revenue, billing, client spend, booked revenue ]
          ai_context: Gross dollar amount spent by the advertiser on a specific brand.
        
    	impressions:
          sql: '"IMPRESSIONS"'
          type: number
          synonyms: [ ad delivery, ad views, served ads ]
          ai_context: Total count of ads served; the denominator for CPM.
    ```
  </Step>
</Steps>

## Iterating on AI context

Improving AI quality is an iterative process. Use this workflow to refine your context:

1. **Monitor**: Use the **AI usage** dashboard in the [**Analytics** section](/administration/analytics) to find queries with negative (👎) feedback.
2. **Identify**: Did the AI fail due to a missing synonym or lack of business logic?
3. **Tune**: Update the YAML at the appropriate level (model, topic, or view).
4. **Verify**: Re-run the prompt in the [**Omni Agent**](/ai/chat) to ensure the fix worked.

<Tip>
  When you correct the AI in a chat session (e.g., `"Actually, always use Fiscal Year"`), click the <Icon icon="brain" /> (brain) icon to have the AI [learn from the conversation](/ai/learn-from-conversation) and propose model changes to incorporate the correction.
</Tip>

## Next steps

* [Model-level ai\_context](/modeling/models/ai-context) — Reference for model-level `ai_context` syntax
* [Topic-level ai\_context](/modeling/topics/parameters/ai-context) — Reference for topic-level `ai_context` syntax
* [View-level ai\_context](/modeling/views/parameters/ai-context) — Reference for view-level `ai_context` syntax
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Broader guidance on optimizing your model for AI


# Building a basic cohort analysis with pivots
Source: https://docs.omni.co/guides/patterns/simple-cohort-analysis-pivot

Build a cohort analysis using pivots in Omni to track user retention, engagement, and behavior over time.

<GuideSidebar />

<GuideTitle title="Building a basic cohort analysis with pivots" />

Create a cohort analysis to understand how specific groups of users behave over time. By comparing different cohorts, you can identify patterns in retention, engagement, or purchasing behavior.

<Steps>
  <Step title="Create the cohort grid">
    To build your initial cohort, follow these steps:

    1. Choose a fixed dimension, such as the date a user was created. This date acts as your cohort identifier and should be placed on the X-axis.

       <img alt="Cohort date field selected in the Omni query builder" />

    2. Choose the date representing the behavior or activity you want to track.

    3. [Pivot](/analyze-explore/point-click-queries) the activity date to see how activity changes over subsequent periods.

       <img alt="Activity date pivoted in the Omni query builder" />

    4. Choose a measure that reflects the behavior you are analyzing, such as a **Count** or **Count Distinct** of a specific action.

       <img alt="Selected fields in the Omni query builder" />

    5. Review the results. Omni automatically generates the "cohort triangle" visualization based on these selections.

       <img alt="Cohort triangle results in Omni" />
  </Step>

  <Step title="Visualize with conditional formatting">
    You can make your analysis more readable by applying a color scale to the table:

    1. In the **Visualizations** tab, select the **Table** visualization.
    2. Click the [**Conditional Formatting** tab](/visualize-present/visualizations/types/table#conditional-formatting-options) in the **Chart Options** panel.
    3. For **Rule type**, select **Color Scale**.
    4. In **Apply to**, select the measure to apply the scale against. This visually highlights how each cohort is performing relative to others.

       <img alt="Table visualization with color scale applied to cohort data" />

    <Tip>
      **Use a sequential color scale** (e.g., light to dark) to quickly identify where retention or engagement drops off across different time periods.
    </Tip>
  </Step>
</Steps>

## Video walkthrough

<iframe title="Building a simple cohort analysis with pivots" />

## Next steps

* [Learn more about table visualizations](/visualize-present/visualizations/types/table) to further customize your view.
* [Explore advanced querying](/analyze-explore/point-click-queries) to add filters or custom calculations to your cohort.


# Cohort analysis using a thin spine
Source: https://docs.omni.co/guides/patterns/spine-cohort-analysis

Build cohort analyses using thin dimensional spines.

<GuideSidebar />

<GuideTitle title="Cohort analysis using a thin spine" />

In the [Thin dimensional spine for multi-fact event analysis guide](/guides/patterns/thin-dimension-spine), you learned what a thin dimensional spine is, how it works, and how to implement your own using dbt and Omni.

In this guide, we'll build on the knowledge in that guide to walk you through several approaches to cohort analysis.

## Requirements

To follow along with this guide, you'll need:

* **To have read the [Thin dimensional spine for multi-fact event analysis guide](/guides/patterns/thin-dimension-spine).** This guide describes the basics of thin dimensional spines and how to build and materialize your own.
* **Familiarity with [modeling](/modeling) in Omni**

## Attribute-based cohorts

To build this type of analysis:

1. Maintain an attribute table with per-user first/last timestamps, e.g., `attr__users_event_bounds` with `first_signup_ts`, `first_purchase_ts`.
2. Group and filter users by these milestones across event streams

## Event-to-event cohorts

This type of analysis looks at the timing between events — for example, signup-to-first-login latency, or engagement patterns following a first purchase.

## Dynamic 'time since selected event' cohorting

Using the spine, you can model a dynamic "since basis" and "grain" selector to compute buckets of time since a specific event:

```yaml title="Snippet: dim__user_event_spine_thin.view" expandable theme={null}
dimensions:
  selected_basis_ts:
    type: timestamp
    sql: |
      case {{filters.dim__user_event_spine_thin.cohort_basis.value}}
        when 'first_ad' then ${attr__users_event_bounds.first_ad_ts}
        when 'first_signup' then ${attr__users_event_bounds.first_signup_ts}
        else ${attr__users_event_bounds.first_ad_ts}
      end

  time_since_selected_event:
    type: number
    label: Time Since Selected Event
    sql: |
      datediff(
        case {{filters.dim__user_event_spine_thin.cohort_grain.value}}
          when 'day' then 'day'
          else 'day'
        end,
        ${selected_basis_date},
        ${event_date_day}
      )
```


# Thin dimensional spine for multi-fact event analysis
Source: https://docs.omni.co/guides/patterns/thin-dimension-spine

Analyze multiple event streams together without fanout using a thin dimensional spine.

<GuideSidebar />

<GuideTitle title="Thin dimensional spine for multi-fact event analysis" />

This guide walks you through building a **thin dimensional spine** in Omni — a modeling pattern that lets you analyze many independent event tables together by time and shared entity attributes without incurring fanout or poor performance.

While the examples below use mobile gaming events (logins, sessions, ads, purchases), this pattern applies to any domain with multiple event streams sharing common dimensions, such as SaaS product events, marketplace activity, or IoT telemetry.

## When to use this pattern

Use this pattern when:

* You have many event tables sharing common dimensions like `user_id`.
* Analysts want a single Topic for analysis across multiple event streams.
* Queries typically touch only a subset of those event streams.
* Performance and predictable SQL generation are priorities.

## How to model thin spine tables

A common approach to multi-fact analysis is to model a massive join of `calendar x users x all event tables`. This quickly leads to fanout, slow queries, and unpredictable SQL. Instead, you can model a **thin dimensional spine** — a table where each row represents the *existence* of activity, not the details of the activity itself.

Instead of this:

```yaml title="Avoid this pattern, which joins everything together" theme={null}
calendar x users x all event tables
```

You model this:

```yaml title="Use this pattern, which creates a thin spine of activity" theme={null}
(event_date_day, user_id, event_type)
```

Which you could use to create a spine table like `dim__user_event_spine_thin`. This table contains one row per (`event_date_day`, `user_id`, `event_type`) combination that actually occurred:

| **user\_id** | **event\_date\_day** | **event\_type** |
| :----------- | :------------------- | :-------------- |
| 101          | 2025-01-10           | login           |
| 101          | 2025-01-10           | session\_start  |
| 101          | 2025-01-10           | ad\_impression  |
| 204          | 2025-01-10           | iap\_purchase   |

<Tip>
  **Using Snowflake?** Cluster your spine by (`event_date_day`, `event_type`) to improve query performance.
</Tip>

### Modeling a secondary date spine

In addition to the thin spine, you should maintain a date-only spine table (`dim__date_spine`) for calendar descriptors. This gives you a clean place for all calendar fields without bloating the thin spine.

To build it:

* **Fields** - Include attributes like `is_weekday`, `is_us_federal_holiday`, or fiscal calendar fields.
* **Join logic** - Join to the topic on:
  ```sql theme={null}
  dim__user_event_spine_thin.event_date_day = dim__date_spine.date_day
  ```

### Storage considerations

While the spine is logically thin, it can still become large in absolute storage terms. Keep these factors in mind:

* **Row counts** - Each (`user`, `time grain`, `event_type`) combination produces a row
* **Granularity** - Hourly (or finer) spines significantly multiply row counts
* **Pruning** - Pruning helps query performance, but not storage footprint

To keep storage manageable:

* Default to **daily** granularity unless finer-grain analysis is truly required
* Use separate spines for different grains (e.g., a daily user spine and an hourly session spine)
* Be deliberate about which event types you include in the spine

### Spine materialization benefits

You may wonder whether it's worth materializing the spine given its potential size. While the spine can grow large, the cost is a known and bounded trade-off:

<Columns>
  <Card title="Build-time cost" icon="hand-holding-dollar">
    The spine intentionally shifts cost from query-time to build-time
  </Card>

  <Card title="Reduce effective scan size" icon="arrow-down">
    Pruning makes the effective scan much smaller than the full table size
  </Card>

  <Card title="Improve predictability" icon="list-check">
    CTE-only patterns can complicate cohort analysis and reusability
  </Card>

  <Card title="Semantic stability" icon="anchor">
    The spine creates a stable semantic surface for downstream analysis
  </Card>
</Columns>

## Build and model the spine with dbt and Omni

In this section, we'll walk you through how to build and materialize the thin spine table using dbt and then model it in Omni.

In this guide, we're using the following event tables:

* **Engagement** - `event__login`, `event__session_start`
* **Monetization and ads** - `event__iap_purchase`, `event__ad_impression`
* **Shared fields** - All event tables share `user_id` and `event_ts` (timestamp)

### Requirements

To follow along, you'll need:

* Familiarity with [dbt](/integrations/dbt)
* Familiarity with [modeling](/modeling) in Omni

<Steps>
  <Step title="Build a generate_event_spine_from_models dbt macro">
    First, you'll build a `generate_event_spine_from_models` macro in dbt. This pattern uses the macro to derive `event_type` from model names and emit a `UNION ALL` spine query.

    The macro expects:

    * Event models are named like `event__login`, `event__iap_purchase`, etc.
    * `event_type` is the suffix after `event__`.
    * Each event model includes `event_ts` and `user_id` columns, or you override these via arguments

    ```sql title="generate_event_spine_from_models macro" expandable theme={null}
    {% macro generate_event_spine_from_models(event_model_names,
      event_ts_col='event_ts',
      user_id_col='user_id',
      date_grain='day',
      event_prefix='event__',
      lower_bound_date_sql=None,
      upper_bound_date_sql=None) %}

    {% if event_model_names is not iterable %}
      {{ exceptions.raise_compiler_error("generate_event_spine_from_models: event_model_names must be an iterable of strings") }}
    {% endif %}

    {% set selects = [] %}
    {% for name in event_model_names %}
      {% if (name | trim).startswith(event_prefix) %}
        {% set event_type = (name | trim)[(event_prefix | length):] %}
      {% else %}
        {{ exceptions.raise_compiler_error("generate_event_spine_from_models: model " ~ name ~ " does not start with expected prefix.") }}
      {% endif %}

      {% set rel = ref(name | trim) %}

      {% set where_clauses = [] %}
      {% if lower_bound_date_sql is not none %}
        {% do where_clauses.append("to_date(date_trunc('"~date_grain~"', "~ event_ts_col ~ ")) >= " ~lower_bound_date_sql) %}
      {% endif %}
      {% if upper_bound_date_sql is not none %}
        {% do where_clauses.append("to_date(date_trunc('"~date_grain ~"', "~ event_ts_col~")) <= " ~ upper_bound_date_sql) %}
      {% endif %}

      {% set where_sql %}
        {% if where_clauses | length > 0 %} where {{ where_clauses | join("\n and ") }} {% endif %}
      {% endset %}

      {% set stmt %}
        select
          to_date(date_trunc('{{ date_grain }}', {{ event_ts_col }})) as event_date_day,
          {{ user_id_col }} as user_id,
          '{{ event_type }}' as event_type
        from {{ rel }}
        {{ where_sql }}
        group by 1, 2, 3
      {% endset %}
      {% do selects.append(stmt) %}
    {% endfor %}

    {{ selects | join("\nunion all\n") }}
    {% endmacro %}
    ```
  </Step>

  <Step title="Build an incremental dim__user_event_spine_thin dbt model">
    The next step is to build a `dim__user_event_spine_thin` model in dbt.

    The spine model is incremental and supports two modes:

    1. **Append-only** - Only inserts new spine rows beyond what already exists
    2. **Merge with a 7-day lookback window** - Recomputes the most recent 7 days and merges into the target

    ```sql title="dim__user_event_spine_thin model" expandable theme={null}
    {% set event_models = ['event__login', 'event__session_start', 'event__ad_impression', 'event__iap_purchase'] -%}
    {% set mode = var('spine_incremental_mode', 'merge_7d') -%}
    {% set loopback_days = var('spine_loopback_days', 7) -%}
    {% set full_day_offset = var('spine_full_day_offset_days', 1) -%}

    {{ config(
        materialized='incremental',
        unique_key=['event_date_day', 'user_id', 'event_type'],
        incremental_strategy='merge',
        cluster_by=['event_date_day', 'event_type']
    )}}

    with event_max_days as (
        {% for m in event_models %}
        select
            '{{m}}' as event_model,
            max(to_date(event_ts)) as max_event_day
        from {{ ref(m) }}
        {% if not loop.last %} union all {% endif %}
        {% endfor %}
    ),
    bounds as (
        select
            min(max_event_day) as last_available_day,
            dateadd('day', -{{ full_day_offset }}, min(max_event_day)) as last_full_day
        from event_max_days
    ),
    incremental_window as (
        select
            last_full_day,
            case
                when '{{ mode }}' = 'merge_7d'
                then dateadd('day', -{{ loopback_days }}, last_full_day)
                else null
            end as loopback_start_day
        from bounds
    ),
    spine_src as (
        {{ generate_event_spine_from_models(
            event_model_names=event_models,
            event_ts_col='event_ts',
            user_id_col='user_id',
            date_grain='day',
            lower_bound_date_sql="(select loopback_start_day from incremental_window)",
            upper_bound_date_sql="(select last_full_day from incremental_window)"
        )}}
    )
    select
        event_date_day,
        user_id,
        event_type
    from spine_src s
    {% if is_incremental() %}
        {% if mode == 'append' %}
            where s.event_date_day > (select coalesce(max(event_date_day), to_date('1900-01-01')) from {{ this }})
            and s.event_date_day <= (select last_full_day from incremental_window)
        {% else %}
            where s.event_date_day <= (select last_full_day from incremental_window)
        {% endif %}
    {% else %}
        where s.event_date_day <= (select last_full_day from incremental_window)
    {% endif %}
    ```
  </Step>

  <Step title="Build the topic in Omni">
    Once the spine is built, configure your Omni topic to use it as the base view. This topic uses the secondary date spine for calendar descriptors and enforces a date filter for safety.

    ```yaml title="user_activity.topic file" expandable highlight={3} theme={null}
    label: User Activity
    group_label: Multi-Fact Analytics
    base_view: dim_user_event_spine_thin

    joins:
      # Calendar descriptors — all date filtering should use this view
      dim__date_spine: {}

      # Attributes
      attr__users_profile: {}
      attr__users_progression: {}
      attr__users_monetization: {}
      attr__users_event_bounds: {}

      # Event tables
      event__login: {}
      event__session_start: {}
      event__ad_impression: {}
      event__iap_purchase: {}

    # Default workbook filter (visible/removable)
    default_filters:
      dim__date_spine.date_day:
        time_for_duration: [ 7 complete days ago, 7 days ]

    # Required pruning / safety filters
    always_where_sql: |
      (
        -- Require a date filter on the date spine.
        -- If a user removes the default date filter, this evaluates to FALSE and returns 0 rows.
        case when {{dim__date_spine.date_day.is_filtered}} then true else false end
      )
      AND
      (
        -- Prune event_type for optimal Snowflake partition performance
        ${dim__user_event_spine_thin.event_type} IN (
          case when {{ event__login.in_query }} then 'login' end,
          case when {{ event__session_start.in_query }} then 'session_start' end,
          case when {{ event__ad_impression.in_query }} then 'ad_impression' end,
          case when {{ event__iap_purchase.in_query }} then 'iap_purchase' end
        )
      )
    ```
  </Step>

  <Step title="Curate the topic fields">
    To make sure users filter consistently on the date spine, hide timestamps and non-common dimensions within the event views:

    ```yaml title="Snippet of user_activity.topic" expandable theme={null}
    views:
      event__login:
        dimensions:
          event_time:
            hidden: true
          login_method:
            hidden: true
          platform:
            hidden: true
      event__session_start:
        dimensions:
          event_time:
            hidden: true
          session_type:
            hidden: true
      event__iap_purchase:
        dimensions:
          event_time:
            hidden: true
          sku:
            hidden: true
          purchase_currency:
            hidden: true
    ```
  </Step>

  <Step title="Define relationships">
    The core philosophy of this pattern is to keep the thin spine minimal — it contains only join keys, `event_type`, and dates. All other metadata is joined in from external views.

    There are two key architectural decisions to understand:

    * **Prevent unnecessary symmetric aggregation** - Event relationships are explicitly set to `one_to_one` even though the actual cardinality is `one_to_many`. This prevents Omni from unnecessarily employing [symmetric aggregation](/analyze-explore/sql/symmetric-aggregates).
    * **Minimal base** - Many teams hide most or all dimensions on the thin spine so users primarily interact with date fields from the date spine, attributes from `attr_` tables, and measures from `event_` views.

    <Warning>
      Every additional event table follows this same structure. Repeat this pattern when you add new events.
    </Warning>

    ```yaml title="Omni Relationships file" expandable theme={null}
    # Spine → date spine (calendar descriptors)
    - join_from_view: dim__user_event_spine_thin
      join_to_view: dim__date_spine
      join_type: always_left
      on_sql: ${dim__user_event_spine_thin.event_date_day} = ${dim__date_spine.date_day}
      relationship_type: many_to_one

    # Spine → attributes
    - join_from_view: dim__user_event_spine_thin
      join_to_view: attr__users_profile
      join_type: always_left
      on_sql: ${dim__user_event_spine_thin.user_id} = ${attr__users_profile.user_id}
      relationship_type: many_to_one

    - join_from_view: dim__user_event_spine_thin
      join_to_view: attr__users_progression
      join_type: always_left
      on_sql: ${dim__user_event_spine_thin.user_id} = ${attr__users_progression.user_id}
      relationship_type: many_to_one

    - join_from_view: dim__user_event_spine_thin
      join_to_view: attr__users_event_bounds
      join_type: always_left
      on_sql: ${dim__user_event_spine_thin.user_id} = ${attr__users_event_bounds.user_id}
      relationship_type: many_to_one

    # Spine → events (conditional joins)
    - join_from_view: dim__user_event_spine_thin
      join_to_view: event__login
      join_type: always_left
      on_sql: |
        ${dim__user_event_spine_thin.event_type} = 'login'
        AND ${dim__user_event_spine_thin.user_id} = ${event__login.user_id}
        AND ${dim__user_event_spine_thin.event_date_day} = ${event__login.event_time[date]}
      relationship_type: one_to_one

    - join_from_view: dim__user_event_spine_thin
      join_to_view: event__session_start
      join_type: always_left
      on_sql: |
        ${dim__user_event_spine_thin.event_type} = 'session_start'
        AND ${dim__user_event_spine_thin.user_id} = ${event__session_start.user_id}
        AND ${dim__user_event_spine_thin.event_date_day} = ${event__session_start.event_time[date]}
      relationship_type: one_to_one

    - join_from_view: dim__user_event_spine_thin
      join_to_view: event__ad_impression
      join_type: always_left
      on_sql: |
        ${dim__user_event_spine_thin.event_type} = 'ad_impression'
        AND ${dim__user_event_spine_thin.user_id} = ${event__ad_impression.user_id}
        AND ${dim__user_event_spine_thin.event_date_day} = ${event__ad_impression.event_time[date]}
      relationship_type: one_to_one

    - join_from_view: dim__user_event_spine_thin
      join_to_view: event__iap_purchase
      join_type: always_left
      on_sql: |
        ${dim__user_event_spine_thin.event_type} = 'iap_purchase'
        AND ${dim__user_event_spine_thin.user_id} = ${event__iap_purchase.user_id}
        AND ${dim__user_event_spine_thin.event_date_day} = ${event__iap_purchase.event_time[date]}
      relationship_type: one_to_one
    ```
  </Step>

  <Step title="Build an example analysis">
    With the spine materialized and the Omni model built, you can try out what you've created by building an analysis. In this example, you'll build a cross-event analysis that looks at `Week x Country with multi-event measures`.

    In an Omni [workbook](/analyze-explore), create a query with the following configuration:

    * **Dimensions** - `dim__date_spine.date_day` (grouped by week) and `attr__users_profile.country`
    * **Measures** - `event__login.login_count`, `event__session_start.session_count`, `event__ad_impression.ad_impression_count`, and `event__iap_purchase.iap_revenue`
    * **Derived metric** - `avg_logins_per_user`, calculated by dividing login count by spine-level distinct users
  </Step>

  <Step title="Optional: Add new event streams">
    This pattern is designed to make adding new event types mechanical and low-risk. To add a new event stream:

    1. **dbt** - Add the event model name to `event_models` in the spine SQL
    2. **Omni topic** - In the Omni topic, add `event__new_event: {}` to the `joins` section
    3. **Pruning** - Add a `case when {{ event__new_event.in_query }} then 'new_event' end` line to `always_where_sql`.
    4. **Relationships** - In the Omni model's relationships file, add a conditional `one_to_one` relationship join matching on `event_type`, `user_id`, and date grain
  </Step>
</Steps>

## Best practices for modeling spines in Omni

Now that you've walked through modeling spines in Omni, we have a few tips to reduce surprises in aggregation and filtering. Keep the following in mind when modeling in Omni.

### General tips

* **Hide non-common dimensions** - Expose only curated measures and optionally timestamps for drilling
* **Prefer curated metrics** - Instead of raw fields like `purchase_amount`, expose measures like `iap_revenue` or `payer_count`
* **Keep cohort-defining fields in attribute space** - Put cohort keys in `attr__` tables so they behave consistently across event streams

### Apply topic best practices

As your model grows, topics can become difficult to use if the field list gets too large or too heterogeneous. Keep these guidelines in mind:

* **Focus over mega-topics** - Prefer multiple focused topics (e.g., `engagement`, `monetization`) over a single mega-topic
* **User-facing product** - Treat topics as user-facing products with coherent scopes
* **Spine reusability** - The thin spine is **infrastructure** — you can reuse it across multiple topics

For more topic design guidance, refer to the [Topic design best practices guide](/modeling/topics/best-practices).

### Use filtered measures for event-specific breakdowns

Instead of exposing event-specific dimensions directly, create curated filtered measures. For example, if `event__login` has a `login_method` dimension, you can create specific measures for counts of Google or iCloud logins:

```yaml title="event__login.view (illustrative)" theme={null}
measures:
  login_count:
    aggregate_type: count
  google_login_count:
    label: Google Logins
    aggregate_type: count
    filters:
      event__login.login_method:
        is: google
  icloud_login_count:
    label: iCloud Logins
    aggregate_type: count
    filters:
      event__login.login_method:
        is: icloud
```

### Build a cross-event analysis

With this pattern in place, you can build cross-event analyses like a weekly report by country. You would use:

* **Dimensions** - `dim__date_spine.date_day` (grouped by week) and `attr__users_profile.country`
* **Measures** - `event__login.login_count`, `event__session_start.session_count`, `event__ad_impression.ad_impression_count`, and `event__iap_purchase.iap_revenue`
* **Derived metrics** - For example, `avg_logins_per_user` calculated by dividing login count by spine-level distinct users

## Next steps

Now that you understand thin dimensional spines and how to build your own, you can use them to build different types of analysis. For example, start with the [Build cohort analysis with thin spine guide](/guides/patterns/spine-cohort-analysis).


# Add links to visualizations
Source: https://docs.omni.co/guides/visualizations/add-links

Encourage self-service data exploration by adding links to other dashboards to your visualizations.

<GuideSidebar />

<GuideTitle title="Add links to visualizations" />

A great way to encourage self-service data exploration is by adding URL links to your charts and visualizations. That way, your teammates can click on a data point and explore other dashboards. For example, here are a few common use cases we see:

* **Customer lookup** - In a table listing your biggest customers, you can add a link to the `Salesforce Account ID` field that will take you to their Salesforce Account page.
* **Application database** - In a graph of most common error codes encountered by users, you can add a link to the `Error Code` field that links to your application database's most recent instances of that error code.
* **Cross-linking dashboards** - In a chart with number of orders per customer, you can add a link to a **Customer Lookup** Omni dashboard that lets you see more details on a specific customer.

## Linking in action

Check out what linking in a visualization looks like in practice with this short video demonstration:

<Frame>
  <iframe title="Links in Omni visualizations" />
</Frame>

## Adding dynamic links to fields

Omni lets you add dynamic links to individual dimensions and measures to curate that self-service data exploration. All you need to do is add the [`links` parameter](/modeling/dimensions/parameters/links) to the field in your model:

```yaml title="Search engine links on country field" theme={null}
country:
  links:
    - url: https://www.google.com/search?q=${users.country}
      label: Google
      icon_url: https://cdn4.iconfinder.com/data/icons/new-google-logo-2015/400/new-google-favicon-1024.png
    - url: https://www.bing.com/search?q=${users.country}
      label: Bing
```


# Customize drill fields
Source: https://docs.omni.co/guides/workbooks/custom-drill-fields

Curate the columns displayed to users when drilling.

<GuideSidebar />

<GuideTitle title="Customize drill fields" />

Drilling is a great way to invite users to dig deeper into the data. For example, if you have a measure `Order Items Count` with a value of `10`, drilling lets you see more details on those 10 order items.

By default, when you drill, Omni will show the first 10 columns defined in your view. However, you can curate what columns are shown upon drilling in the workbook or the model IDE.

## Option 1: Workbook

1. In a workbook query tab, click <Icon icon="ellipsis-vertical" /> and select **Modeling > Edit**:
   <img alt="" />
2. Use the **Drill fields** section to add, remove, and reorder the drill fields:
   <img alt="" />

<Note>
  These changes will only exist for this workbook unless you [promote them to the shared model](/modeling/develop/promotion).
</Note>

## Option 2: Model IDE

To customize the available drill fields on a measure, use the [`drill_fields` parameter](/modeling/measures/parameters/drill-fields):

```yaml title="Measure with specific drill fields" theme={null}
count:
  drill_fields:
    [
      users.id,
      users.full_name,
      users.email,
      users.age,
      users.state,
      users.country,
      "users.created_at[date]"
    ]
  aggregate_type: count
```

You can also specify a default set of drill fields for all measures in a view with the [`default_drill_fields` view parameter](/modeling/views/parameters/default-drill-fields):

```yaml title="Default drill fields for order_items view" theme={null}
default_drill_fields:
  [
    id,
    user_id,
    users.full_name,
    inventory_items.product_name,
    sale_price,
    margin,
    "order_items.created_at[date]",
    status
  ]
```


# Point-in-time snapshots with parameters
Source: https://docs.omni.co/guides/workbooks/snapshots-with-parameters

How to use Mustache syntax to dynamically modify a query view

<GuideSidebar />

<GuideTitle title="Point-in-time snapshots with parameters" />

Sometimes you need to answer "as of" questions like *Which reservations were active last Tuesday?* or *What did our pipeline look like at quarter-end?* This guide shows how to build a parameterized query view that filters data to a specific point in time — and allows users to pick that date themselves.

## Requirements

To follow the steps in this guide, you'll need:

* A table with start and end date (or datetime) fields — for example, `check_in_date` and `check_out_date`
* Access to the model in your Omni instance

## How it works

A [query view](/modeling/query-views) is a SQL view defined in the model that can accept parameter values at query time. Instead of hardcoding a date in SQL, the selected date is injected directly into the `WHERE` clause. When the user changes the parameter, the query view regenerates automatically.

```sql The core pattern theme={null}
WHERE {{filters.your_view_name.snapshot_date.value}}::DATE
      >= your_table.start_date::DATE
  AND {{filters.your_view_name.snapshot_date.value}}::DATE
      < your_table.end_date::DATE
```

In the above example,  only the records that were "active" on the selected date will be returned, meaning they had started but not yet ended.

<Note>
  The `::DATE` cast strips time information from your timestamps. This prevents mismatches when your datetime fields include time components like `2024-02-15 14:30:00`
</Note>

## Set up the query view

<Steps>
  <Step title="Define the query view">
    1. In the workbook, create the query from a new SQL tab. Once the query is created, save as query view.  *Note: This particular pattern focuses on SQL based query views*
    2. Define a filter parameter for the snapshot date. The syntax for injecting parameter values follows this pattern:

       ```sql theme={null}
       {{ filters.<view_name>.<parameter_name>.value }}
       ```

       For example, if the view is named `snapshots` and the parameter is `snapshot_date`:

       ```sql theme={null}
       {{ filters.snapshots.snapshot_date.value }}::DATE
       ```

       <Warning>
         Verify that the filter parameter syntax is correct, including that the view name and parameter name match exactly. Incorrect syntax is the most common cause for issues.
       </Warning>
    3. Using the above-mentioned syntax, add the newly created parameter to the query view's SQL to inject the parameter's value.  When building the `WHERE` clause, use `<` (not `<=`) for the end date comparison. For example, a reservation that checks out on Feb 17th shouldn't appear in a Feb 17th snapshot.

       ```yaml snapshots.query.view {4,6,14,15,16,17} theme={null}
       sql: |
         SELECT *
         FROM your_schema.your_table
         WHERE {{filters.snapshots.snapshot_date.value}}::DATE
               >= your_table.start_date::DATE
           AND {{filters.snapshots.snapshot_date.value}}::DATE
               < your_table.end_date::DATE

       dimensions:
         reservation_date: {}
         check_in_datetime: {}
         check_out_datetime: {}
       ## etc...
       filters:
         snapshot_date:
           type: timestamp
           description: "The date to snapshot active records"
       ```

       You can also suggest from a list of timestamps using `suggestion_list` or optionally set a value as the default filter, for example:

       ```yaml theme={null}
       filters:
         snapshot_date:
           type: string
           suggestion_list:
             - value: 2024-02-01 00:00:00 -00:00
           default_filter:
             is: 2024-02-01 00:00:00 -00:00
       ```

       Which would then look like this in the workbook:

       <img alt="" />
  </Step>

  <Step title="Add the view to your topic">
    In the topic file, add the query view as a join (as shown) or include it as a standalone view so users can access it in workbooks:

    <Frame>
      <img alt="Image" />
    </Frame>
  </Step>

  <Step title="Test the snapshot">
    1. Open a workbook and navigate to your topic.
    2. Add the `snapshot_date` parameter filter to the query.
    3. Enter a date into the filter and run the query. You should see only the records that were active on that date:

       <img alt="" />

    If counts look off, check that you're using `count_distinct` on your ID field — without it, records that span multiple days can be counted more than once.
  </Step>
</Steps>

## Bonus: Populate the date picker with a list of dates

By default, the `snapshot_date` parameter accepts free-text input. If you want users to select from a list of valid dates instead, you can use `suggest_field` to populate the dropdown from a calendar view.

<Steps>
  <Step title="Create a calendar view">
    A calendar view is a query view that generates a list of dates. Most databases support a recursive CTE approach:

    <Note>
      The SQL syntax for recursive CTEs varies by database. Click the tab for your database to view the correct SQL.
    </Note>

    <CodeGroup>
      ```yaml Snowflake theme={null}
      # calendar.query.view
      sql: |
        WITH RECURSIVE dates AS (
          SELECT '2020-01-01'::TIMESTAMP AS date
          UNION ALL
          SELECT DATEADD(day, 1, date) AS date
          FROM dates
          WHERE date < '2029-12-31'::TIMESTAMP
        )
        SELECT date FROM dates

      dimensions:
        date:
          sql: ${date}
          type: date
      ```

      ```yaml DuckDB theme={null}
      # calendar.query.view
      sql: |
        WITH RECURSIVE rec_cte AS (
          SELECT '2020-01-01'::TIMESTAMP AS DATE
          UNION ALL
          SELECT DATE + INTERVAL '1 day'
          FROM rec_cte
          WHERE DATE < '2029-12-31'::TIMESTAMP
        )
        SELECT DATE FROM rec_cte

      dimensions:
        date:
          sql: '"DATE"'
          type: date
      ```

      ```yaml Google BigQuery theme={null}
      # calendar.query.view
      sql: |
        SELECT date
        FROM UNNEST(
          GENERATE_DATE_ARRAY('2020-01-01', '2029-12-31', INTERVAL 1 DAY)
        ) AS date

      dimensions:
        date:
          sql: "'date'"
          type: date
      ```

      ```yaml Postgres theme={null}
      # calendar.query.view
      sql: |
        SELECT generate_series::DATE AS DATE
        FROM generate_series(
          '2020-01-01'::TIMESTAMP,
          '2029-12-31'::TIMESTAMP,
          INTERVAL '1 day'
        )

      dimensions:
        date:
          sql: "'DATE'"
          type: date
      ```
    </CodeGroup>
  </Step>

  <Step title="Point parameter at the calendar">
    Update the snapshot parameter to pull suggestions from the calendar view:

    ```yaml theme={null}
    filters:
      snapshot_date:
        type: timestamp
        description: "The date to snapshot active records"
        suggest_field: calendar.date
    ```

    Now when users click the `snapshot_date` parameter, they'll see a dropdown populated with dates from your calendar view instead of a blank text field or suggestions from the specific `suggestion_list`.

    <img alt="" />
  </Step>
</Steps>


# Welcome to the Omni docs!
Source: https://docs.omni.co/index

Omni is the BI platform that combines a shared data model with the flexibility of SQL for governed, self-service analytics.

Omni is the business intelligence platform that combines the consistency of a shared data model with the freedom of SQL.

You don’t have to choose between a governed model and agile analysis. Focus on answering data questions, and Omni will build a data model as you go, allowing for reusability, governance, and performance optimization.

## New to Omni?

Start here! Use our onboarding video collection to get up and running with Omni.

<Columns>
  <Card title="Model developer onboarding" icon="circle-play" href="/getting-started/developers">
    Get started developing models and content in Omni
  </Card>

  <Card title="Viewer onboarding" icon="eye" href="/getting-started/viewers">
    Learn how to navigate Omni as a viewer of dashboards
  </Card>

  <Card title="Administration" icon="lock" href="/administration">
    Manage users, billing, authentication, and more in your Omni instance
  </Card>
</Columns>

## Develop with Omni

<Columns>
  <Card title="REST APIs" icon="code" href="/api">
    Programmatically interact with Omni via API
  </Card>

  <Card title="CLI" icon="terminal" href="/developers/cli">
    Interact with Omni APIs from the terminal
  </Card>

  <Card title="Agent skills" icon="robot" href="/developers/agent-skills">
    Bring Omni workflows into your agent environment
  </Card>

  <Card title="Embedded analytics" icon="chart-simple" href="/embed">
    Build AI-powered data applications with Omni
  </Card>
</Columns>

## Inspiration and releases

<Columns>
  <Card title="Demos" icon="wand-sparkles" href="/demos">
    Check out what we're building or experimenting with
  </Card>

  <Card title="Community" icon="discourse" href="https://community.omni.co">
    Search for Omni FAQs, how-to guides, and analytical patterns
  </Card>
</Columns>

<Columns>
  <Card title="Changelog" icon="chart-simple" href="/changelog">
    Keep up with the latest product releases
  </Card>

  <Card title="Example showcase" icon="wand-magic-sparkles" href="/showcase">
    Get inspired with examples of visualizations, dashboards, and more!
  </Card>
</Columns>


# GitHub AI integration
Source: https://docs.omni.co/integrations/ai/github

Extend the Omni Agent with code search and file retrieval from your GitHub repositories.

<Note>
  **Looking for git version control?** See the [git integration](/integrations/git) guides.
</Note>

Omni's GitHub AI integration extends the Omni Agent with the ability to search code and retrieve file contents from your GitHub repositories. This allows you to reference code, explore implementations, and incorporate technical context into your data analysis workflows. Using the GitHub integration, you could:

* **Reference implementation details** - Review how a data model is implemented in your application code while analyzing the corresponding data in Omni
* **Validate assumptions** - Check configuration files or schema definitions to verify how data is being collected or processed
* **Document findings** - Pull code snippets to include technical context in your analysis or documentation

For example, you could ask: *"Search for our user tracking code and then show me the distribution of user events from the analytics table"* - combining code exploration with data analysis in a single conversation.

## Common questions

<AccordionGroup>
  <Accordion title="Is this the same as the git integration?">
    No. The GitHub AI integration is different than the [git integration](/integrations/git).

    This integration allows the Omni Agent to use code and files in connected GitHub repositories as context, whereas the git integration allows you to implement git-based version control for model development.
  </Accordion>

  <Accordion title="What can the Omni Agent access?">
    Every Omni user that wants to use the GitHub AI integration must connect their GitHub account. This means that the Omni Agent will have the same permissions as the prompting user, accessing only the repositories they have access to.
  </Accordion>

  <Accordion title="How are search results and file contents processed?">
    Code search results and file contents are processed the same way as other AI features in Omni. Refer to [AI data privacy](/ai/security) for more information.
  </Accordion>
</AccordionGroup>

## Setting up the GitHub integration

### Requirements

To configure the GitHub integration for your Omni organization, you'll need:

* **Organization Admin** permissions in Omni
* Permissions in GitHub that allow you to create apps

<Steps>
  <Step title="Register a GitHub app">
    <Steps>
      <Step title="Define basic app info">
        1. In GitHub, navigate to your **Developer settings**.
           * **For a personal app**, [click here for a direct link](https://github.com/settings/apps/new).
           * **For an organization-owned app**, replace `<your-organization>` in the following URL to create a direct link:

             ```text wrap theme={null}
             https://github.com/organizations/<your-organization>/settings/apps/new
             ```
        2. Fill in the basic app info:
           * **GitHub App Name** - Enter a name for the app. For example, `Omni AI Integration`
           * **Description** - **Optional**. For example, "Enables the Omni Agent to search and read code from GitHub repositories"
           * **Homepage URL** - Enter the full URL of your Omni organization. For example, `https://your-org.omniapp.co`
      </Step>

      <Step title="Define user settings">
        In the **Identifying and authorizing users** section, define the fields as follows:

        * **Callback URL** - Copy and paste the following URL into this field:

          ```text theme={null}
          https://callbacks.omniapp.co/callback/github-ai
          ```
        * **Expire user authorization tokens** - Uncheck (disable) this option
        * **Request user authorization (OAuth) during installation** - Check (enable) this option
      </Step>

      <Step title="Disable webhooks">
        In the **Webhook** section, **uncheck the Active option**. Omni's integration doesn't use webhooks.
      </Step>

      <Step title="Define permissions">
        1. In **Repository permissions**, set:
           * **Contents** - Read-only
           * **Metadata** - Read-only
        2. In **Account permissions**, set **Email addresses** to **Read-only**.

        All other permissions can be left as **No access**.
      </Step>

      <Step title="Define app installation">
        In the **Where can this app be installed?** section, select an option based on your needs:

        * **Only on this account** — If the app is only for your organization
        * **Any account** — If multiple GitHub organizations need to connect
      </Step>

      <Step title="Complete the setup">
        Click **Register application** to complete the setup.
      </Step>
    </Steps>
  </Step>

  <Step title="Generate a client secret">
    After registering the app:

    1. On the app's settings page, scroll down to **Client secrets**.
    2. Click **Generate a new client secret**.
    3. Copy the secret immediately — it will only be shown once.
    4. Keep the **Client ID** handy, as you'll need it in the next step.
  </Step>

  <Step title="Enable and configure the Omni integration">
    1. In Omni, navigate to **Settings > Integrations**.
    2. Click the **AI Integrations** tab.
    3. Toggle the&#x20;**&#x20;integration** to **on**.
    4. You'll be prompted for your  credentials:

       * **OAuth Client ID** - Paste the **Client ID** from the  app
       * **OAuth Client Secret** - Paste the **Client secret** from the  app
    5. Click **Save**.
  </Step>
</Steps>

The integration will be available in your Omni organization. Each user must connect their individual accounts in their [user settings](/administration/users/your-account) to use the integration.

## Connecting your GitHub account

<Note>
  **This section applies to all users**, not only  admins. Every user who wants to use the  AI integration must connect their  account.
</Note>

After the  AI integration is enabled for your Omni organization, users will need to connect their individual  accounts to use the integration.

You can connect your account from the connector menu in the [Omni Agent](/ai/chat) (click the <Icon icon="circle-plus" /> button and then **Connect** next to ) or from your user settings:

<Steps>
  <Step>
    In Omni, click your user icon and then [**Manage account**](/administration/users/your-account).
  </Step>

  <Step>
    Scroll down to the **Connected Services** section.
  </Step>

  <Step>
    Next to the  integration, click **Connect**.
  </Step>

  <Step>
    Complete the authentication flow to connect your account.
  </Step>
</Steps>

## Using GitHub in the Omni Agent

<Note>
  Before users can use GitHub with the Omni Agent, they will need to connect their GitHub accounts in their [user settings](/administration/users/your-account).
</Note>

Once your GitHub account is connected, you can ask the Omni Agent to search for code or retrieve specific files from your repositories.

### Searching code

The Omni Agent can search across all repositories you have access to using GitHub's code search. To search for code, ask questions like:

* "Search my repositories for authentication logic"
* "Find examples of how we handle error logging in our codebase"
* "Look for database connection code in my projects"

The Agent returns matching snippets in the chat, including:

* Repository name and owner
* File path
* Code snippet with surrounding context
* Direct link to the file on GitHub

### Retrieving files

You can also ask the Omni Agent to retrieve the full contents of a specific file from a repository:

* "Show me the contents of config.yaml in my main repository"
* "Fetch the authentication middleware file from the backend project"
* "Get the README from the data-pipeline repository"

The Agent returns the full file contents inline, so you can review code, configuration, or documentation without leaving Omni.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to connect GitHub error">
    This error can be caused by:

    * An incorrect or rotated client secret
    * An incorrect callback URL
    * An expired authorization code. Codes are single-use and expire after 10 minutes)
  </Accordion>

  <Accordion title="GitHub tools not appearing in the Omni Agent">
    Tools will only become accessible after an individual user connects their GitHub account in their user settings. Verify that the user has [connected their GitHub account](#connect-user-account).
  </Accordion>

  <Accordion title="Private repositories not accessible">
    If a user can't see their private repositories:

    * The user may need to grant access to specific organizations when they complete the [authorization flow](#connect-user-account)
    * The GitHub App may need to be installed on the organization that owns the repositories
  </Accordion>
</AccordionGroup>

## Next steps

* [Explore the Omni Agent](/ai/chat) to learn more about conversational data analysis
* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve AI-generated query quality
* [Connect other AI integrations](/integrations/ai) to add external context
* [Review AI security practices](/ai/security) to understand how Omni processes data


# Google Calendar AI integration
Source: https://docs.omni.co/integrations/ai/google-calendar

Extend the Omni Agent with context from your Google Calendar, so you can reference events and meetings alongside your data analysis.

Omni's Google Calendar AI integration extends the Omni Agent with the ability to reference events, meetings, and schedules from your Google Calendar. This allows you to bring scheduling context into your data analysis workflows. Using the Google Calendar integration, you could:

* **Correlate events with metrics** - Review when a launch, campaign, or team offsite occurred while analyzing the corresponding trends in your data
* **Pull meeting context** - Reference the attendees, timing, or notes of a specific meeting while preparing analysis for a follow-up
* **Plan around your schedule** - Incorporate upcoming events into analysis that informs decisions or deliverables

For example, you could ask: *"Find the product launch event from last month and show me the change in signups that week"* - combining calendar context with data analysis in a single conversation.

## Common questions

<AccordionGroup>
  <Accordion title="What can the Omni Agent access?">
    Every Omni user that wants to use the Google Calendar AI integration must connect their Google account. This means that the Omni Agent will have the same permissions as the prompting user, accessing only the calendars and events they have access to.
  </Accordion>

  <Accordion title="How are calendar events processed?">
    Calendar events and meeting details are processed the same way as other AI features in Omni. Refer to [AI data privacy](/ai/security) for more information.
  </Accordion>
</AccordionGroup>

## Setting up the Google Calendar integration

See [Setting up Google AI integrations](/integrations/ai/google-setup) for help setting up the Google Calendar integration for your Omni organization.

After Google Calendar is set up, each user in your Omni organization must connect their individual accounts in their [user settings](/administration/users/your-account) to use the integration.

## Connecting your Google Calendar account

<Note>
  **This section applies to all users**, not only  admins. Every user who wants to use the  AI integration must connect their  account.
</Note>

After the  AI integration is enabled for your Omni organization, users will need to connect their individual  accounts to use the integration.

You can connect your account from the connector menu in the [Omni Agent](/ai/chat) (click the <Icon icon="circle-plus" /> button and then **Connect** next to ) or from your user settings:

<Steps>
  <Step>
    In Omni, click your user icon and then [**Manage account**](/administration/users/your-account).
  </Step>

  <Step>
    Scroll down to the **Connected Services** section.
  </Step>

  <Step>
    Next to the  integration, click **Connect**.
  </Step>

  <Step>
    Complete the authentication flow to connect your account.
  </Step>
</Steps>

## Using Google Calendar in the Omni Agent

<Note>
  Before users can use Google Calendar with the Omni Agent, they will need to connect their Google accounts in their [user settings](/administration/users/your-account).
</Note>

Once your Google Calendar account is connected, you can ask the Omni Agent to look up events and meetings from the calendars you have access to.

### Finding events

The Omni Agent can search your calendars for events based on time ranges, attendees, or keywords. To find events, ask questions like:

* "What meetings do I have about the Q3 roadmap this month?"
* "Find the product launch event from last month"
* "Show me all meetings with the finance team last week"

The Agent returns matching events in the chat, including:

* Event title
* Date and time
* Attendees
* Description or notes (if available)

### Referencing meeting context

You can also ask the Omni Agent to pull details about a specific event to pair with your analysis:

* "Get the details of tomorrow's planning meeting and summarize the agenda"
* "Show me who attended the pricing review last Thursday"

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to connect Google Calendar error">
    This error can be caused by:

    * An incorrect or rotated client secret
    * An incorrect callback URL
    * An expired authorization code. Codes are single-use and expire after a short period.
  </Accordion>

  <Accordion title="Google Calendar tools not appearing in the Omni Agent">
    Tools will only become accessible after an individual user connects their Google account in their user settings. Verify that the user has [connected their Google Calendar account](#connect-user-account).
  </Accordion>
</AccordionGroup>

## Next steps

* [Explore the Omni Agent](/ai/chat) to learn more about conversational data analysis
* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve AI-generated query quality
* [Connect other AI integrations](/integrations/ai) to add external context
* [Review AI security practices](/ai/security) to understand how Omni processes data


# Google Drive AI integration
Source: https://docs.omni.co/integrations/ai/google-drive

Extend the Omni Agent with search and file retrieval from your Google Drive, so you can reference documents and spreadsheets alongside your data analysis.

Omni's Google Drive AI integration extends the Omni Agent with the ability to search and retrieve files from Google Drive. This allows you to reference documents, spreadsheets, and other shared files alongside your data analysis workflows. Using the Google Drive integration, you could:

* **Reference source documents** - Pull context from a strategy doc, PRD, or spec while analyzing the corresponding data in Omni
* **Validate definitions** - Check a shared spreadsheet or glossary to verify how a metric is defined before using it in analysis
* **Incorporate supporting material** - Surface reports, notes, or documentation relevant to the question you're asking

For example, you could ask: *"Find our churn definition doc and then show me the churn rate by segment for last quarter"* - combining document context with data analysis in a single conversation.

## Common questions

<AccordionGroup>
  <Accordion title="What can the Omni Agent access?">
    Every Omni user that wants to use the Google Drive AI integration must connect their Google account. This means that the Omni Agent will have the same permissions as the prompting user, accessing only the files and folders they have access to.
  </Accordion>

  <Accordion title="How are file contents processed?">
    File search results and file contents are processed the same way as other AI features in Omni. Refer to [AI data privacy](/ai/security) for more information.
  </Accordion>
</AccordionGroup>

## Setting up the Google Drive integration

See [Setting up Google AI integrations](/integrations/ai/google-setup) for help setting up the Google Drive integration for your Omni organization.

After Google Drive is set up, each user in your Omni organization must connect their individual accounts in their [user settings](/administration/users/your-account) to use the integration.

## Connecting your Google Drive account

<Note>
  **This section applies to all users**, not only  admins. Every user who wants to use the  AI integration must connect their  account.
</Note>

After the  AI integration is enabled for your Omni organization, users will need to connect their individual  accounts to use the integration.

You can connect your account from the connector menu in the [Omni Agent](/ai/chat) (click the <Icon icon="circle-plus" /> button and then **Connect** next to ) or from your user settings:

<Steps>
  <Step>
    In Omni, click your user icon and then [**Manage account**](/administration/users/your-account).
  </Step>

  <Step>
    Scroll down to the **Connected Services** section.
  </Step>

  <Step>
    Next to the  integration, click **Connect**.
  </Step>

  <Step>
    Complete the authentication flow to connect your account.
  </Step>
</Steps>

## Using Google Drive in the Omni Agent

<Note>
  Before users can use Google Drive with the Omni Agent, they will need to connect their Google accounts in their [user settings](/administration/users/your-account).
</Note>

Once your Google Drive account is connected, you can ask the Omni Agent to search for files or retrieve the contents of specific documents from Drive.

### Searching files

The Omni Agent can search across the files you have access to in Google Drive. To search for files, ask questions like:

* "Find our Q3 planning doc in Drive"
* "Search Drive for spreadsheets about pricing experiments"
* "Look for the onboarding playbook shared by the marketing team"

The Agent returns matching files in the chat, including:

* File name
* Owner and last modified date
* A snippet or summary of the contents
* Direct link to the file in Google Drive

### Retrieving file contents

You can also ask the Omni Agent to retrieve the full contents of a specific file:

* "Show me the contents of the churn definition doc"
* "Fetch the pricing model spreadsheet and summarize the tiers"
* "Get the latest revision of the product strategy doc"

The Agent returns the file contents inline, so you can review documents and spreadsheets without leaving Omni.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to connect Google Drive error">
    This error can be caused by:

    * An incorrect or rotated client secret
    * An incorrect callback URL
    * An expired authorization code. Codes are single-use and expire after a short period.
  </Accordion>

  <Accordion title="Google Drive tools not appearing in the Omni Agent">
    Tools will only become accessible after an individual user connects their Google account in their user settings. Verify that the user has [connected their Google Drive account](#connect-user-account).
  </Accordion>

  <Accordion title="Files not appearing in search results">
    If a user can't find a file they expect to see:

    * The user may not have access to the file in Google Drive
    * The file may be in a shared drive that requires additional permissions
    * The user may need to re-authorize the integration to refresh their access scopes
  </Accordion>
</AccordionGroup>

## Next steps

* [Explore the Omni Agent](/ai/chat) to learn more about conversational data analysis
* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve AI-generated query quality
* [Connect other AI integrations](/integrations/ai) to add external context
* [Review AI security practices](/ai/security) to understand how Omni processes data


# Setting up Google AI integrations
Source: https://docs.omni.co/integrations/ai/google-setup

Create a shared Google Cloud project and OAuth client to enable Omni's Google Calendar and Google Drive AI integrations.

Omni's Google AI integrations — [Google Calendar](/integrations/ai/google-calendar) and [Google Drive](/integrations/ai/google-drive) — can share a single Google Cloud project and OAuth client. This guide walks through creating that project, enabling the APIs for the integrations you want to use, and generating the credentials you'll provide to Omni.

You only need to complete this setup once. If you want to enable an additional Google integration later, return to your existing project to enable its API and add its redirect URI rather than creating a new project.

## Requirements

To configure any of the Google AI integrations for your Omni organization, you'll need:

* **Organization Admin** permissions in Omni
* Permissions in Google Cloud that allow you to:
  * Create projects
  * Create OAuth apps

<Steps>
  <Step title="Create a Google Cloud project">
    1. Open the [New Project page](https://console.cloud.google.com/projectcreate) in the Google Cloud Console.
    2. Complete the project form fields.
    3. Click **Create** when finished.
  </Step>

  <Step title="Configure Google Auth Platform for the project">
    Google requires you to configure Google Auth Platform for the project before you can generate credentials.

    1. Open the project's [Auth overview page](https://console.cloud.google.com/auth/overview). If Google Auth Platform isn't configured for the project, this page will look like the following:

       <Frame>
         <img alt="Project with unconfigured Google Auth Platform" />
       </Frame>
    2. Click **Get started**.
    3. Fill in the form:
       * **App information** - Enter a **Name** and an **Email**
       * **Audience** - Select **Internal**
       * **Contact information** - Enter an email address
       * **Finish** - Check the **I agree** box
    4. Click **Create**.
  </Step>

  <Step title="Enable APIs for your project">
    <Note>
      Enable only the APIs for the integrations you plan to use. You can return later to enable more.
    </Note>

    1. Open [the API Library](https://console.developers.google.com/apis/library) in the Google API Console.
    2. Add the following APIs:
       * **Google Calendar** - Required to use the [Google Calendar AI integration](/integrations/ai/google-calendar)
       * **Google Drive** - Required to use the [Google Drive AI integration](/integrations/ai/google-drive)
       * **Google Sheets** - Required to search for and retrieve Sheets when using the [Google Drive AI integration](/integrations/ai/google-drive)
    3. After you locate an API, click it and then click the **Enable** button.
  </Step>

  <Step title="Create OAuth credentials">
    1. Open the project's [Clients page](https://console.cloud.google.com/auth/clients).
    2. Click **Create Client**.
    3. In the application type dropdown, select the **Web application**.
    4. Enter a **Name** for the client, such as `Omni AI integration`.
    5. In the **Authorized redirect URIs**, add the following URIs:

       * **Google Calendar** - `https://callbacks.omniapp.co/callback/google-calendar`
       * **Google Drive** - `https://callbacks.omniapp.co/callback/google-drive`
       * **Google Sheets** - `https://callbacks.omniapp.co/callback/google-sheets`

       <Note>
         Add only the redirect URIs for the integrations you plan to use.
       </Note>

       At this point, the page should look like the following:

       <Frame>
         <img alt="Completed OAuth client form" />
       </Frame>
    6. Click **Create**. After you create the client, a dialog like the following will display:
       <Frame>
         <img alt="Generated OAuth credentials" />
       </Frame>
    7. Keep this dialog open for now - you'll need it to complete the setup in Omni.
  </Step>

  <Step title="Enable and configure the Omni integrations">
    1. In Omni, navigate to **Settings > Integrations**.
    2. Click the **AI Integrations** tab.
    3. For each Google integration you want to connect, complete the following steps:
       1. Toggle the integration to **on**.
       2. When prompted, enter your credentials:
          * **OAuth Client ID** - Paste the **Client ID** from the Google OAuth client
          * **OAuth Client Secret** - Paste the **Client secret** from the Google OAuth client
       3. Click **Save**.
  </Step>
</Steps>

The integrations you enabled will now be available in your Omni organization. Each user must connect their individual accounts in their [user settings](/administration/users/your-account) to use the integrations.

## Next steps

* Learn how to use the [Google Calendar AI integration](/integrations/ai/google-calendar) to reference events and meetings in the Omni Agent
* Learn how to use the [Google Drive AI integration](/integrations/ai/google-drive) to search and retrieve files in the Omni Agent
* [Explore the Omni Agent](/ai/chat) to learn more about conversational data analysis
* [Connect other AI integrations](/integrations/ai) to add context from additional tools
* [Review AI security practices](/ai/security) to understand how Omni processes data


# Connecting AI integrations
Source: https://docs.omni.co/integrations/ai/index

Enable, disable, and remove AI integrations that extend the Omni Agent with context from Google Calendar, Google Drive, GitHub, Notion, and Slack.

AI integrations extend the Omni Agent with context from the tools your team already uses, allowing it to reference files, messages, calendar events, and code alongside your Omni data.

This page covers how to enable, disable, and remove AI integrations for your Omni organization. For setup instructions specific to each integration, see the [individual integration guides](#supported-integrations).

## Requirements

The permissions required to manage an AI integration depends on the integration:

* **Google Drive, Google Calendar, GitHub, and Notion** require **Organization Admin** permissions
* **Slack** is available to all users

## Supported integrations

<Columns>
  <Card title="Google Calendar" icon="calendar" href="/integrations/ai/google-calendar">
    Search events and meetings from Google Calendar
  </Card>

  <Card title="Google Drive" icon="google-drive" href="/integrations/ai/google-drive">
    Search and retrieve files from Google Drive
  </Card>

  <Card title="GitHub" icon="github" href="/integrations/ai/github">
    Search code and files from GitHub repositories
  </Card>

  <Card title="Notion" icon="notion" href="/integrations/ai/notion">
    Search and retrieve content from Notion workspaces
  </Card>

  <Card title="Slack" icon="slack" href="/integrations/ai/slack">
    Search messages, files, and threads in Slack
  </Card>
</Columns>

## Enabling AI integrations

<Note>
  This section applies to GitHub, Google Calendar, Google Drive, and Notion.

  Slack does not require any organization-level configuration. Users can connect their Slack accounts directly from their [user settings](/administration/users/your-account).
</Note>

Enabling an AI integration makes the integration available to users in your Omni organization. After the integration is enabled, users will need to connect their individual accounts to use the integration. Users can connect their accounts either from their [user settings](/administration/users/your-account) or directly from the connector menu in the [Omni Agent](/ai/chat).

<Steps>
  <Step>
    In Omni, navigate to **Settings > Integrations**.
  </Step>

  <Step>
    Click the **Integrations** tab.
  </Step>

  <Step>
    Locate the integration you want to connect and toggle it to **on**.
  </Step>

  <Step>
    Use the [guide for the integration](#supported-integrations) to learn how to generate the credentials to complete the setup. This step isn't required when configuring Notion.
  </Step>

  <Step>
    The integration will be available in your Omni organization. Users must connect their individual accounts in their [user settings](/administration/users/your-account) to use the integration.
  </Step>
</Steps>

## Disabling AI integrations

Disabling an AI integraiton will automatically disable it for all users in your Omni organization.

<Steps>
  <Step>
    In Omni, navigate to **Settings > Integrations**.
  </Step>

  <Step>
    Click the **Integrations** tab.
  </Step>

  <Step>
    Locate the integration you want to disconnect and toggle it to **off**.
  </Step>
</Steps>

## Removing AI integrations

Unlike disabling an AI integration, removing an integration from your Omni organization also removes all user connections. This means that users will need to re-authorize the integration again if it's re-enabled.

<Steps>
  <Step>
    In Omni, navigate to **Settings > Integrations**.
  </Step>

  <Step>
    Click the **Integrations** tab.
  </Step>

  <Step>
    Locate the integration you want to remove and click the <Icon icon="vertical-ellipsis" /> icon next to it.
  </Step>

  <Step>
    Click **Remove integration**.
  </Step>

  <Step>
    When prompted, click **Yes, remove integration**.
  </Step>
</Steps>


# Notion AI integration
Source: https://docs.omni.co/integrations/ai/notion

Extend the Omni Agent with the ability to search and retrieve content from your Notion workspace.

Omni's Notion AI integration extends the Omni Agent with the ability to search and retrieve content from your Notion workspace. This allows you to reference documentation, project plans, and knowledge base articles alongside your data analysis workflows. Using the Notion integration, you could:

* **Reference project documentation** - Pull context from project specs or requirements while analyzing related data in Omni
* **Access knowledge base articles** - Retrieve documented processes or definitions to inform your analysis
* **Review team notes** - Reference meeting notes or decisions documented in Notion while working with data

For example, you could ask: *"Find our data dictionary in Notion and then show me the user engagement metrics"* - combining documentation with data analysis in a single conversation.

## Common questions

<AccordionGroup>
  <Accordion title="What can the Omni Agent access?">
    Every Omni user that wants to use the Notion AI integration must connect their Notion account. This means that the Omni Agent will have the same permissions as the prompting user, accessing only the pages and databases they have access to.
  </Accordion>

  <Accordion title="How are Notion pages and content processed?">
    Notion content is processed the same way as other AI features in Omni. Refer to [AI data privacy](/ai/security) for more information.
  </Accordion>
</AccordionGroup>

## Setting up the Notion integration

<Note>
  **Organization Admin** permissions are required to configure the Notion integration.
</Note>

<Steps>
  <Step>
    In Omni, navigate to **Settings > Integrations**.
  </Step>

  <Step>
    Click the **AI Integrations** tab.
  </Step>

  <Step>
    Toggle the **Notion integration** to **on**.
  </Step>
</Steps>

The integration will be available in your Omni organization. Each user must connect their individual accounts in their [user settings](/administration/users/your-account) to use the integration.

## Connecting your Notion account

<Note>
  **This section applies to all users**, not only  admins. Every user who wants to use the  AI integration must connect their  account.
</Note>

After the  AI integration is enabled for your Omni organization, users will need to connect their individual  accounts to use the integration.

You can connect your account from the connector menu in the [Omni Agent](/ai/chat) (click the <Icon icon="circle-plus" /> button and then **Connect** next to ) or from your user settings:

<Steps>
  <Step>
    In Omni, click your user icon and then [**Manage account**](/administration/users/your-account).
  </Step>

  <Step>
    Scroll down to the **Connected Services** section.
  </Step>

  <Step>
    Next to the  integration, click **Connect**.
  </Step>

  <Step>
    Complete the authentication flow to connect your account.
  </Step>
</Steps>

## Using Notion in the Omni Agent

<Note>
  Before users can use Notion with the Omni Agent, they will need to connect their Notion accounts in their [user settings](/administration/users/your-account).
</Note>

Once your Notion account is connected, you can ask the Omni Agent to search for pages or retrieve content from your Notion workspace.

### Searching pages

The Omni Agent can search across all pages and databases you have access to in Notion. To search for content, ask questions like:

* "Search my Notion workspace for the project roadmap"
* "Find documentation about our data pipeline in Notion"
* "Look for meeting notes from last quarter in Notion"

### Retrieving content

You can also ask the Omni Agent to retrieve specific pages or content from your Notion workspace:

* "Show me the contents of our data dictionary page in Notion"
* "Get the project requirements from Notion"
* "Fetch the onboarding guide from our Notion workspace"

The Agent returns the page content inline, so you can review documentation and notes without leaving Omni.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to connect Notion error">
    This error can occur if:

    * The OAuth authorization was cancelled or interrupted
    * Your Notion session has expired
    * Network connectivity issues occurred during the connection process

    Try connecting again from your [user settings](/administration/users/your-account).
  </Accordion>

  <Accordion title="Notion tools not appearing in the Omni Agent">
    Tools will only become accessible after an individual user connects their Notion account in their user settings. Verify that the user has [connected their Notion account](#connect-user-account).
  </Accordion>

  <Accordion title="Cannot find specific pages">
    If you can't find specific pages:

    * Verify you have access to the page in Notion
    * Check that the page is not in a private workspace you don't have access to
    * Ensure the page has been shared with you in Notion
  </Accordion>
</AccordionGroup>

## Next steps

* [Explore the Omni Agent](/ai/chat) to learn more about conversational data analysis
* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve AI-generated query quality
* [Connect other AI integrations](/integrations/ai) to add external context
* [Review AI security practices](/ai/security) to understand how Omni processes data


# Slack AI integration
Source: https://docs.omni.co/integrations/ai/slack

Extend the Omni Agent with Slack messages, threads, and files so you can reference team discussions and shared documents alongside your data analysis.

<Note>
  **Looking to use Omni in Slack?** See the [Omni Slack Agent](/integrations/omni-slack-agent) guide.
</Note>

Omni's Slack AI integration extends the Omni Agent with the ability to search messages, threads, and files across your Slack workspace. The integration is available to all users—connect your Slack account from your [user settings](/administration/users/your-account) to start using it with the Omni Agent. Using the Slack integration, you could:

* **Pull context from discussions** - Reference past conversations about a metric or definition while analyzing the corresponding data in Omni
* **Cross-check decisions** - Find the thread where a KPI target or reporting change was agreed on and incorporate it into your analysis
* **Locate shared files** - Surface spreadsheets, screenshots, or documents that were shared in channels relevant to your question

For example, you could ask: *"Find the thread where we discussed last quarter's churn target and compare it to this quarter's actuals"* - combining team context with data analysis in a single conversation.

## Common questions

<AccordionGroup>
  <Accordion title="What can the Omni Agent access?">
    The Slack AI integration is available to all users without requiring organization-level configuration. When you connect your Slack account, the Omni Agent will have the same permissions as you, accessing only the channels, messages, and files you have access to in Slack.
  </Accordion>

  <Accordion title="What Slack scopes does the integration need?">
    When you connect your Slack account, Omni will request the following scopes:

    | Scope              | Purpose                                                                |
    | ------------------ | ---------------------------------------------------------------------- |
    | `search:read`      | Search messages and files                                              |
    | `users:read`       | Get user info for metadata                                             |
    | `team:read`        | Get team info for workspace domain (used in permalinks)                |
    | `channels:read`    | Read channel info                                                      |
    | `channels:history` | Read message history in public channels (for `conversations.replies`)  |
    | `groups:read`      | Read private channel info (if user has access)                         |
    | `groups:history`   | Read message history in private channels (for `conversations.replies`) |
  </Accordion>

  <Accordion title="How are messages and file contents processed?">
    Slack messages, threads, and file contents are processed the same way as other AI features in Omni. Refer to [AI data privacy](/ai/security) for more information.
  </Accordion>

  <Accordion title="Is this the same as the Omni Slack Agent?">
    No. The Slack AI integration is different than the [Omni Slack Agent](/integrations/omni-slack-agent).

    This integration allows the Omni Agent to use Slack messages, files, and threads as context, whereas the Omni Slack Agent enables your team to ask questions about your Omni data from within Slack.
  </Accordion>
</AccordionGroup>

## Connecting your Slack account

You can connect your Slack account from the connector menu in the [Omni Agent](/ai/chat) (click the <Icon icon="circle-plus" /> button and then **Connect** next to Slack) or from your user settings:

<Steps>
  <Step>
    In Omni, click your user icon and then [**Manage account**](/administration/users/your-account).
  </Step>

  <Step>
    Scroll down to the **Connected Services** section.
  </Step>

  <Step>
    Next to the **Slack** integration, click **Connect**.
  </Step>

  <Step>
    Complete the authentication flow to connect your account.
  </Step>
</Steps>

## Using Slack in the Omni Agent

Once you've [connected your Slack account](#connecting-your-slack-account), you can ask the Omni Agent to search messages, threads, and files across the channels you have access to.

### Searching messages

The Omni Agent can search across public channels and the private channels and DMs you're a member of. To search messages, ask questions like:

* "Find messages in #analytics about the new attribution model"
* "Search Slack for discussions about Q3 revenue targets"
* "Look for messages from our finance team about budget reporting"

The Omni Agent will return matching messages in the chat.

### Reading threads

You can also ask the Omni Agent to pull the full contents of a specific thread for deeper context:

* "Show me the thread where we finalized the churn metric definition"
* "Get the discussion from last week's incident thread in #engineering"

The Omni Agent returns the thread contents inline, so you can review decisions and context without leaving Omni.

### Finding files

The Omni Agent can surface files shared in Slack channels you have access to:

* "Find the pricing spreadsheet that was shared in #sales last month"
* "Look for the architecture diagram shared in #platform"

## Next steps

* [Explore the Omni Agent](/ai/chat) to learn more about conversational data analysis
* [Optimize your models for AI](/modeling/develop/ai-optimization) to improve AI-generated query quality
* [Review AI security practices](/ai/security) to understand how Omni processes data


# Debugging dbt sync issues
Source: https://docs.omni.co/integrations/dbt/debugging-sync-issues

Find and resolve dbt sync issues using the validation issues surfaced in Omni's dbt IDE.

Each time Omni syncs your dbt project, it translates your dbt models, semantic models, dimensions, measures, and metrics into your Omni semantic model. Anything Omni can't translate — a model it can't match to a view, an unsupported dbt feature, a Jinja expression it can't render — is recorded as an issue and surfaced in the dbt IDE.

## Requirements

To follow the steps in this guide, you'll need:

* An Omni connection with a [configured dbt integration](/integrations/dbt/setup)
* **Querier**, **Modeler**, or **Connection Admin** permissions to access the model. To ignore issues, **Modeler** or **Connection Admin** permissions are required.

## About dbt sync issues

Issues never block a sync. Omni imports everything it can translate and records the rest, so a warning on one metric doesn't stop the models around it from importing. An issue persists until you [fix the underlying problem in dbt](#troubleshoot) and re-sync, or [ignore](#ignore) it.

When a sync identifies an issue, the <DbtIdeIcon /> icon in the model IDE will display an indicator:

<Frame>
  <img alt="dbt IDE icon in the model IDE showing a red issue indicator" />
</Frame>

When there are issues, clicking the <DbtIdeIcon /> icon will clear the indicator and open the **Sync** page. The top of the page displays a summary of the most recent sync and a summary of any issues found:

<Frame>
  <img alt="Sync page summary of the issues found in the most recent dbt sync" />
</Frame>

The summary breaks the issues out by level:

| Level                               | Description                                                                                                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <DbtNoteIssueIcon /> **Note**       | Informational. Worth a look, but nothing is missing or broken.                                                                                                                        |
| <DbtWarningIssueIcon /> **Warning** | Omni couldn't translate part of your dbt project. The entity is skipped, but everything around it still imports.                                                                      |
| <DbtErrorIssueIcon /> **Error**     | A dbt object wasn't matched to an Omni view. The model exists in your dbt project, but Omni can't find the table or view it should have been built as, so it isn't queryable in Omni. |

Along with the **Sync** page summary, Omni flags files and directories containing issues in the file list. See [Troubleshooting dbt sync issues](#troubleshoot) for more information.

Refer to the [dbt sync issue reference](#issue-reference) for potential issues and how to resolve them.

## Troubleshooting dbt sync issues

The dbt IDE is read-only, so resolving an issue is a round trip: diagnose it in Omni, fix it in your dbt project, then re-sync in Omni. To edit dbt models from Omni rather than in your project, see [Working with dbt models](/integrations/dbt/models).

<Steps>
  <Step title="Open the flagged file">
    1. In Omni, open the model IDE and click the **dbt** icon in the sidebar.
    2. In the file list, locate a file with an issue indicator. Each flagged file displays an icon and count for every issue type it contains, and collapsed directories roll up the counts of everything inside them, so you can find affected files without expanding the whole tree.

       <Frame>
         <img alt="dbt IDE file list with directories and files flagged by issue type icons and counts" />
       </Frame>
    3. Click the file to open it.
  </Step>

  <Step title="Review the issue">
    The file's issues are listed in the **dbt sync issues** panel below the editor:

    <Frame>
      <img alt="dbt file with a Warning issue, showing the highlighted problem line and the issues panel at the bottom of the file" />
    </Frame>

    Click an issue to jump to the line that caused it or <TroubleshootWrenchIcon /> **Troubleshoot** for details. Alternatively, you can click [<Icon icon="eye-slash" /> **Ignore**](#ignore) to suppress it.

    <Note>
      Issues in dbt model files only display in the **dbt sync issues** panel. This is because dbt models are reported against `.sql` files, which don't have lines to resolve.
    </Note>
  </Step>

  <Step title="Fix the issue in dbt">
    Make the correction in your dbt project and push it.
  </Step>

  <Step title="Re-sync Omni">
    In Omni, click **Sync now** on the **Sync** page to pick up the change. Resolved issues will be removed on the next sync.
  </Step>
</Steps>

## Ignoring dbt sync issues

<Note>
  **Modeler** or **Connection Admin** permissions are required to ignore issues, as ignoring an issue edits the model.
</Note>

Some issues aren't worth acting on, such as an unsupported feature you don't plan to remove or duplicate measures you've already hidden. Ignoring an issue suppresses the notifications and indicators in the dbt IDE, but it doesn't fix the underlying issue.

You can ignore:

* **One issue in a file** by clicking <Icon icon="eye-slash" /> **Ignore** on the issue in the **dbt sync issues** panel.
* **All issues in a file** by right-clicking on the file in the file list and selecting **Ignore all issues in this file**.
* **All issues in a directory** by right-clicking on the directory in the file list and selecting **Ignore all issues in this directory**. Suppression will be applied to every file and subdirectory inside it.

## dbt sync issue reference

<AccordionGroup>
  <Accordion title="Note: Import resulted in duplicate measures" icon={<DbtNoteIssueIcon />}>
    * **What it means** - Your dbt metric definitions produced more than one copy of the same measure.
    * **How to fix it** - Hide all but one of the duplicate measures within the view, then ignore the issue.
  </Accordion>

  <Accordion title="Warning: Unsupported feature" icon={<DbtWarningIssueIcon />}>
    * **What it means** - Omni doesn't support this dbt feature yet, so the entity was skipped during generation.
    * **How to fix it** - Remove or rework the use of the feature in your dbt project.
  </Accordion>

  <Accordion title="Warning: Circular metric dependency" icon={<DbtWarningIssueIcon />}>
    * **What it means** - The metric depends on itself through a chain of other metrics, so it can't be resolved.
    * **How to fix it** - In your dbt project, trace the metrics it references and remove or redefine one of the dependencies.
  </Accordion>

  <Accordion title="Warning: Dependency not found" icon={<DbtWarningIssueIcon />}>
    * **What it means** - The entity references something Omni couldn't find.
    * **How to fix it** - Check that the dependency exists and is spelled correctly, and that the file defining it is part of the dbt project.
  </Accordion>

  <Accordion title="Warning: Dependency not translated" icon={<DbtWarningIssueIcon />}>
    * **What it means** - The entity depends on something that itself failed to translate.
    * **How to fix it** - Fix the issue reported on the dependency first. This issue should clear once the issue on the dependency is resolved.
  </Accordion>

  <Accordion title="Warning: Derived metric unknown aliases" icon={<DbtWarningIssueIcon />}>
    * **What it means** - The derived metric references aliases that aren't defined.
    * **How to fix it** - Add the missing inputs to the metric, or correct the alias names so they match its declared inputs.
  </Accordion>

  <Accordion title="Warning: Conflicts with a column in your warehouse of the same name" icon={<DbtWarningIssueIcon />}>
    * **What it means** - The dimension has the same name as a column already present in the warehouse table.
    * **How to fix it** - Rename the dimension so it no longer collides with the underlying column.
  </Accordion>

  <Accordion title="Warning: SQL cannot be parsed" icon={<DbtWarningIssueIcon />}>
    * **What it means** - Omni couldn't parse the SQL for this entity.
    * **How to fix it** - Look for dialect-specific syntax or constructs Omni doesn't understand, simplify the expression, and re-sync.
  </Accordion>

  <Accordion title="Warning: Jinja error" icon={<DbtWarningIssueIcon />}>
    * **What it means** - A Jinja expression couldn't be rendered.
    * **How to fix it** - Omni renders only a subset of dbt's Jinja. Review the reported Jinja and avoid macros and context Omni can't resolve.
  </Accordion>

  <Accordion title="Warning: Ratio metric with filters and non-simple dependency" icon={<DbtWarningIssueIcon />}>
    * **What it means** - Ratio metrics with filters require simple metric inputs, and one of this metric's inputs isn't one.
    * **How to fix it** - Point the input at a simple metric, or remove the filters from the ratio metric.
  </Accordion>

  <Accordion title="Error: This dbt model was not matched to an Omni view" icon={<DbtErrorIssueIcon />}>
    * **What it means** - Based on your dbt manifest, Omni expected a view built at a specific database, schema, and alias, and couldn't find it.

    * **How to fix it** - Follow these steps to identify and resolve the issue:

      <Steps>
        <Step title="Get the database location from the dbt sync issues panel">
          In the file in the dbt IDE, click <TroubleshootWrenchIcon /> **Troubleshoot** on the issue in the **dbt sync issues** panel. The popover contains the name of the database, schema, and table Omni expected based on your dbt manifest, along with the Omni view name it looked for.

          If that location is wrong, your [dbt environment settings](/integrations/dbt/environments) don't match your dbt profile or dbt Cloud environment. If the location is right, the view is missing or invisible to Omni.
        </Step>

        <Step title="Verify visibility in Omni">
          * **Check UI visibility.** Look for the table in the **All views and fields** section of a workbook. If it's missing, it hasn't been ingested into the Omni model layer yet.
          * **Try querying the table with SQL**. Use its fully qualified name (FQN), for example `DATABASE.SCHEMA.TABLE`.
            In a workbook, open the [SQL editor](/analyze-explore/sql) and run a query:
            * If the FQN works but the table is missing from the model IDE, it is likely a metadata or permission issue
            * If the FQN fails with `"Object does not exist"`, Omni cannot access the table
        </Step>

        <Step title="Check the dbt environment settings">
          Compare the database, schema, and alias reported in the **Troubleshoot** popover against the environment's configuration in Omni. The **Default schema** and **Target name** must match the dbt profile or dbt Cloud environment the models were built with. See [Configuring dbt environments](/integrations/dbt/environments) for what each setting controls.
        </Step>

        <Step title="Check database permissions">
          For Omni to pull in dbt schemas, the database user Omni connects with must have permissions to access and query those schemas. Use the [setup guide for your database](/connect-data/setup/index) to verify that the database user has the required permissions, including grants covering your dbt schemas - existing objects and, where supported, future objects so new models are accessible after each build.
        </Step>

        <Step title="Check connection settings">
          Verify that the following settings are correctly defined for the underlying connection:

          * **Included schemas** - Check your [model file](/modeling/models) or connection settings for [`included_schemas`](/modeling/models/included-schemas).

            If you filtered your connection (e.g., `included_schemas: [omni_dbt]`), Omni will hide all other schemas, including the development schemas.
          * **Other databases** - Ensure the database containing your dev schema is listed in the **Other databases** section of the connection settings. It must be listed here if it differs from the primary connection database.
          * **Branch refresh** - If testing in a branch, verify that [Branch-based schema refresh](/modeling/develop/schema-refreshes) is enabled. Updates will not sync to Omni otherwise.
        </Step>

        <Step title="Refresh the schema">
          If permissions are correct but models are still missing, [refresh the schema](/modeling/develop/schema-refreshes). You can scope this to your specific dbt dev schema to save time.

          On a dbt-integrated connection, a schema refresh also re-syncs dbt — pulling the latest Git manifest, recompiling the project, and re-running the checks — so there's no need to sync separately afterward. If nothing has changed in the warehouse and you only need to pick up dbt metadata, a [dbt sync on its own](/integrations/dbt/syncing-dbt#sync-only) is faster.
        </Step>

        <Step title="Check your dbt project's configuration">
          Lastly, in your dbt project:

          * **Define environment Variables**. If your project uses variables like `DBT_CLOUD_ENVIRONMENT_TYPE` to name schemas, ensure these are defined in Omni's [dbt environment settings](/integrations/dbt/environments).
          * **Run `dbt clone`.** Running `dbt clone` helps sync your dev environment with production, but remember that cloned objects still require the permissions mentioned in [step 4](#check-database-permissions) if future grants aren't active.

            If you're running partial builds, consider enabling deferral on the environment instead — see [Using virtual schemas with partial dbt builds](/integrations/dbt/virtual-schemas#partial-dbt-builds).
        </Step>
      </Steps>
  </Accordion>
</AccordionGroup>

## Common questions

Click the following headings for answers to common questions, including problems that show up in your model rather than as flagged issues in the dbt IDE.

<AccordionGroup>
  <Accordion title="What permissions does Omni need to access dbt development schemas?">
    Omni needs read access to all databases and schemas used by your dbt project, including development schemas. See your database's [connection setup guide](/connect-data/setup/index) to verify the required permissions. If you're using dbt, make sure those grants also cover your dbt schemas — and where your database supports it, use future grants so new models are accessible after each build.
  </Accordion>

  <Accordion title="How can I see which dbt models are pulled into Omni as schemas?">
    Open the dbt IDE and click **Sync** at the top of the file list. Any dbt object that isn't matched to an Omni view is counted in the **Sync** page and the files responsible are flagged in the file list.
  </Accordion>

  <Accordion title="Why don't my ephemeral models appear in Omni?">
    Models materialized as `ephemeral` are compiled as CTEs and never exist as physical tables, so Omni skips them when matching dbt models to views. They also won't raise an issue for being unmatched.
  </Accordion>

  <Accordion title="Why are views missing from my model?">
    This often happens if views are flagged with an `ignored: true` parameter. Omni's sync may interpret complex views — especially those with dynamic logic like Jinja loops — as "not in use" and automatically hide them to keep the model clean.

    To fix this:

    1. Navigate to the model IDE.
    2. Toggle the view mode to **Model**. The dropdown may default to **Combined**, so be sure to update it if needed.
    3. Navigate to the file for the view and check for an `ignored: true` parameter.
    4. Remove the parameter and promote the changes to the shared model.
  </Accordion>
</AccordionGroup>

## Related

* [Set up the dbt integration](/integrations/dbt/setup)
* [Configuring dbt environments](/integrations/dbt/environments)
* [Syncing dbt](/integrations/dbt/syncing-dbt)
* [Work with dbt models in Omni](/integrations/dbt/models)
* [Schema refreshes](/modeling/develop/schema-refreshes)


# Configuring dbt environments in Omni
Source: https://docs.omni.co/integrations/dbt/environments

Mirror your dbt profiles.yml or dbt Cloud environments in Omni so Omni runs dbt commands the way your project expects.

A dbt environment tells Omni how to run dbt commands against your project — which schema your models are built into, which database they live in, and what `target` your project expects.

A production environment is created automatically when you set up the dbt integration. Additional environments, typically one per developer, let you point Omni at development builds and swap between them from an Omni branch.

## How it works

Every time Omni syncs, it compiles your dbt project to build a manifest. Just like a local `dbt run`, that compilation needs to know where your models are built. An Omni environment supplies that information by mirroring an entry from your dbt configuration:

* **dbt Core** — One output block under a profile in your `profiles.yml`
* **dbt Cloud** — One environment, or one developer's credentials

The closer an Omni environment mirrors its dbt counterpart, the more accurately Omni resolves where your models actually live. When the two drift apart, Omni compiles a manifest pointing at the wrong place, and models come back unmatched — see [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) for more information.

### Environment ownership

Every dbt environment is either **personal**, meaning it belongs to a single user, or **shared**, meaning it doesn't have an owner. Ownership is controlled by the environment's [**Belongs to** setting](#param-belongs-to).

Ownership determines who can manage (create, edit, delete) the environment:

| Environment               | Belongs to   | Who can manage                         |
| ------------------------- | ------------ | -------------------------------------- |
| Personal (yours)          | You          | You; Organization Admins               |
| Personal (another user's) | Another user | The other user; Organization Admins    |
| Shared                    | No one       | Connection Admins; Organization Admins |

Anyone who can access the model IDE can create an environment for themselves. Creating a shared environment requires Connection Admin or Organization Admin permissions; only Organization Admins can reassign ownership of an environment.

The production environment is always shared and cannot be assigned an owner.

## Requirements

To follow the steps in this guide, you'll need:

* An Omni connection with a [configured dbt integration](/integrations/dbt/setup)
* **Restricted Querier** permissions or higher on the shared model. If you're using [custom roles](/administration/users/custom-roles), you need the **Use IDE** permission.

## Managing dbt environments

dbt environments can be managed in the Omni UI using the dbt IDE, the dbt environment APIs, or the Omni CLI.

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. In Omni, click **Develop** in the main [sidebar](/administration/settings/sidebar).
    2. If your organization has more than one model, click the model you want to work with in the list to open the model IDE. If you have only one model, Omni opens it automatically.
    3. In the model IDE, click the **dbt** icon in the sidebar.
    4. Click **Sync** at the top of the file list.

    This opens the **Sync** page:

    <Frame>
      <img alt="Highlighted Environments section in the dbt IDE, accessed by clicking Sync in the IDE's file list" />
    </Frame>
  </Tab>

  <Tab title="API" icon="cloud">
    Use the dbt environment APIs to [create](/api/dbt/create-dbt-environment), [update](/api/dbt/update-dbt-environment), [list](/api/dbt/list-dbt-environments), and [delete](/api/dbt/delete-dbt-environment) dbt environments.
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the `omni connections dbt-environments-create`, `omni connections dbt-environments-update`, and `omni connections dbt-environments-delete` [commands](/developers/cli/commands/connections) to create, update, and delete dbt environments using the CLI.
  </Tab>
</Tabs>

## Creating dbt environments

### Creating personal environments

<Note>
  All users who want to preview their dbt changes in Omni need a dbt environment. A single personal environment only applies to the user who owns it.
</Note>

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    To create a personal dbt environment in the Omni UI:

    1. [Open the **Sync** page](#manage-environments) in the dbt IDE.
    2. In the **Environments** section, click **Add Environment**.
    3. Define the [environment settings](#configure-settings), setting **Belongs to** to you or another user, if you're an Organization Admin.
    4. **Optional**: Add your dbt project's [environment variables](#add-variables).
    5. Click **Save** to create the environment.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Create a dbt environment API](/api/dbt/create-dbt-environment) to create a new personal dbt environment.

    To create a personal environment for:

    * **Yourself** - Set the `ownerId` to your Omni user ID. Get your ID with the [Who Am I API](/api/who-am-i/get-current-identity-and-permissions).
    * **Another user** - Set the `ownerId` to the other user's Omni user ID. This requires **Organization Admin** permissions. Get the user's ID with the [List users API](/api/users/list-users).

    ```http expandable theme={null}
    curl --request POST \
      --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "name": "Blobby's Environment",
      "ownerId": "550e8400-e29b-41d4-a716-446655440000",
      "targetSchema": "blob_analytics",
      "targetDatabase": "blobsrus",
      "variables": [
        {
          "name": "DBT_TARGET",
          "value": "production",
          "isSecret": false
        },
        {
          "name": "DBT_API_KEY",
          "value": "sk-...",
          "isSecret": true
        }
      ]
    }
    '
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [Omni CLI](/developers/cli) `omni connections dbt-environments-create` command to create a new personal environment.

    To create a personal environment for:

    * **Yourself** - Set the `ownerId` to your Omni user ID. Get your ID by running `omni whoami whoami` and locating the `user.id` value.
    * **Another user** - Set the `ownerId` to the other user's Omni user ID. This requires **Organization Admin** permissions. Get the user's ID by running `omni scim users-list` and locating the user in the response.

    ```bash theme={null}
    omni connections dbt-environments-create <connection-id> --body '
    {
      "name": "Blobby's Environment",
      "ownerId": "550e8400-e29b-41d4-a716-446655440000",
      "targetSchema": "blob_analytics",
      "targetDatabase": "blobsrus",
      "variables": [
        {
          "name": "DBT_TARGET",
          "value": "production",
          "isSecret": false
        },
        {
          "name": "DBT_API_KEY",
          "value": "sk-...",
          "isSecret": true
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

### Creating shared environments

<Note>
  **Connection Admin** or **Organization Admin** permissions are required to create shared environments. See [Environment ownership](#ownership) for more information.
</Note>

A production environment is created automatically when you set up the dbt integration, so you only need to [configure its settings](#configure-settings) and add [environment variables](#manage-variables) to finish setting it up.

Use these instructions to create additional shared environments.

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    To create a shared dbt environment in the Omni UI:

    1. [Open the **Sync** page](#manage-environments) in the dbt IDE.
    2. In the **Environments** section, click **Add Environment**.
    3. Define the [environment settings](#configure-settings), setting **Belongs to** to **No one (shared)**.
    4. **Optional**: Add your dbt project's [environment variables](#add-variables).
    5. Click **Save** to create the environment.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Create a dbt environment API](/api/dbt/create-dbt-environment) to create a new shared dbt environment, omitting the `ownerId` from the request body:

    ```http expandable theme={null}
    curl --request POST \
      --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "name": "Shared environment",
      "targetSchema": "blob_analytics",
      "targetDatabase": "blobsrus",
      "variables": [
        {
          "name": "DBT_TARGET",
          "value": "production",
          "isSecret": false
        },
        {
          "name": "DBT_API_KEY",
          "value": "sk-...",
          "isSecret": true
        }
      ]
    }
    '
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [Omni CLI](/developers/cli) `omni connections dbt-environments-create` command to create a new shared environment.

    Omit the `ownerId` property from the request body to create the shared environment:

    ```bash theme={null}
    omni connections dbt-environments-create <connection-id> --body '
    {
      "name": "Shared environment",
      "targetSchema": "blob_analytics",
      "targetDatabase": "blobsrus",
      "variables": [
        {
          "name": "DBT_TARGET",
          "value": "production",
          "isSecret": false
        },
        {
          "name": "DBT_API_KEY",
          "value": "sk-...",
          "isSecret": true
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

## Editing dbt environments

<Note>
  See [Environment ownership](#ownership) for the permissions required to edit environments.
</Note>

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    To update an existing environment:

    1. In the [**Sync** page of the dbt IDE](#manage-environments), click the <Icon icon="ellipsis-vertical" /> icon next to the environment.
    2. Click **Edit**.
    3. Update the environment's [settings](#configure-settings), [variables](#manage-variables), or both.
    4. Click **Save**.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update a dbt environment API](/api/dbt/update-dbt-environment) to update an existing dbt environment, providing the `environmentId` as a path parameter. Only include the fields you want to update in the request body:

    ```http theme={null}
    curl --request PUT \
      --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments/{environmentId} \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "name": "Blobby Development",
      "targetSchema": "dev_schema"
    }
    '
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [Omni CLI](/developers/cli) `omni connections dbt-environments-update` command to update an existing dbt environment. Only include the fields you want to update in the `--body`:

    ```bash theme={null}
    omni connections dbt-environments-update <connection-id> <environment-id> --body '
    {
      "name": "Blobby Development",
      "targetSchema": "dev_schema"
    }
    '
    ```
  </Tab>
</Tabs>

### Assigning dbt environment ownership

<Note>
  **Organization Admin** permissions are required to assign environment ownership.

  The default production environment cannot be assigned an owner.
</Note>

Organization Admins can assign [ownership of an environment](#ownership) during the initial setup, or update it after the environment is created:

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. In the [**Sync** page of the dbt IDE](#manage-environments), click the <Icon icon="ellipsis-vertical" /> icon next to the environment.
    2. Click **Edit**.
    3. Set **Belongs to** to the user that should own the environment.
    4. Click **Save**.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update a dbt environment API](/api/dbt/update-dbt-environment) to change the owner of an existing dbt environment. Set the `ownerId` to the ID of the user who should own the environment:

    ```http theme={null}
    curl --request PUT \
      --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments/{environmentId} \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "ownerId": "550e8400-e29b-41d4-a716-446655440000"
    }
    '
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [Omni CLI](/developers/cli) `omni connections dbt-environments-update` command to change the owner of an existing dbt environment. Set the `ownerId` to the ID of the user who should own the environment:

    ```bash theme={null}
    omni connections dbt-environments-update <connection-id> <environment-id> --body '
    {
      "ownerId": "550e8400-e29b-41d4-a716-446655440000"
    }
    '
    ```
  </Tab>
</Tabs>

## Configuring dbt environment settings

A dbt environment's settings mirror one entry from your dbt configuration. Copy the values directly from your `profiles.yml` (dbt Core) or dbt Cloud environment credentials to ensure Omni runs dbt commands the way your project expects.

For example, take this `profiles.yml` entry for a developer working locally with dbt Core:

```yaml theme={null}
my_project:
  target: dev               # Target Name
  outputs:
    dev:
      type: snowflake
      database: analytics   # Default Database
      schema: dbt_blobby    # Default Schema
      role: transformer     # Target Role
```

The matching Omni dbt environment would be:

| Omni setting     | Value         |
| ---------------- | ------------- |
| Name             | `Blobby Dev`  |
| Default Schema   | `dbt_blobby`  |
| Default Database | `analytics`   |
| Target Name      | `dev`         |
| Target Role      | `transformer` |
| Belongs to       | Blobby        |

Note that **Name** and **Belongs to** don't come from your dbt configuration - they're the environment's display label and [owner](#ownership), which are set in Omni.

<Note>
  **Using dbt Cloud?** Copy the values from **Profile > Credentials > \[your project] > Development credentials**, where **Schema** maps to **Default Schema** and **Target name** maps to **Target Name**.
</Note>

### dbt environment settings reference

<ParamField>
  A user-friendly label displayed in the UI. This is what users pick from when switching environments, so name it after what it points at — `Production`, `Staging`, or `Blobby Dev`.
</ParamField>

<ParamField>
  The user that owns the environment. Personal environments can only be edited by their owner or by Organization Admins. See [Environment ownership](#ownership) for more information.

  Choose **No one (shared)** for environments like production or staging that any Connection Admin should be able to edit. The production environment is always shared.
</ParamField>

<ParamField>
  Defers unbuilt dbt models in this environment to the production environment's builds, so partial builds don't make the rest of your models disappear. Only available on non-production environments.

  See [Using virtual schemas with partial dbt builds](/integrations/dbt/virtual-schemas#partial-dbt-builds) for more information.
</ParamField>

<ParamField>
  The schema where dbt models are built when the models don't have a custom schema defined. **Copy this value from the `schema` in your `profiles.yml` (dbt Core) or your dbt Cloud environment credentials.**

  For a developer environment, this is the developer's personal schema.
</ParamField>

<ParamField>
  The default database where dbt models are built. Defaults to the connection's database — copy the `database` value from your `profiles.yml` or dbt Cloud environment if this environment builds models in a different database. Shown only on dialects that support multiple databases or catalogs.
</ParamField>

<ParamField>
  A custom value for `target.name` when Omni runs dbt commands. Copy the `target` value from your `profiles.yml` or the **Target name** from dbt Cloud environment credentials if your dbt code relies on it — for example, a `generate_schema_name` macro that branches on `target.name`. New production environments default to `prod`.
</ParamField>

<ParamField>
  **Snowflake only.** A custom value for `target.role` when Omni runs dbt commands. Copy the `role` value from your `profiles.yml` if your dbt code relies on it, which is most common when developers dynamically switch databases by role.
</ParamField>

## Managing dbt environment variables

If your dbt project uses environment variables — such as to pull dependencies or determine the database or schema that models are built into — Omni needs the same values to compile your project. Environment variables are managed in an individual environment's settings.

### Adding dbt variables

<Note>
  Variables aren't shared across environments — they belong to a single environment. If multiple environments require the same variable, you'll need to add it to each environment.
</Note>

<Tabs>
  <Tab title="Omni UI" icon="window-maximize">
    1. In the [**Sync** page of the dbt IDE](#manage-environments), click the <Icon icon="ellipsis-vertical" /> icon next to the environment.
    2. Click **Edit**.
    3. In the **Environment Variables** section, click **Add variable**.
    4. Fill in the following:
       * **Name** - Must begin with `DBT_` and contain only letters, numbers, and underscores. This cannot be changed after the variable is saved.
       * **Value** - The value Omni passes when it runs dbt commands.
       * **Secret** - Check this to store the value as write-only, so it's masked after saving. Names beginning with `DBT_ENV_SECRET_` are marked secret automatically.
    5. Click **Save** to create the variable.
  </Tab>

  <Tab title="API" icon="cloud">
    Use the [Update a dbt environment API](/api/dbt/update-dbt-environment) to add variables to an existing dbt environment. Include a variable's `id` to update an existing variable:

    ```http theme={null}
    curl --request PUT \
      --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments/{environmentId} \
      --header 'Authorization: Bearer {token}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "variables": [
        {
          "name": "DBT_NEW_VAR",
          "value": "new_value",
          "isSecret": false
        },
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "DBT_TARGET",
          "value": "new_value",
          "isSecret": false
        }
      ]
    }
    '
    ```
  </Tab>

  <Tab title="CLI" icon="terminal">
    Use the [Omni CLI](/developers/cli) `omni connections dbt-environments-update` command to add variables to an existing dbt environment. Include a variable's `id` to update an existing variable:

    ```bash theme={null}
    omni connections dbt-environments-update <connection-id> <environment-id> --body '
    {
      "variables": [
        {
          "name": "DBT_NEW_VAR",
          "value": "new_value",
          "isSecret": false
        },
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "DBT_TARGET",
          "value": "new_value",
          "isSecret": false
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

### Renaming dbt variables

Variable names cannot be changed after the variable is saved. To rename a variable:

1. In the [**Sync** page of the dbt IDE](#manage-environments), click the <Icon icon="ellipsis-vertical" /> icon next to the environment.
2. Click **Edit**.
3. Scroll to the **Environment Variables** section.
4. [Delete the variable](#delete-variables).
5. [Create a variable](#add-variables) with the new name.

### Deleting dbt variables

To delete a variable:

1. In the [**Sync** page of the dbt IDE](#manage-environments), click the <Icon icon="ellipsis-vertical" /> icon next to the environment.
2. Click **Edit**.
3. Scroll to the **Environment Variables** section.
4. Click the <Icon icon="trash" /> icon next to the variable. **This immediately deletes the variable.**

## Next steps

* [Syncing dbt](/integrations/dbt/syncing-dbt) — Sync an environment's dbt metadata into your Omni model
* [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) — Resolve models that Omni couldn't match after a sync


# Pushing exposures to dbt
Source: https://docs.omni.co/integrations/dbt/exposures

Author new dbt models from Omni queries, edit existing models in the dbt IDE, and push exposures back to your dbt repository.

[dbt exposures](https://docs.getdbt.com/docs/build/exposures) document the downstream consumers of your dbt models, like dashboards or applications. Omni can generate exposure files from your published dashboards and push them to your dbt repository, providing visibility into how dbt models are consumed by Omni.

## Requirements

To follow the steps in this guide, you'll need:

* An Omni connection with a [configured dbt integration](/integrations/dbt)
* **Connection Admin** permissions for the connection in Omni
* Write access on the deploy key used to connect your [dbt Git repository](/integrations/dbt/setup) to Omni

## Pushing exposures to dbt

1. In Omni, click **Develop**.
2. If your organization has more than one model, click the model you want to work with to open the model IDE. If you have only one model, Omni opens it automatically.
3. Click **Model > Push to dbt**.
4. In the dialog, check the **Sync exposures** setting. Omni will generate exposure YAML files and push them to your repository.
5. Click **Create pull request**.
6. Review and merge the pull request in your Git provider.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Models missing from exposure">
    Exposures rely on explicit references to map dependencies. If Omni cannot determine the connection between a query and a dbt model, the exposure will not generate correctly.

    * **Use `${model_name}` syntax**. Your SQL must use Omni's mustache-style references (e.g., `${fct_orders}`) for Omni to detect the dependency.
    * **Avoid direct table references**. Referencing database tables directly (e.g., `FROM production.orders`) bypasses the mapping layer, and Omni cannot currently map these raw strings to dbt exposures.
      <Tip>
        If you have a large number of direct table references, use the [Content Validator](/modeling/develop/content-validator) to bulk-swap them for `${...}` model references to re-link your content to the dbt integration.
      </Tip>
    * **Check the publication status of the dashboard**. Omni expects dashboards to be moved to the shared space to be captured in a generated exposure.
  </Accordion>
</AccordionGroup>

## Common questions

<AccordionGroup>
  <Accordion title="What do exposures include?">
    When you push exposures from Omni, each published dashboard generates an exposure file containing:

    * The dashboard name and URL
    * The dbt models that the dashboard depends on
    * Metadata about the exposure (owner, type)
  </Accordion>

  <Accordion title="Where are exposure files created?">
    Exposure files are created in the `models/omni_exposures/` directory of your dbt repository. This file path is not currently customizable.
  </Accordion>

  <Accordion title="How are exposure names created?">
    Omni generates exposure names from dashboard titles. If a dashboard title contains special characters or emoji, the resulting exposure name may trigger dbt deprecation warnings about invalid naming conventions.
  </Accordion>

  <Accordion title="Can Omni automatically sync exposures to dbt?">
    While the **Push to dbt** action in the UI is a manual process, you can automate this using the [dbt exposures API endpoint](/api/dbt).

    The [Get dbt exposures API](/api/dbt/get-dbt-exposures) provides direct access to exposure metadata without requiring file generation. You can set up a script — using GitHub Actions, a cron job, or orchestration tools like Dagster or Airflow — to fetch exposure data using the API and generate the dbt YAML on a regular cadence. This ensures your dbt lineage stays synchronized with the dashboards your team is building without requiring manual intervention.

    <Tip>
      Check out our [community guide](https://community.omni.co/t/generating-dbt-exposures-using-omni-apis/392) for a script template to help you get started with this workflow, or use the [dbt exposures API](/api/dbt/get-dbt-exposures) directly.
    </Tip>
  </Accordion>

  <Accordion title="Are private Omni dashboards or workbooks included in exposures?">
    Currently, exposure generation focuses on the final, governed **dashboards** that serve as the primary consumption point for data.

    * **Published dashboards**: Only dashboards in the shared space are included in exposure generation.
    * **Private content**: Dashboards in your personal space and workbooks are not supported.
  </Accordion>
</AccordionGroup>

## Next steps

* [Embed dbt data health tiles](/guides/dashboards/dbt-data-health-tiles) — Display the freshness and quality of the data behind a dashboard using the exposures you've pushed to dbt.
* [Create and edit dbt models](/integrations/dbt/models) — Author new dbt models from Omni queries or edit existing models and push changes back to your dbt repository.


# Working with dbt and Git
Source: https://docs.omni.co/integrations/dbt/git-workflows

Manage Omni model changes using dbt and Git workflows, including branches, pull requests, and dynamic environments.

Managing changes across your data stack shouldn't feel like a black box. By integrating dbt and Git with Omni, you can align your analytics development with software engineering best practices using branches, pull requests, and dynamic environments to test changes before they reach your end users.

This guide covers the core workflows for keeping Omni in sync with dbt, collaborating with Git, and managing the end-to-end development lifecycle.

## Requirements

To follow the workflows in this guide, you'll need:

* A [configured dbt integration](/integrations/dbt/setup) on your Omni connection
* [Virtual schemas](/integrations/dbt/virtual-schemas) or [connection environments](/connect-data/dynamic-environments) configured to use the environment switcher
* Permissions to push changes from Omni to dbt, if using top-down workflows

## Governance and SDLC controls

For teams requiring governance, Omni supports a software-engineering-style development lifecycle. Three Omni features make this possible:

* **Omni's [Git integration](/integrations/git),** which allows you to sync your Omni model to a Git repository and enforce pull requests for all model changes.

  <Warning>
    We recommend having separate Git repositories for your dbt code and your Omni code.
  </Warning>

* **Dynamic environments**. Use [connection environments](/connect-data/dynamic-environments) to swap entire databases or [dynamic schemas](/modeling/models/dynamic-schemas) to swap underlying schemas within a single connection. This allows you to point an Omni branch at a CI schema to test breaking changes.

* **Content drafts**. [Drafts](/content/develop/drafts) allow you to iterate on dashboards privately. You can attach these drafts to specific branches to see how underlying model changes impact the visualization.

## Bottom-up: dbt to Omni

This is the standard flow where you define core logic (tables, views, schemas) in dbt. Omni inherits this logic, including descriptions and metadata, so you only have to define it once.

<Steps>
  <Step title="Prepare the data and code">
    Before Omni can detect a new model, it must be materialized as a table or view in your database and committed to your dbt Git repository so Omni can access the metadata.

    1. **Materialize your dbt model.** Run `dbt build` (or `dbt run`) against your development target. Omni cannot query a model that hasn't been materialized in your database yet.
    2. **Push to Git.** Push your dbt code to a feature branch in your Git provider.
  </Step>

  <Step title="Sync with Omni">
    1. **Create a branch.** In the Omni model IDE, create a new branch for testing changes from dbt.
    2. **Switch dbt environments.** Click the dbt settings button in the Omni branch header to navigate to your connection's dbt development settings page, where you can select your dbt development environment.
       <Tip>
         Switching dbt environments requires [Virtual Schemas](/integrations/dbt/virtual-schemas) to be configured.
       </Tip>
    3. **Refresh the schema.** Click **Model > Refresh Schema**. [Schema refreshes](/modeling/develop/schema-refreshes) trigger Omni to pull the updated manifest from Git and the new table structures from your database.
  </Step>

  <Step title="Model and validate">
    1. **Develop in Omni**. Your new dbt model will display in the IDE. You can now add it to topics, define joins, or create measures.
    2. **Validate Omni content**. Use the [**Content Validator**](/modeling/develop/content-validator) to see how your changes impact existing dashboards. You can perform a global find-and-replace for renamed fields across all content if needed.
    3. **Merge and publish**. Once your dbt pull request is merged, merge your Omni branch to promote your metadata changes to production.
  </Step>
</Steps>

## Top-down: Pushing changes from Omni to dbt

If you'd rather model visually, Omni also lets you push transformations from the Omni UI back to dbt. You can also restrict this workflow to specific users based on Omni data permissions. See [Creating new dbt models from Omni queries](/integrations/dbt/models#creating-new-dbt-models-from-omni-queries) for the full workflow.

<Tip>
  Use Omni as a prototyping layer. Build views in Omni first to test if they provide value before committing to the full dbt materialization process.
</Tip>

## Common questions

<AccordionGroup>
  <Accordion title="What workflows does Omni support for dbt and Git?">
    Omni supports both [bottom-up (dbt to Omni)](#dbt-to-omni) and [top-down (Omni to dbt)](#omni-to-dbt) development patterns.
  </Accordion>

  <Accordion title="Do business users need Git access to push changes to dbt?">
    No. Omni handles the connection using a centralized deploy key or integration. You can manage which users have permission to push changes within Omni's internal settings.
  </Accordion>

  <Accordion title="Will changes in an Omni branch be rebased when others merge?">
    Yes, shared model changes are automatically rebased and picked up by other branches upon merge.
  </Accordion>

  <Accordion title="Will branch-based draft changes be rebased if someone else is working on the same document?">
    No. Draft changes do not get rebased. If multiple people edit the same document draft, subsequent merges can overwrite previous changes. Coordinate with others when collaborating on the same dashboard to avoid accidental overwrites.
  </Accordion>

  <Accordion title="Can folder structures (e.g., user/branch-name) be used for Omni branches?">
    Yes. Folder-structured branch names aren't automatically matched between Omni and dbt, so you'll need to manually repoint your dbt branch to the working branch in the Omni model IDE to keep the workflows synced.
  </Accordion>

  <Accordion title="What happens if a dbt change breaks a dashboard?">
    Before merging your branch, use Omni's [Content Validator](/modeling/develop/content-validator) to find and fix any broken references (e.g., a deleted column). You can fix these globally from the validator interface before the changes go live.
  </Accordion>
</AccordionGroup>

## Next steps

* [Connecting dbt to Omni](/integrations/dbt/setup) — Set up the dbt integration if you haven't already
* [Working with dbt models](/integrations/dbt/models) — Author and edit dbt models from Omni
* [Content Validator](/modeling/develop/content-validator) — Catch broken references before merging model changes
* [Connection environments](/connect-data/dynamic-environments) — Configure dynamic environments for safe testing


# Getting started with dbt
Source: https://docs.omni.co/integrations/dbt/index

Integrate dbt Core or dbt Cloud with Omni to sync metadata, author models, push exposures, and connect your semantic layer.

Omni's bi-directional dbt integration makes it easy to view your dbt metadata, create and edit models within Omni, and keep your dbt and BI layer operating in lockstep.

## What you can do with dbt in Omni

After you [connect your dbt Git repository](#setup), Omni compiles your dbt project into a manifest and reads it. From there, you can:

<CardGroup>
  <Card title="Sync dbt model metadata" icon="arrows-rotate" href="/integrations/dbt/syncing-dbt">
    Sync metadata in your dbt project into matching views in your Omni model. See the [dbt metadata reference](/integrations/dbt/metadata-reference) for all available metadata.
  </Card>

  <Card title="Configure environments" icon="user-pen" href="/integrations/dbt/environments">
    Tell Omni how to run dbt commands against your project - which schema your models are built into, which database they live in, and what `target` your project expects.
  </Card>

  <Card title="Test dbt changes against real content" icon="arrow-right-arrow-left" href="/integrations/dbt/virtual-schemas">
    Use Virtual Schemas to enable environment switching without rewriting content, so you can see what a model change does before it reaches users.
  </Card>

  <Card title="Integrate dbt's semantic layer" icon="layer-group" href="/integrations/dbt/semantic-layer">
    Map dimensions, entities, measures, and metrics defined in dbt's semantic layer into your Omni model.
  </Card>

  <Card title="Author dbt models in Omni" icon="pen" href="/integrations/dbt/models">
    Promote an Omni query into a dbt model, or edit existing models in the Omni UI.
  </Card>

  <Card title="Push exposures to dbt" icon="share-nodes" href="/integrations/dbt/exposures">
    Track Omni dependencies in dbt by generating exposure files from published dashboards and pushing them to your dbt repository.
  </Card>

  <Card title="Collaborate with Git" icon="code-branch" href="/integrations/dbt/git-workflows">
    Learn how to manage the development lifecycle between Omni, dbt, and Git.
  </Card>
</CardGroup>

## Setting up dbt

To use dbt in Omni:

1. [**Connect your dbt Git repository**](/integrations/dbt/setup). Omni reads your dbt project from the Git repository that holds it. Each Omni connection supports one dbt project.
2. [**Configure your production dbt environment**](/integrations/dbt/environments). A dbt environment tells Omni where your models are built. Omni creates a production environment automatically when you connect a dbt Git repository, but you must configure its settings to mirror your `profiles.yml` (dbt Core) or your dbt Cloud environment.
3. [**Sync dbt with Omni**](/integrations/dbt/syncing-dbt). Trigger a dbt sync to compile the manifest, locate your dbt models in the database, and pull descriptions, tests, and tags into the matching Omni views.
4. [**Optional: Set up Virtual Schemas**](/integrations/dbt/virtual-schemas). Virtual Schemas point your content at a dbt environment instead of a physical schema, so users can swap between production and a personal dev build without breaking workbooks and topics.

## Guides

<Columns>
  <Card title="Preview dbt changes in Omni" icon="magnifying-glass" href="/guides/modeling/preview-dbt-changes">
    Preview dbt model changes in an Omni development environment.
  </Card>

  <Card title="Embed dbt data health tiles in Omni dashboards" icon="heart-pulse" href="/guides/dashboards/dbt-data-health-tiles">
    Embed dbt data health tiles (formerly status tiles) in Omni dashboards.
  </Card>

  <Card title="All dbt guides" icon="book" href="/guides/?tags=dbt">
    See all dbt guides
  </Card>
</Columns>

## Common questions

<AccordionGroup>
  <Accordion title="What dbt platforms and versions does Omni support?">
    Omni supports dbt Core and dbt Cloud. Since Omni reads your dbt project directly from its Git repository for either platform, version detection works the same way regardless of which one you use.

    For versions, the connection's **dbt Version** setting defaults to **Auto**. In Auto mode, Omni detects the version from the `require-dbt-version` pin in your `dbt_project.yml`, and falls back to the latest version Omni supports if the pin is missing or specifies a version Omni doesn't support. You can also choose a specific version from the **dbt Version** setting in the connection's dbt settings.

    The list of versions Omni supports changes as new dbt releases come out, so check the **dbt Version** dropdown in your connection's settings for what's currently available. For dbt's own policy on which versions it supports, see the [dbt version support documentation](https://docs.getdbt.com/docs/dbt-versions).
  </Accordion>

  <Accordion title="What features require using the formal dbt integration?">
    If you connect to tables as raw schemas rather than using the formal dbt integration, you won't be able to:

    * Sync metadata from dbt into your Omni model
    * View upstream dbt dependencies within Omni
    * Toggle between dbt environments
    * Edit dbt models in Omni
  </Accordion>

  <Accordion title="Can I connect multiple dbt projects to a single Omni connection?">
    Only one dbt project at a time can be associated with an Omni connection. If you have multiple dbt projects, the workaround depends on how you want to query the data in Omni.

    To query the datasets together, you'll need to do one of the following:

    1. Connect to one project and pull the other projects' tables as raw schemas
    2. Consolidate dbt projects

    Otherwise, you'll need to create a connection for each dataset. Depending on your goals and whether the datasets are identical, you can use [dynamic environments](/connect-data/dynamic-environments) to switch between the datasets in Omni. Dynamic environments only change the connection being used, not the structure of the underlying model - this means if one model uses an object that doesn't exist in another, there will be errors.
  </Accordion>

  <Accordion title="Can I use a custom dbt plugin to sync multi-project models?">
    No. Omni does not currently support custom dbt plugins.
  </Accordion>

  <Accordion title="Can I query tables from different dbt projects in the same dashboard?">
    This is possible only if the tables are included in the same Omni connection. A connection can have only one dbt manifest, so you can query Project A with full metadata and Project B as raw tables in the same dashboard.

    Combining tables from two separate Omni connections into a single query or dashboard tile isn't supported.
  </Accordion>
</AccordionGroup>


# dbt metadata reference
Source: https://docs.omni.co/integrations/dbt/metadata-reference

A complete list of the dbt metadata Omni can include in a dbt sync, and what each item becomes in your Omni model.

A [dbt sync](/integrations/dbt/syncing-dbt) reads metadata from your dbt project and adds it to the matching Omni views. This page lists the metadata a sync can include, what each item becomes in Omni, and what a sync does not read.

Omni includes some metadata in every sync, while the rest depends on the connection's dbt settings.

## Default dbt metadata

Every time Omni performs a <Tooltip href="/integrations/dbt/syncing-dbt">dbt sync</Tooltip>, the following metadata is included by default:

| From dbt                                                                                                             | In Omni                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Model, seed, or snapshot description**                                                                             | View description                                                                                                                                                                                 |
| **Column description**                                                                                               | Description on the matching dimension                                                                                                                                                            |
| **Model SQL**                                                                                                        | `code` in the view's `dbt` block                                                                                                                                                                 |
| **materialized config**                                                                                              | `config.materialized` in the view's `dbt` block                                                                                                                                                  |
| **Model-level tags config**                                                                                          | `config.tags` in the view's `dbt` block                                                                                                                                                          |
| [**Custom schema config**](https://docs.getdbt.com/docs/build/custom-schemas)                                        | `config.schema` in the view's `dbt` block. Also names the [virtual schema](/integrations/dbt/virtual-schemas)                                                                                    |
| **Downstream models**                                                                                                | `referenced_by` in the view's `dbt` block                                                                                                                                                        |
| [**accepted\_values test values**](https://docs.getdbt.com/reference/resource-properties/data-tests#accepted_values) | `all_values` on the dimension, which Omni uses for filter suggestions and [AI context](/modeling/develop/ai-optimization). If the test has a `where:` config, the values map to `sample_values`. |

Omni matches dbt column names to dimension names without case sensitivity. Only columns that exist in the warehouse table are updated — documenting a column in dbt does not create a dimension in Omni.

## Constraints

If you have [native dbt `primary_key` and `foreign_key` constraints](https://docs.getdbt.com/reference/resource-properties/constraints) defined in your dbt project, you can include them in <Tooltip href="/integrations/dbt/syncing-dbt">dbt syncs</Tooltip> by enabling **Auto-generate primary keys and relationships from dbt constraints** in the connection's dbt settings.

When this setting is enabled, dbt syncs include the following:

| From dbt                     | In Omni                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **primary\_key constraints** | View primary keys. **Note**: Omni only applies a primary key from dbt when the view does not already have one.     |
| **foreign\_key constraints** | [Relationships](/modeling/relationships). **Note**: Foreign key constraints must use a single column on each side. |

<Note>
  Only native dbt constraints are supported. Constraints defined through a package (e.g., `Snowflake-Labs/dbt_constraints`) or constraints based on data tests are not supported.
</Note>

## Semantic layer

If you use dbt's semantic layer, you can include the semantic layer's metadata in <Tooltip href="/integrations/dbt/syncing-dbt">dbt syncs</Tooltip> in a few short steps. See [Integrating dbt's semantic layer with Omni](/integrations/dbt/semantic-layer) for more information.

When the semantic layer is enabled, dbt syncs include the following:

| From dbt                      | In Omni                                                                                                                      |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Semantic layer dimensions** | View dimensions. Includes metadata for descriptions, expressions, and labels.                                                |
| **Semantic layer entities**   | Dimensions that are used to create [relationships](/modeling/relationships) between tables mapped to their respective models |
| **Measures**                  | View [measures](/modeling/measures)                                                                                          |
| **Simple metrics**            | [Measures](/modeling/measures) in the view that the table of the underlying expression is based on                           |
| **Ratio metrics**             | [Measures](/modeling/measures) in the view that the denominator is based on                                                  |
| **Derived metrics**           | [Measures](/modeling/measures) in the view that the first metric is based on                                                 |
| **Semantic view labels**      | Labels on the corresponding `dbt_models` table                                                                               |

Metrics with filters will have dimensions created as those filters in Omni. These dimensions are automatically hidden and applied to the corresponding Omni measure for an equivalent calculation.

## Next steps

* Troubleshoot and resolve [dbt sync issues](/integrations/dbt/debugging-sync-issues)
* Learn more about [dbt syncs in Omni](/integrations/dbt/syncing-dbt)
* Integrate [dbt's semantic layer](/integrations/dbt/semantic-layer) with Omni
* Generate [exposures](/integrations/dbt/exposures) in Omni and push to dbt


# Authoring dbt models in Omni
Source: https://docs.omni.co/integrations/dbt/models

Author new dbt models from Omni queries, and edit existing models in Omni workbooks.

While not every query needs to be pushed down to dbt, when you do create a query where you want to promote the logic into dbt, you can do so within Omni.

Omni also supports editing existing models. You can run and compile dbt SQL with Jinja references and config settings, allowing you to interact with data as you build and eliminate the need for manual SQL substitutions when referencing existing models. Models authored in Omni can then be materialized through existing dbt workflows without requiring complex warehouse permissions for schema ownership.

## Requirements

To follow the steps in this guide, you'll need an Omni connection with a [configured dbt integration](/integrations/dbt/setup).

## Creating new dbt models from Omni queries

1. In a workbook, open the query you want to use to convert to a dbt model.

2. Click **Model > Convert to dbt model**. Omni will convert the query to dbt SQL and update to display a **dbt mode** banner above the field browser:

   <img alt="Highlighted dbt mode banner in an Omni workbook" />

3. Use the SQL editor to refine the model. You can run the query periodically to verify the output.

4. Click **Model > Push to dbt repo**.

5. In the **Push to dbt** dialog:

   <img alt="Push to dbt dialog in Omni" />

   * **Model name** — The filename for the new `.sql` file. Make sure this is unique — if it matches an existing model name, it will **overwrite** that file.
   * **Git branch** — The branch to push to
   * **Commit message** — A description of the change

6. Click **Push**.

   <Tip>
     **Seeing changes to an existing file?** If the diff shows modifications to a file you didn't intend to update, the model name likely matches an existing dbt model. See [Preventing overwrites to existing models](#preventing-overwrites-to-existing-models) for how to fix this.
   </Tip>

7. You'll be prompted to create a pull request in the dbt git repository. Complete the pull request process, following your organization's process.

After the pull request is merged and the model is built in your warehouse, bring it into Omni by [triggering a schema refresh](/modeling/develop/schema-refreshes).

## Editing dbt models in Omni

<Note>
  **Modeler** or **Connection Admin** permissions are required to edit dbt models.
</Note>

While the dbt IDE is read-only, you can edit existing dbt models in a workbook and push changes back to the dbt repository.

1. Navigate to **Develop**. If your organization has more than one model, select the model you want to work with. If you have only one model, Omni opens it automatically.
2. In the model IDE, click the <DbtIdeIcon /> **dbt** icon in the sidebar.
3. In the file list, click the dbt model you want to edit.
4. Click the **Open in workbook** button near the top right corner of the page:

   <img alt="Open in workbook button in the Omni dbt IDE" />
5. The model will open in a new workbook. Use the SQL editor to iterate on the model.
6. When finished, click **Model > Push to dbt repo** and follow the same push flow as creating a new model.

After the model is rebuilt in your warehouse, bring in the updated version by [triggering a schema refresh](/modeling/develop/schema-refreshes).

## Preventing overwrites to existing models

When you convert a workbook query and push it to your dbt repository, Omni checks the **Model name** against your existing project. When pushing a model, Omni uses the **Model name** to determine whether to create a new file or update an existing one. If the name matches an existing dbt model, Omni treats the push as an update rather than a new addition.

To create a brand-new `.sql` file instead of overwriting:

1. Open the **Push to dbt** dialog.
2. Edit the **Model name** field to a unique name.
3. Confirm the push to generate the new file in your repository.

<Tip>
  **Check the diff.** You can review exactly what will be changed or overwritten in the diff viewer before you confirm the push.
</Tip>

## Next steps

* [Trigger a schema refresh](/modeling/develop/schema-refreshes) — Bring newly built or updated dbt models into Omni.


# Integrating dbt's semantic layer with Omni
Source: https://docs.omni.co/integrations/dbt/semantic-layer

Learn how Omni integrates with dbt's semantic layer to pull dimensions, measures, metrics, and entities into your Omni model.

Omni's integration with dbt's semantic layer reads metadata from your dbt semantic layer project and maps it into your Omni model. This includes dimensions, entities, measures, and metrics, so you can use your dbt semantic definitions directly in Omni without recreating them.

## Requirements

To follow this guide, you'll need:

* A dbt semantic layer project configured in your dbt repository
* To have the [dbt integration enabled](/integrations/dbt/setup) for an Omni database connection
* **Organization Admin** permissions or **Connection Admin** permissions for the connection where dbt is enabled

## Mapping dbt metadata into Omni

See the [dbt metadata reference](/integrations/dbt/metadata-reference#semantic-layer) to learn about how dbt semantic layer data is mapped into Omni.

## Setup

<Steps>
  <Step title="Enable the semantic layer">
    1. Navigate to **Settings > Connections**.
    2. Click the connection where dbt is enabled.
    3. Click the **dbt** tab on the connection's settings page.
    4. Check the **Enable semantic layer** box.
    5. Click **Save**.
  </Step>

  <Step title="Perform a schema refresh">
    With the semantic layer sync enabled, the next step is to trigger a [schema refresh](/modeling/develop/schema-refreshes) to pull the metadata into Omni.

    1. In the connection settings page, click the **Settings** tab.
    2. Click the **Refresh now** button to trigger the refresh.

    <Note>
      If you have branch-based schema refreshes enabled, the steps for triggering a refresh will be different than those listed here. Refer to the [Schema refreshes guide](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) for more information.
    </Note>
  </Step>
</Steps>

## Known differences and limitations

There are some behavioral differences between how dbt's semantic layer and Omni handle certain concepts:

<Columns>
  <Card title="Not currently supported" icon="ban">
    The following are not currently supported:

    * Cumulative and conversion metrics
    * Null filling
  </Card>

  <Card title="Aggregation time dimensions" icon="calendar">
    Omni does not support the concept of an `agg_time_dimension`, so you must carefully pick the dimensions and grains at which you view various metrics. Omni will append a comment to the field's description to denote the default time field that should be used with the metric to help provide clarity.
  </Card>

  <Card title="Time spines" icon="timeline">
    Time spines exist in dbt's semantic layer, whereas Omni allows you to fill dates when desired to conduct more complete analyses over various time windows.
  </Card>

  <Card title="Offsets and relative calculations" icon="calculator">
    These can still be done in Omni via YAML configuration or the UI, depending on the specific goal.
  </Card>
</Columns>

<Card title="Ratio metric calculations" icon="arrow-down-1-9">
  When calculating ratio metrics, Omni joins the tables because its representation of metrics is still tied to a table.

  This can differ from MetricFlow's approach of generating two separate metrics in subqueries, joining them, and then calculating the ratio. Omni's approach automatically leverages symmetric aggregation to avoid miscalculations caused by fan outs.
</Card>

## Common questions

<AccordionGroup>
  <Accordion title="Does Omni's integration work with MetricFlow?">
    Yes. The dbt Semantic Layer is powered by [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow), dbt's open-source metric query engine. If you've defined metrics and semantic models using MetricFlow, this is the integration that brings them into Omni.
  </Accordion>

  <Accordion title="Where should I define metrics - in dbt or in Omni?">
    The most effective approach is a hybrid model that balances centralized governance with BI agility.

    Use the dbt Semantic Layer for:

    * **Cross-tool consistency**: Define "Tier 0" canonical metrics (like Gross Revenue or Churn Rate) that must be identical across multiple platforms (e.g., Hex, Salesforce, or custom apps).
    * **Centralized governance**: Use dbt when you want the data engineering team to own the "source of truth" through a formal pull request (PR) process.

    Use the Omni semantic layer for:

    * **BI-specific metadata**: Use Omni for logic that only impacts the analysis experience, such as **color mapping**, **field grouping**, **drill paths**, and **friendly labels**.
    * **AI and natural language**: Add **AI context** and synonyms in Omni to help users query data in plain English.
    * **Speed and plasticity**: Use Omni to prototype new metrics or create complex join logic and workbook-level calculations on the fly without waiting for dbt deployments.

    <Tip>
      Think of the dbt Semantic Layer as a small set of slow-changing, universal gold metrics. Think of the Omni layer as the plastic workspace where you iterate quickly and provide the rich context users need for self-service.
    </Tip>
  </Accordion>

  <Accordion title="Is the dbt Semantic Layer integration one-way or two-way?">
    The dbt Semantic Layer integration is a **one-way import**. Omni ingests metrics and semantic models defined in dbt, but it does not support exporting or pushing metrics authored in Omni back into dbt semantic files.
  </Accordion>
</AccordionGroup>

## Troubleshooting

See [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) for more information.

## Next steps

* Author and edit [dbt models](/integrations/dbt/models) from Omni
* Trigger a [schema refresh](/modeling/develop/schema-refreshes) to sync dbt changes into your Omni model
* Learn what [metadata Omni pulls in](/integrations/dbt/metadata-reference) during dbt syncs


# Connecting an Azure DevOps dbt repository to Omni
Source: https://docs.omni.co/integrations/dbt/setup/azure-devops

Connect your Azure DevOps dbt repository to Omni.

Omni supports **SSH authentication** for connecting to your Azure DevOps repository. This method uses a deploy key to connect Omni to your repository.

## Requirements

To follow the steps in this guide, you'll need:

* **An existing [database connection](/connect-data/setup) in Omni**
* [**Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt
* **Permissions in Azure DevOps** that allow you to add deploy keys

## Configure SSH authentication

<Steps>
  <Step title="Retrieve the dbt repository's SSH URL">
    1. In your browser, navigate to the Azure DevOps repository you want to connect to Omni.
    2. Click the **Clone** button near the top right corner of the page.
    3. Click the  option to display the repository's  URL.

    Keep this page open—you'll need it in the next step.
  </Step>

  <Step title="Create the dbt connection in Omni">
    1. In Omni, navigate to **Settings > Connections**.
    2. Click the connection you want to use.
    3. Click the **dbt** tab.
    4. Fill in the following fields:
       * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
       * **Git SSH URL** - Enter the SSH URL you retrieved in step 1 of this guide
       - **Git Branch** - Enter the name of the default branch for the repository. This is usually `main` or `master`.
         <Warning>
           Avoid naming your branch `omni` or `omnianalytics`. Omni creates temporary branches prefixed with `omni/` and `omnianalytics/` during internal operations like connection testing. A branch named `omni` or `omnianalytics` in your repository will conflict with this and cause validation errors and connection test failures.
         </Warning>
       - **Folder** - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
       - **Enable Virtual Schemas** - Enables the use of virtual schemas, which require additional setup. See [Working with dbt virtual schemas](/integrations/dbt/virtual-schemas) for instructions.
       - **Enable dbt Semantic Layer** - Check this box to enable the [dbt Semantic Layer integration](/integrations/dbt/semantic-layer). When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
       - **Auto-generate primary keys and relationships from dbt constraints** - Check this box to allow Omni to generate primary keys and relationships from native dbt constraints.
       - **dbt Version** - When set to **Auto** (default), Omni will auto-detect the dbt version from the `require-dbt-version` pin in `dbt_project.yml`. If a usable pin isn't found, Omni defaults to the latest supported version of dbt. Otherwise, you can select a specific version from the list of versions that Omni supports. See [supported dbt platforms and versions](/integrations/dbt#common-questions) for more on how Omni picks a version.
    5. Click **Save**.

    After the dbt connection is created, a **Public Key** will display. Leave this page open - you'll need it in the next step.
  </Step>

  <Step title="Add the deploy key to your repository">
    <Note>
      If the repository is already connected to Omni through the [Git integration](/integrations/git), skip this step. Omni will use the existing deploy key.
    </Note>

    In this step, you'll add the **Public Key** created in step 2 of this guide to your dbt repository as a deploy key.

    1. Browse to the Azure DevOps web portal (ex: `https://dev.azure.com/<your-org-name>/`).
    2. Click the **User settings** icon next to your avatar in the top right corner of the page.
    3. Click **SSH public keys**.
    4. On the page that displays, click **+ New Key**.
    5. In the **Add New SSH Key** panel that displays, fill in the following:
       * **Name** - Enter a descriptive name, such as *Omni Snowflake Model*
       * **Public Key Data** -&#x20;
    6. Click **Add**.
  </Step>
</Steps>

## Next steps

After you successfully connect your dbt repository, you need to:

1. [Configure your production dbt environment](/integrations/dbt/environments)
2. [Sync dbt with Omni](/integrations/dbt/syncing-dbt)
3. [Set up Virtual Schemas](/integrations/dbt/virtual-schemas). This isn't required to use the dbt integration, but enabling Virtual Schemas before you start building in Omni avoids migrating later.


# Connecting a GitHub dbt repository to Omni
Source: https://docs.omni.co/integrations/dbt/setup/github

Connect your GitHub dbt repository to Omni.

Omni supports three methods for connecting to a GitHub-hosted dbt repository:

* **GitHub App authentication** - Uses a GitHub app to perform authentication. Enables commit signing.
* **SSH authentication** — Uses a deploy key to connect Omni to your repository. This is the traditional method and requires configuring a deploy key in your Git provider.
* **HTTPS token authentication** — Uses an access token to authenticate. This method is simpler to set up because it doesn't require deploy keys.

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="GitHub App">
  <Note>
    GitHub App authentication is only available for `github.com` repositories. This option only appears if your Omni instance has the GitHub App configured. If you don't see this option and want to use it, reach out to Omni support.
  </Note>

  ## Requirements

  To follow the steps in this guide, you'll need:

  * **An existing [database connection](/connect-data/setup) in Omni**
  * [**Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt

  ## Configure GitHub App authentication

  <Steps>
    <Step title="Retrieve the repository's HTTPS URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Launch the Omni GitHub App installation flow">
      1. In Omni, navigate to **Settings > Connections**.
      2. Click the connection you want to use.
      3. Click the **dbt** tab.

      4) From the **Authentication Method** dropdown, select **GitHub App**.
      5) In the **HTTPS URL** field, copy and paste the repository's HTTPS URL from Step 1.
      6) Next to the **Installation ID** field, click the **Install the Omni GitHub App** link.

      GitHub will open in another tab in your browser. Leave this page open and finish the app installation in the other tab.
    </Step>

    <Step title="Install the Omni GitHub App">
      1. In GitHub, select the repository you want to connect.
      2. Complete the installation.
      3. After you complete the installation, retrieve the app's **installation ID** from the page URL:

         <Frame>
           <img alt="Highlighted app installation ID in the page URL" />
         </Frame>

      The installation ID is the string of numbers after the last forward slash in the page URL.
    </Step>

    <Step title="Configure the Git settings in Omni">
      1. Navigate back to the Omni Git settings page.
      2. Finish configuring the integration's settings:
         * **Installation ID** - Paste the installation ID you copied from GitHub in the previous step
         * **Committer name** - Enter the display name to associate with [signed commits](#configure-commit-signing). **You'll configure commit signing in the next step.**
         * **Committer email** - Enter the verified email of the GitHub user to associate with [signed commits](#configure-commit-signing). **You'll configure commit signing in the next step.**
         - **Git Branch** - Enter the name of the default branch for the repository. This is usually `main` or `master`.
           <Warning>
             Avoid naming your branch `omni` or `omnianalytics`. Omni creates temporary branches prefixed with `omni/` and `omnianalytics/` during internal operations like connection testing. A branch named `omni` or `omnianalytics` in your repository will conflict with this and cause validation errors and connection test failures.
           </Warning>
         - **Folder** - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
         - **Enable Virtual Schemas** - Enables the use of virtual schemas, which require additional setup. See [Working with dbt virtual schemas](/integrations/dbt/virtual-schemas) for instructions.
         - **Enable dbt Semantic Layer** - Check this box to enable the [dbt Semantic Layer integration](/integrations/dbt/semantic-layer). When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
         - **Auto-generate primary keys and relationships from dbt constraints** - Check this box to allow Omni to generate primary keys and relationships from native dbt constraints.
         - **dbt Version** - When set to **Auto** (default), Omni will auto-detect the dbt version from the `require-dbt-version` pin in `dbt_project.yml`. If a usable pin isn't found, Omni defaults to the latest supported version of dbt. Otherwise, you can select a specific version from the list of versions that Omni supports. See [supported dbt platforms and versions](/integrations/dbt#common-questions) for more on how Omni picks a version.
      3. Click **Save and Test Connection**.
    </Step>

    <Step title="Configure commit signing">
      <Note>
        This step is optional.
      </Note>

      Authenticating through Omni's GitHub app allows you to enable commit signing. When a user with a verified email adds Omni's public signing key, Omni's commits will show up as **Verified**.

      The user with the verified **Committer email** you defined in the previous step must complete the following to configure commit signing:

      1. In GitHub, navigate to **Settings > SSH and GPG keys**. **Note**: This is an individual **user's** settings, not the connected repository's settings.
      2. Click **New SSH key**.
      3. Set the **Key type** to **Signing key**.
      4. In the **Key** field, paste the public key from the Omni Git settings page.
      5. Click **Add SSH key**.
    </Step>
  </Steps>
</View>

<View title="SSH authentication">
  ## Requirements

  To follow the steps in this guide, you'll need:

  * **An existing [database connection](/connect-data/setup) in Omni**
  * [**Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt

  ## Configure SSH authentication

  <Steps>
    <Step title="Retrieve the dbt repository's SSH URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Create the dbt connection in Omni">
      1. In Omni, navigate to **Settings > Connections**.
      2. Click the connection you want to use.
      3. Click the **dbt** tab.
      4. Fill in the following fields:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **Git SSH URL** - Enter the SSH URL you retrieved in step 1 of this guide
         - **Git Branch** - Enter the name of the default branch for the repository. This is usually `main` or `master`.
           <Warning>
             Avoid naming your branch `omni` or `omnianalytics`. Omni creates temporary branches prefixed with `omni/` and `omnianalytics/` during internal operations like connection testing. A branch named `omni` or `omnianalytics` in your repository will conflict with this and cause validation errors and connection test failures.
           </Warning>
         - **Folder** - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
         - **Enable Virtual Schemas** - Enables the use of virtual schemas, which require additional setup. See [Working with dbt virtual schemas](/integrations/dbt/virtual-schemas) for instructions.
         - **Enable dbt Semantic Layer** - Check this box to enable the [dbt Semantic Layer integration](/integrations/dbt/semantic-layer). When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
         - **Auto-generate primary keys and relationships from dbt constraints** - Check this box to allow Omni to generate primary keys and relationships from native dbt constraints.
         - **dbt Version** - When set to **Auto** (default), Omni will auto-detect the dbt version from the `require-dbt-version` pin in `dbt_project.yml`. If a usable pin isn't found, Omni defaults to the latest supported version of dbt. Otherwise, you can select a specific version from the list of versions that Omni supports. See [supported dbt platforms and versions](/integrations/dbt#common-questions) for more on how Omni picks a version.
      5. Click **Save**.

      After the dbt connection is created, a **Public Key** will display. Leave this page open - you'll need it in the next step.
    </Step>

    <Step title="Add the deploy key to your repository">
      <Note>
        If the repository is already connected to Omni through the [Git integration](/integrations/git), skip this step. Omni will use the existing deploy key.
      </Note>

      In this step, you'll add the **Public Key** created in step 2 of this guide to your dbt repository as a deploy key.

      1. In the GitHub repository, click the **Settings** tab.
      2. Click **Deploy keys**, located in the **Security** section of the sidebar.
      3. Click **Add deploy key**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** -&#x20;
         * **Allow write access** -&#x20;
      5. Click **Add key**.
    </Step>
  </Steps>
</View>

<View title="HTTPS token authentication">
  ## Requirements

  To follow the steps in this guide, you'll need:

  * **An existing [database connection](/connect-data/setup) in Omni**
  * [**Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt

  ## HTTPS token authentication

  <Steps>
    <Step title="Retrieve the dbt repository's HTTPS URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Create an access token">
      <Note>
        If the repository belongs to an organization, the organization must have a [personal access token policy](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) that allows the creation of personal access tokens.
      </Note>

      In GitHub, create a fine-grained personal access token with the following permissions for the repository:

      * **Contents**: Read and write
      * **Metadata**: Read-only (automatically included)
      * **Pull requests**: Read and write

      See [GitHub's documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) for instructions on creating a fine-grained personal access token.
    </Step>

    <Step title="Create the dbt connection in Omni">
      1. In Omni, navigate to **Settings > Connections**.
      2. Click the connection you want to use.
      3. Click the **dbt** tab.
      4. Fill in the following fields:
         * **Authentication Method** - Select **HTTPS (Token)** from the dropdown.
         * **Git HTTPS URL** - Enter the HTTPS URL you retrieved in step 1 of this guide
         * **Access Token** - Paste the access token you created in step 2 of this guide
         - **Git Branch** - Enter the name of the default branch for the repository. This is usually `main` or `master`.
           <Warning>
             Avoid naming your branch `omni` or `omnianalytics`. Omni creates temporary branches prefixed with `omni/` and `omnianalytics/` during internal operations like connection testing. A branch named `omni` or `omnianalytics` in your repository will conflict with this and cause validation errors and connection test failures.
           </Warning>
         - **Folder** - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
         - **Enable Virtual Schemas** - Enables the use of virtual schemas, which require additional setup. See [Working with dbt virtual schemas](/integrations/dbt/virtual-schemas) for instructions.
         - **Enable dbt Semantic Layer** - Check this box to enable the [dbt Semantic Layer integration](/integrations/dbt/semantic-layer). When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
         - **Auto-generate primary keys and relationships from dbt constraints** - Check this box to allow Omni to generate primary keys and relationships from native dbt constraints.
         - **dbt Version** - When set to **Auto** (default), Omni will auto-detect the dbt version from the `require-dbt-version` pin in `dbt_project.yml`. If a usable pin isn't found, Omni defaults to the latest supported version of dbt. Otherwise, you can select a specific version from the list of versions that Omni supports. See [supported dbt platforms and versions](/integrations/dbt#common-questions) for more on how Omni picks a version.
      5. Click **Save**.
    </Step>
  </Steps>
</View>

## Next steps

After you successfully connect your dbt repository, you need to:

1. [Configure your production dbt environment](/integrations/dbt/environments)
2. [Sync dbt with Omni](/integrations/dbt/syncing-dbt)
3. [Set up Virtual Schemas](/integrations/dbt/virtual-schemas). This isn't required to use the dbt integration, but enabling Virtual Schemas before you start building in Omni avoids migrating later.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection test fails with GitHub App authentication">
    If the connection test fails when using **GitHub App** authentication, verify:

    * **Installation ID is correct** - The installation ID must be numeric and match the Omni GitHub App installation for your repository or organization. You can find this in your GitHub settings under **Integrations > GitHub Apps > Configure**.
    * **GitHub App is installed** - The Omni GitHub App must be installed and granted access to the repository. Check your GitHub organization or repository settings to confirm.
    * **Repository URL is correct** - The repository URL must be an HTTPS URL starting with `https://github.com/`.
    * **GitHub App is configured in Omni** - Your Omni instance must have the GitHub App configured. If the GitHub App option doesn't appear in the authentication method dropdown, contact your Omni administrator.

    If you continue to experience issues, try using **SSH** or **HTTPS token** authentication instead.
  </Accordion>
</AccordionGroup>


# Connecting a Gitlab dbt repository to Omni
Source: https://docs.omni.co/integrations/dbt/setup/gitlab

Connect your Gitlab dbt repository to Omni.

Omni supports three methods for connecting to your Gitlab-hosted dbt repository:

* **SSH authentication** — Uses a deploy key to connect Omni to your repository. This is the traditional method and requires configuring a deploy key in your Git provider.
* **HTTPS token authentication** — Uses an access token to authenticate. This method is simpler to set up because it doesn't require deploy keys.

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="SSH authentication">
  ## Requirements

  To follow the steps in this guide, you'll need:

  * **An existing [database connection](/connect-data/setup) in Omni**
  * [**Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt
  * **Permissions in Gitlab** that allow you to add deploy keys

  ## Configure SSH authentication

  <Steps>
    <Step title="Retrieve the dbt repository's SSH URL">
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Create the dbt connection in Omni">
      1. In Omni, navigate to **Settings > Connections**.
      2. Click the connection you want to use.
      3. Click the **dbt** tab.
      4. Fill in the following fields:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **Git SSH URL** - Enter the SSH URL you retrieved in step 1 of this guide
         - **Git Branch** - Enter the name of the default branch for the repository. This is usually `main` or `master`.
           <Warning>
             Avoid naming your branch `omni` or `omnianalytics`. Omni creates temporary branches prefixed with `omni/` and `omnianalytics/` during internal operations like connection testing. A branch named `omni` or `omnianalytics` in your repository will conflict with this and cause validation errors and connection test failures.
           </Warning>
         - **Folder** - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
         - **Enable Virtual Schemas** - Enables the use of virtual schemas, which require additional setup. See [Working with dbt virtual schemas](/integrations/dbt/virtual-schemas) for instructions.
         - **Enable dbt Semantic Layer** - Check this box to enable the [dbt Semantic Layer integration](/integrations/dbt/semantic-layer). When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
         - **Auto-generate primary keys and relationships from dbt constraints** - Check this box to allow Omni to generate primary keys and relationships from native dbt constraints.
         - **dbt Version** - When set to **Auto** (default), Omni will auto-detect the dbt version from the `require-dbt-version` pin in `dbt_project.yml`. If a usable pin isn't found, Omni defaults to the latest supported version of dbt. Otherwise, you can select a specific version from the list of versions that Omni supports. See [supported dbt platforms and versions](/integrations/dbt#common-questions) for more on how Omni picks a version.
      5. Click **Save**.

      After the dbt connection is created, a **Public Key** will display. Leave this page open - you'll need it in the next step.
    </Step>

    <Step title="Add the deploy key to your repository">
      <Note>
        If the repository is already connected to Omni through the [Git integration](/integrations/git), skip this step. Omni will use the existing deploy key.
      </Note>

      In this step, you'll add the **Public Key** created in step 2 of this guide to your dbt repository as a deploy key.

      1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
         <Note>
           GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
         </Note>
      2. Fill in the deploy key fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** -&#x20;
         * **Grant write permissions to this key** -&#x20;
      3. Click **Add key**.
    </Step>
  </Steps>
</View>

<View title="HTTPS token authentication">
  ## Requirements

  To follow the steps in this guide, you'll need:

  * **An existing [database connection](/connect-data/setup) in Omni**
  * [**Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt
  * **Permissions in Gitlab** that allow you to create access tokens

  ## HTTPS token authentication

  <Steps>
    <Step title="Retrieve the dbt repository's HTTPS URL">
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Create a Gitlab access token">
      In GitLab, create a project access token with the following scopes:

      * **read\_repository**
      * **write\_repository**

      See [GitLab's documentation](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) for instructions on creating a project access token.
    </Step>

    <Step title="Create the dbt connection in Omni">
      1. In Omni, navigate to **Settings > Connections**.
      2. Click the connection you want to use.
      3. Click the **dbt** tab.
      4. Fill in the following fields:
         * **Authentication Method** - Select **HTTPS (Token)** from the dropdown.
         * **Git HTTPS URL** - Enter the HTTPS URL you retrieved in step 1 of this guide
         * **Access Token** - Paste the access token you created in step 2 of this guide
         - **Git Branch** - Enter the name of the default branch for the repository. This is usually `main` or `master`.
           <Warning>
             Avoid naming your branch `omni` or `omnianalytics`. Omni creates temporary branches prefixed with `omni/` and `omnianalytics/` during internal operations like connection testing. A branch named `omni` or `omnianalytics` in your repository will conflict with this and cause validation errors and connection test failures.
           </Warning>
         - **Folder** - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
         - **Enable Virtual Schemas** - Enables the use of virtual schemas, which require additional setup. See [Working with dbt virtual schemas](/integrations/dbt/virtual-schemas) for instructions.
         - **Enable dbt Semantic Layer** - Check this box to enable the [dbt Semantic Layer integration](/integrations/dbt/semantic-layer). When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
         - **Auto-generate primary keys and relationships from dbt constraints** - Check this box to allow Omni to generate primary keys and relationships from native dbt constraints.
         - **dbt Version** - When set to **Auto** (default), Omni will auto-detect the dbt version from the `require-dbt-version` pin in `dbt_project.yml`. If a usable pin isn't found, Omni defaults to the latest supported version of dbt. Otherwise, you can select a specific version from the list of versions that Omni supports. See [supported dbt platforms and versions](/integrations/dbt#common-questions) for more on how Omni picks a version.
      5. Click **Save**.
    </Step>
  </Steps>
</View>

## Next steps

After you successfully connect your dbt repository, you need to:

1. [Configure your production dbt environment](/integrations/dbt/environments)
2. [Sync dbt with Omni](/integrations/dbt/syncing-dbt)
3. [Set up Virtual Schemas](/integrations/dbt/virtual-schemas). This isn't required to use the dbt integration, but enabling Virtual Schemas before you start building in Omni avoids migrating later.


# Connecting a dbt Git repository to Omni
Source: https://docs.omni.co/integrations/dbt/setup/index

Get started using Omni's dbt integration by connecting your dbt Git repository.

The first step to using dbt in Omni is to connect the Git repository containing your dbt project to Omni. Use the guide for your Git provider to get started:

<CardGroup>
  <Card title="Azure DevOps" icon="microsoft" href="/integrations/dbt/setup/azure-devops" />

  <Card title="GitHub" icon="github" href="/integrations/dbt/setup/github" />

  <Card title="GitLab" icon="gitlab" href="/integrations/dbt/setup/gitlab" />
</CardGroup>

## Next steps

After you successfully connect your dbt repository, you need to:

1. [Configure your production dbt environment](/integrations/dbt/environments)
2. [Sync dbt with Omni](/integrations/dbt/syncing-dbt)
3. [Set up Virtual Schemas](/integrations/dbt/virtual-schemas). This isn't required to use the dbt integration, but enabling Virtual Schemas before you start building in Omni avoids migrating later.

## Common questions

<AccordionGroup>
  <Accordion title="What features require a direct dbt Git repository connection?">
    While reading metadata from your database provides basic descriptions, you won't be able to:

    * Push SQL changes or new fields created in Omni back to dbt
    * Sync personal development branches in Omni to your development dbt environment
    * Auto-generate primary keys and relationships from dbt YAML constraints
  </Accordion>

  <Accordion title="Can I use the same Git repo for Omni models and dbt code?">
    Omni strongly recommends using two separate repositories: one for your dbt project and one for your Omni semantic model. This gives you:

    * **Clear ownership** — Separates data engineering from business logic.
    * **Faster iteration** — Prevents semantic refreshes from being tied to dbt compilation times.
    * **Cleaner Git history** — Keeps automatic commits from the Omni IDE out of your dbt pull requests.
    * **Coordinated deployments** — Ensures Omni model changes only apply after related dbt runs complete, so downstream content doesn't break.

    If you decide to keep Omni and dbt in the same repository, use separate branches for changes. See the [Git integration best practices](/integrations/git/best-practices) for more information.
  </Accordion>

  <Accordion title="Can I use the same dbt repository for multiple database connections?">
    Yes. This is common when using different credentials for different environments, such as using separate Snowflake accounts for different departments.

    <Note>
      You must configure [dbt settings and environment variables](/integrations/dbt/environments) for each individual connection to ensure models map to the correct database and schema.
    </Note>
  </Accordion>

  <Accordion title="Does Omni support dbt mesh architecture across separate Git repositories?">
    No. Currently, Omni supports one dbt repository per database connection. If your architecture relies on multiple interconnected projects in separate repositories, Omni cannot ingest all projects into a single connection at this time.
  </Accordion>
</AccordionGroup>


# Triggering dbt syncs in Omni
Source: https://docs.omni.co/integrations/dbt/syncing-dbt

How Omni schema refreshes and dbt syncing work together to keep your data warehouse, transformation logic, and BI layer in sync.

Omni pulls context from your dbt project into your model, so the descriptions, SQL, and dependencies you maintain in dbt are available to everyone querying in Omni. This allows you to keep definitions in one place, ensuring analytics engineers, analysts, and business users share a single source of truth for what a field or table means.

Two operations keep Omni current with your database and dbt; while the terms are often used interchangeably, they do different jobs:

* **dbt syncs** regenerate the dbt manifest from the selected [dbt environment](/integrations/dbt/environments) and Git branch, locate your dbt models in the database, and pull the model metadata into the corresponding Omni views. They do not scan the database, and therefore do not include structural changes.
* **Schema refreshes** inspect your connected database, identify structural changes, and update the associated Omni model to match. For example, if you add a new column in the warehouse, a schema refresh will pull it into Omni. When an Omni connection has dbt enabled, a schema refresh also performs a dbt sync.

## What dbt syncs pull in

Omni includes some metadata in every dbt sync, while the rest depends on the connection's dbt settings. See the [dbt metadata reference](/integrations/dbt/metadata-reference) for more information, including the metadata Omni excludes.

## Requirements

To sync dbt with Omni, you'll need:

* A connection with [dbt configured](/integrations/dbt/setup)
* **Modeler** or **Connection Admin** permissions on the Omni model

## Triggering dbt syncs

When nothing has changed in the warehouse — you edited a description, added a tag, switched to a different dbt branch, or changed an environment's settings — you don't need a full schema refresh. You can sync dbt on its own from the dbt IDE.

1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).

2. If your organization has more than one model, click the model you want to work with in the list to open the model IDE. If you have only one model, Omni opens it automatically.

3. In the model IDE, click the <DbtIdeIcon /> icon in the sidebar.

4. Click **Sync** at the top of the file list to open the **Sync** page:

   <Frame>
     <img alt="Highlighted Sync settings in the dbt IDE" />
   </Frame>

5. Check that **dbt environment** and **dbt git branch** point at the build you want Omni to read.

   Both selectors require an active Omni branch. The production environment always uses the repository's default branch, so its branch selector stays disabled.

   <Warning>
     Unless [Branch-based schema refresh](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) is enabled, syncing the **production** environment from a branch applies dbt across all models, not only the current branch.
   </Warning>

6. Click **Sync now**. If you changed the environment or branch, the button reads **Save and sync** instead and does both.

<Tip>
  Omni tells you when a sync is due. If the environment has never been synced or its settings have changed since the last sync, you'll see a notice on the **Sync** page.
</Tip>

## Triggering schema refreshes

Run a schema refresh whenever a dbt run changes the structure of your warehouse, such as adding a model or adding, renaming, or removing columns. On a dbt-enabled connection, a schema refresh also runs a [dbt sync](#dbt-sync).

Schema refreshes happen at the connection level, so the steps are the same whether or not you use dbt. See [Schema refreshes](/modeling/develop/schema-refreshes) to learn how to trigger a refresh manually or on a schedule.

To automatically update Omni, use Omni's APIs to trigger a refresh as the last step of your orchestration workflow:

* Call the [Refresh schema API](/api/models/refresh-schema) immediately after a successful `dbt run`. By default, a schema refresh triggers a direct commit to your integrated Git branch to keep your model files in sync with the database.
* Define [cache policies](/modeling/models/cache-policies) (e.g., 24 hours) and use the [Reset cache API](/api/models/reset-cache) to reset the cache specifically when your warehouse jobs complete.

## Checking metadata freshness

<SideBySide alt="Latest sync status in the dbt IDE">
  Use the **dbt Sync** page to see when the metadata for a dbt environment was last updated. The **Status** section on the right side of the page shows when the environment's last sync ran, the git branch and commit that the sync built from, and whether the sync was part of a schema refresh.
</SideBySide>

## Troubleshooting

If you notice a discrepancy between your warehouse and Omni, check these areas:

* **dbt sync issues** - In the dbt IDE, click **Sync** to see what the last sync couldn't translate, including dbt models that Omni couldn't match to a view. See [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) for how to work through them.
* **Model version history** - Click the <Icon icon="clock" /> icon in the model IDE to see a chronological list of what changed and who triggered the refresh. See [Viewing and restoring model versions in the model IDE](/modeling/develop/history) for more information.

## Common questions

<AccordionGroup>
  <Accordion title="Do dbt syncs read all the files I see in the dbt IDE?">
    No. The dbt IDE file tree shows your whole dbt project, including macros, tests, and files that aren't dbt resources at all. Browsing a file there does not mean a sync reads it.

    Macros are the exception: Omni runs dbt to build the manifest, so `generate_schema_name` and `generate_database_name` decide where Omni looks for each model's table.
  </Accordion>

  <Accordion title="Does Omni support custom schema-naming macros?">
    Yes. Omni runs the dbt compiler directly. It detects and handles custom `generate_schema_name()` macros, applying them based on your dbt environment parameters in Omni.

    * **Production** - Maps to standard schemas (e.g., `marts`, `reports`).
    * **Development** - Maps to prefixed schemas (e.g., `dbt_blobby_marts`).
  </Accordion>

  <Accordion title="Why are my column descriptions different from dbt or my database?">
    When column descriptions differ between your dbt instance and your data warehouse's catalog, Omni prioritizes dbt's column descriptions. If descriptions are edited in Omni, Omni prioritizes those descriptions.
  </Accordion>

  <Accordion title="What happens if a column is renamed in dbt?">
    Upon refresh, Omni pulls in the new name automatically. The updated field will be available in your topics, but existing workbook references to the old name will break.

    Use the [Content Validator](/modeling/develop/content-validator) to find and bulk-replace broken references across your workbooks. You can open a branch to make these fixes safely, then merge once everything is working as expected — rather than making changes live.
  </Accordion>

  <Accordion title="Can dbt constraints be used with views?">
    In many warehouses, constraints are applied to tables rather than views. If your dbt project outputs views, define constraints at the model level in dbt so Omni can still inherit that logic, even if the warehouse doesn't enforce them on the view.
  </Accordion>

  <Accordion title="Does Omni automatically infer primary keys from dbt tests?">
    No. While a combination of `unique` and `not_null` tests is logically equivalent to a primary key, Omni does not infer primary key status from these tests. Instead, Omni identifies a primary key through:

    1. dbt constraints, which are included in dbt syncs when **Auto-generate primary keys and relationships from dbt constraints** is enabled in the connection's dbt tab.
    2. Primary keys defined on the object in your database
    3. Manually adding the primary key in Omni
  </Accordion>

  <Accordion title="How can dbt metadata help with Omni's AI?">
    Omni pulls dbt metadata into your model in ways that directly improve AI accuracy. For example, integrated descriptions are used for [AI context](/modeling/develop/ai-optimization), which can help the Omni Agent generate more accurate queries.
  </Accordion>
</AccordionGroup>


# Swapping dbt environments with virtual schemas
Source: https://docs.omni.co/integrations/dbt/virtual-schemas

Unlock dbt environment switching with Virtual Schemas.

Virtual schemas are a powerful abstraction layer in Omni that decouple your modeling logic from specific physical database locations. Think of virtual schemas as a way to swap out the physical tables in your SQL queries for a variable that you can then use to switch in and out different dbt environments.

By using the `omni_dbt` prefix, you can build workbooks and topics once and dynamically swap the underlying data source between dbt environments - like `production` and a personal `dev` schema - without breaking your content.

<Warning>
  **Omni strongly recommends enabling virtual schemas before you begin building Omni**. You can enable them later, but doing so will require [migrating existing content](#migrate).
</Warning>

## Requirements

To set up or migrate to virtual schemas, you'll need:

* **Connection Admin** permissions on the Omni connection
* A [configured dbt integration](/integrations/dbt/setup)

## Setting up virtual schemas

<Steps>
  <Step title="Enable the integration">
    1. In Omni, click **Connections**.
    2. Locate the connection you want to work with.
    3. Click the **dbt** tab.
    4. Toggle on **Enable Virtual Schemas**.

    Omni will automatically generate a new version of your schemas prepended with `omni_dbt_`.

    You will need to build your model from views in the `omni_dbt_` version of your schema for dbt virtual schemas to work.

    It's recommended you only include these schemas going forward, by adding the following to your [model file](/modeling/models/included-schemas):

    ```yaml theme={null}
     included_schemas: ["*omni_dbt*"]
    ```
  </Step>

  <Step title="Configure dbt environments">
    To use the environment toggle, Omni needs to mirror your dbt runner configuration (e.g., dbt Cloud).

    Every developer who wants to use environment switching must have their own environment. See [Configuring dbt environments](/integrations/dbt/environments) for step-by-step instructions.
  </Step>

  <Step title="Confirm Omni model and dbt source mappings">
    In the model IDE, confirm that all models Omni currently accesses are correctly mapped to their dbt sources.

    If this does not pass automatically, refresh your schema and see the debugging steps in [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues).
  </Step>
</Steps>

## Migrating existing content

If you already have a model built on physical schemas, you'll need to migrate your logic to the virtual layer to unlock environment switching.

<Note>
  Before you start, check for [dbt sync issues in the dbt IDE](/integrations/dbt/debugging-sync-issues). Make sure that all the models Omni currently accesses are mapped to the correct dbt sources.
</Note>

<Steps>
  <Step title="Enable the integration">
    1. In Omni, click **Connections**.
    2. Locate the connection you want to work with.
    3. Click the **dbt** tab.
    4. Toggle on **Enable Virtual Schemas**.
  </Step>

  <Step title="Migrate your semantic logic">
    Next, you'll use Omni's migration tool to copy the existing semantic logic from your physical schemas to the new virtual ones.

    <Warning>
      **Before beginning the migration**, note that:

      * **Logic migrations can't be performed in branches, meaning production users could be impacted.** Run the migration during a low-traffic period to minimize disruption.
      * **Existing dashboards and topics won't be updated**. You'll migrate content and topics in the next step.

      **If you skip this step**, any hardcoded schema references in existing content will remain pointed at physical schemas and the environment toggle will have no effect on them.
    </Warning>

    To start the migration, navigate to the connection's **dbt** tab and click the **Run migration** button.

    The migration scans all existing modeling layers and for every view file and relationship that existed under your physical dbt-managed schemas, it creates a one-to-one copy under the new `omni_dbt_` prefixed virtual schema names. Specifically:

    * **View files** — Every view is recreated with the `omni_dbt_` prefix.
    * **Relationships/joins** — Any joins you previously built are duplicated onto the corresponding virtual schema views.
    * **Shared model logic** — Things like custom field definitions, measures (e.g. sum of revenue), labels, etc. are carried over to the virtual schema version.
  </Step>

  <Step title="Verify the migration results">
    Navigate to the model IDE and look for a **Virtual Schemas** section. Database views accessible by Omni but not mapped to a specific dbt model will fall under the generic `omni_dbt` virtual schema.
  </Step>

  <Step title="Migrate your Omni content">
    1. Open an [Omni branch](/content/develop/branch-mode). This ensures that users won't be disrupted while you perform the content migration.
    2. In the model IDE, update your topics' [`base_view`](/modeling/topics/parameters/base-view) references to use the `omni_dbt_` views.
    3. Use the [Content Validator](/modeling/develop/content-validator) to find and replace physical schema references with virtual ones across all dashboards and tiles.
    4. Within your branch, point Omni to a dev schema to verify that changes in your dbt development branch are reflecting correctly. Then:

       1. Open a workbook that uses a virtual schema.
       2. Open the [Query Inspector](/analyze-explore/workbook-inspector) by clicking the <Icon icon="bug" /> icon in the workbook's sidebar.
       3. Check that the underlying table name switches to the dev schema you selected in the dbt development settings page.
  </Step>

  <Step title="Clean up and go live">
    1. Once validated, hide the physical schemas to keep your model clean. Add the following to your [model file](/modeling/models/included-schemas):

       ```yaml theme={null}
       included_schemas: ["*omni_dbt*"]
       ```
    2. Merge your Omni branch.
  </Step>
</Steps>

## Testing new dbt models in Omni branches

1. Run `dbt build` in your local or cloud dev environment.
2. Push your dbt code to a branch (e.g., `git push origin new-feature`).
3. In Omni, create an Omni branch.
4. In the Omni branch header, click the dbt settings button to navigate to your connection's dbt development settings page where you can select your dbt dev environment.
5. Return to your Omni branch and click **Model > Refresh schema**.
6. In the dbt IDE, point to the dbt branch you want to align your Omni branch to.

<Tip>
  When testing in a branch, use the [Query Inspector](/analyze-explore/workbook-inspector) to confirm that switching to your dev environment successfully re-points the query from `PROD.CORE` to `DEV_USER.CORE`.
</Tip>

## Using virtual schemas with partial dbt builds

<Note>
  If you have a new dbt developer environment or are using deferrals already, you might be missing tables from your developer schema if you're seeing partial builds.
</Note>

By default, Omni needs all tables in a model to exist in your physical schema to map them to virtual schemas. If you only build a few models in dev, the rest of the virtual schemas will disappear.

### Enable deferral (recommended)

The recommended approach is to enable the **Enable deferral** checkbox when configuring your dev environment in Omni. When enabled, Omni automatically falls back to production builds for models not built in your dev environment, so you can run partial builds without needing to create clones or build the full project.

For example, if you only build a subset of models in your dev schema, Omni will use the production version for everything else without any additional setup.

See [Configuring dbt environments](/integrations/dbt/environments) for more information about setting up dev environments.

<Tip>
  For partial builds, enable deferral when you routinely build only the models you're actively changing, rather than running full `dbt build` commands.
</Tip>

### Using dbt clone for zero-copy clones

While [Omni's native deferral feature](#deferrals) handles most use cases, `dbt clone` remains a complementary option for creating zero-copy clones of production objects directly in your warehouse. This can be useful when you want physical copies of production tables in your dev schema:

<Tabs>
  <Tab title="dbt Cloud" icon="cloud">
    <Note>
      Deferrals require at least one successful job run in the designated production environment.
    </Note>

    1. In dbt Cloud, enable the **Defer to staging/production** option in your development environment settings. This designates your production job as the reference point.
    2. Once enabled, run `dbt clone` from the dbt Cloud IDE. On warehouses that support it (like Snowflake), this creates zero-copy clones of all production objects in your development schema, creating the "stubs" or references Omni needs to see the entire project.
    3. Once cloned, you can run `dbt build -s <your_model>` for just the specific models you are changing.

       Omni will now see the entire schema - the cloned production tables and your specific dev changes - allowing you to validate your work without a full project run.
  </Tab>

  <Tab title="dbt Core" icon="database">
    1. Download the artifacts from you most recent production run. Production artifacts are typically available from your CI/CD pipeline, an S3 bucket, or your dbt Cloud job's artifact storage.
    2. Pass the artifacts to `dbt clone` using the `--state` flag:

       ```bash theme={null}
       dbt clone --state /path/to/production/artifacts
       ```
    3. Once cloned, you can run `dbt build -s <your_model>` for just the specific models you are changing.

       Omni will now see the entire schema - the cloned production tables and your specific dev changes - allowing you to validate your work without a full project run.
  </Tab>
</Tabs>

See the [Troubleshooting section](#missing-tables-dbt-clone) if tables are missing after going through the above steps.

## Common questions

<AccordionGroup>
  <Accordion title="Why use virtual schemas?">
    While dbt metadata like descriptions and primary keys automatically flows into Omni's standard schemas, virtual schemas unlock advanced environment management.

    * **Environment swapping:** Toggle your Omni branch to point to a development schema (e.g., `dbt_blobby`) to test new logic before merging to production.
    * **Stable references:** Dashboards built on virtual schemas use a stable reference (e.g., `omni_dbt__orders`). When you switch environments, Omni automatically adjusts to fetch data from your dev schema, but the dashboard itself will remain unchanged.
    * **Safety:** You can validate dbt changes in an Omni branch before they hit production, ensuring dashboards don't break after a dbt deployment.
  </Accordion>

  <Accordion title="Is it best practice to use virtual schemas instead of standard schemas?">
    Yes. Virtual schemas prevent your content from being tied to a single physical database location, so you can switch between environments without rebuilding anything. Build once on the virtual layer and swap dynamically as needed.
  </Accordion>

  <Accordion title="Will using virtual schemas make it harder to see where data comes from?">
    No. You can still view the source SQL and dbt lineage directly in the Omni IDE to trace the exact database and schema a model originated from.
  </Accordion>

  <Accordion title="Which schemas get a virtual schema?">
    Only tables built and managed by dbt will have a corresponding virtual schema. Data that comes from other sources — CSV uploads, direct pipeline ingestion, and so on — won't have a virtual schema. You'll always use the physical schema for that data.
  </Accordion>

  <Accordion title="How do I verify which environment is being queried?">
    The raw SQL in the [SQL editor](/analyze-explore/sql) may show the virtual alias.

    To see the physical path being queried, check the [Query Inspector](/analyze-explore/workbook-inspector). It displays the final, compiled SQL sent to your warehouse, including the specific dev or prod database and schema names.
  </Accordion>

  <Accordion title="How do I iterate on dbt models without pushing to production?">
    You can use dynamic schemas and dbt environments to point Omni at your development or feature-branch schemas. This allows you to immediately validate changes in Omni without waiting for a production deployment.
  </Accordion>

  <Accordion title="Does dbt clone override local changes?">
    No. Cloning creates zero-copy clones of all production objects in your development schema. If you then run `dbt build` or `dbt run` on a specific model, dbt replaces that clone with the table or view built from your code. Omni picks up the new version automatically.
  </Accordion>

  <Accordion title="Should I keep virtual schemas or turn them off?">
    * **Keep it if:** You plan to preview how dbt code changes will impact your dashboards before pushing them to production.
    * **Turn it off if:** You only have one dbt environment and never plan to use Omni for development preview work.

      Note that even if you turn off virtual schemas, dbt metadata like descriptions and primary keys will still flow into your standard schemas.
  </Accordion>

  <Accordion title="Why doesn't the SQL change in the SQL editor when I swap environments?">
    Virtual schemas use consistent aliases to keep references stable. To verify the query is hitting your dev schema, check the [Query Inspector](/analyze-explore/workbook-inspector) to see the final, compiled SQL sent to your warehouse.
  </Accordion>

  <Accordion title="How are omni_dbt* schema names determined?">
    Omni derives each virtual schema name from the [custom schema](https://docs.getdbt.com/docs/build/custom-schemas) configured on the dbt model. The custom schema is different from the target (or "default") schema — it's the `+schema:` config you set in `dbt_project.yml` or in a model's config block.

    Where Omni places models depends on if the model has a custom schema:

    * **No custom schema** - Placed in `omni_dbt`
    * **Custom schema** - Placed in `omni_dbt_<custom_schema>`

    For example, given the following `dbt_project.yml`:

    ```yaml theme={null}
    models:
      my_project:
        marketing:
          +schema: marketing
        finance:
          +schema: finance
        staging:
          # no custom schema set
    ```

    Omni generates these virtual schemas:

    * Models under `marketing/` → `omni_dbt_marketing`
    * Models under `finance/` → `omni_dbt_finance`
    * Models under `staging/` (no custom schema) → `omni_dbt`
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="dbt environments aren't working in Omni">
    This is almost always a configuration issue with the environments that aren't working. Each developer needs their own separate environment entry in Omni; a working environment for one person doesn't carry over to others.

    For each person, check the following:

    * **Missing environment entry:** Every developer needs their own entry, added under **Environments** on the dbt IDE's **Sync** page. If an entry doesn't exist for a given developer, Omni has nothing to resolve to when they switch environments.
    * **Incorrect default schema:** Each developer typically builds into their own personal schema in dbt (e.g., `dbt_blobby`). If the Omni connection's **Default schema** doesn't match where that developer's dbt builds, Omni will look in the wrong place.
    * **Incorrect target name:** The **Target name** dbt setting in Omni must exactly match the target that developer uses when running dbt (e.g., `dev`, `default`, or a custom value). See the [Configure dbt environments](#setup) section for guidance on where to find this in dbt Cloud.
    * **dbt hasn't been run for that developer yet:** If a developer has never run `dbt build` or `dbt run` in their personal schema, there will be nothing for Omni to find.

      Once the environment is configured, open the dbt IDE's **Sync** page, select that environment, and click **Sync now**.
    * **Missing warehouse permissions:** The Omni service account must have access to each developer's personal database and schema. If it doesn't, you'll see a warning like `"Database 'DEV_BLOBBY' does not exist or not authorized"` in the health check.

      To verify, open the SQL editor in an Omni workbook and run `SHOW DATABASES`. If the developer's database (e.g., `DEV_BLOBBY`) doesn't appear in the results, the service account hasn't been granted access to it. Confirm the service account has been granted the correct permissions on that developer's database and schema, then re-run the health check.
    * **Missing environment variables:** If your dbt project uses custom environment variables to control schema names, those need to be added per environment in Omni.

    To diagnose quickly, open the dbt health check for the failing environment. It will tell you whether the issue is a configuration mismatch or a permissions problem.
  </Accordion>

  <Accordion title="Virtual schemas are empty">
    Virtual schemas may be empty for a few reasons:

    * **Missing materialization:** Omni can only see models that have been physically built in your warehouse. Ensure you executed `dbt run` or `dbt build` in that specific environment.
    * **Schema refresh needed:** If the data exists in your warehouse but isn't showing in Omni, trigger a schema refresh. See [Schema refreshes](/modeling/develop/schema-refreshes) for instructions.
    * **Permissions:** The database user Omni uses must have `USAGE` and `SELECT` permissions on your personal development schema.
    * **Inclusion filters:** If your model file has [`included_views`](/modeling/models/included-views) or [`included_schemas`](/modeling/models/included-schemas) defined, you must explicitly add `"omni_dbt*"` to that list.
  </Accordion>

  <Accordion title="dbt environment switching not working on dashboard">
    dbt environment switching only works for views built on the `omni_dbt_` (virtualized) layer. If your topic or SQL shows a hardcoded schema name that doesn't start with the virtual prefix, the environment switch will be ignored.
  </Accordion>

  <Accordion title="Missing tables after running dbt clone">
    If `dbt clone` runs but certain tables still error out or don't appear in Omni:

    * **Check the Omni user's permissions**. Ensure the database user Omni uses (or your individual OAuth user) has `SELECT` grants on the production schemas being cloned.
    * **Check production health**: Verify that the models exist and have had a successful run in your production environment. If a model is missing from the production manifest, it cannot be deferred or cloned.
    * **Check your environment settings**. If you have multiple environments (e.g., Staging and Prod) and are using dbt cloud, check that your dbt settings are deferring to the environment that actually contains your data before running the `dbt clone` command.
  </Accordion>

  <Accordion title="Table not found error after switching to dev environment">
    Omni expects every model referenced in an environment to physically exist in the target schema. If you've only built modified models, Omni can't resolve the missing tables.

    Enable deferral for your dev environment to automatically fall back to production builds for unbuilt models. Alternatively, run `dbt clone` before switching environments in Omni to create zero-copy clones of all production tables. If errors persist, confirm your database user has permission to read the production schema — see [dbt connection setup](/integrations/dbt/setup) for more information.
  </Accordion>
</AccordionGroup>

## Next steps

* [Schema refreshes](/modeling/develop/schema-refreshes) — Sync model changes after switching environments.
* [Content Validator](/modeling/develop/content-validator) — Find and bulk-replace schema references across content.
* [Connection environments](/connect-data/dynamic-environments) — Set up dynamic environments for safe testing.


# Git integration best practices
Source: https://docs.omni.co/integrations/git/best-practices

Best practices for working with Omni's Git integration, including branch strategy, keeping pull requests up to date, conflict resolution, and common pitfalls.

When you connect Omni to Git, you get the power of version control, collaboration, and change tracking, but you may also encounter some quirks and pitfalls. A little planning up front can save you from frustration and unexpected behavior.

This guide walks through best practices for working with Omni’s Git integration so you can keep your models (and your sanity) intact.

## Edit models in the model IDE

While models can be edited outside of the model IDE, **we don't recommend it.** Developing in the model IDE will prevent issues from invalid YAML, such as unexpected commits or, in some cases, even reverts.

We recommend using Omni's IDE to develop the model using Omni YAML. The built-in IDE will make validating the YAML straightforward, which will allow you to quickly identify syntax issues - something that isn't currently possible in external IDEs today. This can help cut down on issues surrounding syntax on merges, which can cause Omni to reject the change due to invalid syntax.

For example:

1. A commit containing invalid YAML is merged to the repository's default branch
2. Omni attempts to perform a schema refresh
3. Schema refresh fails due to the invalid YAML
4. Omni authors a commit that resets Git to Omni's current state

In this example, the changes that Omni commits to reset Git will not only remove the problematic YAML, but it will also overwrite any other changes.

## Keep pull requests short-lived and up to date

When a pull request merges, Omni promotes the corresponding Omni branch onto the shared model — it does not apply Git's merge result. Every model file stored on the Omni branch replaces the shared version of that file, and the most recently merged branch wins.

An Omni branch only picks up newer shared model changes when commits are pushed to its open PR, so a PR that sits open for weeks can overwrite changes that merged in the meantime. See [Merging a PR reverts changes from another branch](/integrations/git/troubleshooting#merge-revert) for more information.

To avoid this issue:

* **Merge promptly.** Open PRs from branches that are ready to review and avoid letting reviewed PRs sit while other changes merge.
* **Update stale PRs before merging.** Push a commit or merge the base branch into the PR branch (for example, GitHub's **Update branch** button) so Omni re-syncs the branch against the current shared model. You can also open the branch in the model IDE, save a change, and click **Update pull request**.
* **Avoid parallel branches that touch the same files.** Uploaded CSVs, shared views, and frequently edited topics are common collision points. If two open branches carry the same file, whichever merges second will win.
* **Check the merge afterward.** For any long-lived PR, review the **Webhook merge** entry in the [model history](/modeling/develop/history) after merging to confirm the diff only contains the changes you expected.

## Keep Omni and dbt separate in monorepos

While you can use a monorepo to connect Git and dbt to Omni, there are a few things you should keep in mind:

### Use Gitignore

**In your dbt project**, add your Omni files to [`Gitignore`](https://git-scm.com/docs/gitignore) to prevent pulling your Omni files into where you edit dbt files. It’s possible that the Omni model YAML could be autolinted, resulting in a number of formatting changes that could cause issues in Omni. For this reason, we [strongly recommend editing your models in Omni's model IDE](#edit-models-in-the-model-ide).

### Use separate branches for Omni and dbt

**Make Omni model and dbt changes in separate branches**. Currently, Omni’s Git integration promotes the Omni branch when a pull request is merged. If dbt and Omni changes are merged at the same time, the dbt changes won’t have a chance to build first.

To avoid this, you could use a workflow like the following:

1. Create a new Omni branch to develop against dbt
2. Use a dbt virtual environment to develop against your Omni model
3. Merge the dbt branch
4. Refresh the Omni schema model
5. Switch the Omni branch to point to the production dbt environment; verify changes
6. Promote the Omni model

## Options for protected branches

Protecting the main branch of a repository from direct commits is a basic best practice in Git. If you have branch protection rules enabled, you have a few options for working with Omni’s Git integration:

* **Allow deploy keys to bypass branch protection rules.** This approach is the most permissive as it allows Omni to directly commit to the default branch. However, other users with access to the repository would still not be allowed to directly push to the default branch.
* **Enable Branch schema refresh & Require system syncs.** When these Omni settings are enabled, Omni will open a pull request with schema refresh changes instead of directly committing them to the default branch. These changes would have to be approved to be merged into the repository’s default branch.

**Note:** Some branch protection rules - for example, branch names cannot contain specific characters - are not enforced by Omni.


# git follower mode best practices
Source: https://docs.omni.co/integrations/git/follower-mode/best-practices

Best practices for managing git follower mode deployments in Omni, including sync strategies and conflict prevention tips.

Omni’s git follower mode gives you a powerful way to manage model development across environments while keeping them in sync. To ensure smooth deployments, we recommend following the best practices outlined in this guide.

## git setting configuration

Setting up follower mode involves configuring a few [git settings](/integrations/git/settings) for both the leader and follower models:

* [**Base branch**](/integrations/git/settings#base-branch) - The target branch for Omni pull requests
* [**Always create branches**](/integrations/git/settings#always-create-branches) - When enabled, a corresponding Omni branch is created when a pull request is opened, updated, or merged in the connected repository.
* [**Git follower mode**](/integrations/git/settings#git-follower-mode) - Enables follower mode. The model will be read only and can only be updated by merging pull requests to the base branch.
* [**Model path**](/integrations/git/settings#model-path) - The path to the model files in the connected repository. **The leader and follower(s) must match.**

The following table details Omni's recommendations for each of these settings:

| Setting                                                                         | Leader            | Follower                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Base branch**](/integrations/git/settings#base-branch)                       | `main`            | **For SDLC use cases**, use the name of the environment that corresponds to the branch, like `prod` or `staging`.<br /><br />**For multi-region**, use the name of the region that corresponds to the branch, like `us` or `ireland`. |
| [**Always create branches**](/integrations/git/settings#always-create-branches) | Not enabled       | **Enabled**. This ensures that Omni detects changes made to the follower's base branch and creates a corresponding Omni branch.                                                                                                       |
| [**Git follower mode**](/integrations/git/settings#git-follower-mode)           | Not enabled       | **Enabled**. Required to indicate that the model is a follower.                                                                                                                                                                       |
| [**Model path**](/integrations/git/settings#model-path)                         | No recommendation | Set to the same folder that contains the leader model files in the git repository. For example, if the leader model files are in a folder named `blobs_r_us`, set this to `blobs_r_us`.                                               |

## Development workflow

When developing against models with git follower mode enabled, it’s important to follow a clear workflow that keeps your environments aligned and predictable. Omni recommends a two-part process: first, deploy and develop changes in the leader model, then refresh, test, and promote those changes through the follower. This ensures you can iterate safely while maintaining stability in the "live" models.

<Steps>
  <Step title="Part 1: Deploy and develop the leader">
    1. **In Omni:**

       1. Open a branch against the **leader** model.
       2. Make a change to the model.
       3. When finished, click **Create pull request** in the branch header. This will prompt you to create a pull request against the **leader's base branch** in the git repository. Omni recommends using the `main` branch.

    2. **In the git repository**: Merge the pull request, which will merge the branch into the leader's base branch.

    3. **In Omni:** Verify that the changes you merged are available in the **leader** model.
  </Step>

  <Step title="Part 2: Refresh, test, and deploy the follower">
    1. **In Omni**: Perform a schema refresh on the **follower** model. This step is required to ensure that the follower's schema model matches the schema model of the leader.

    2. **In the git repository**:

       1. Create a new branch off of the **leader's base branch**. Omni recommends using a name like `release-to-prod-YYYYMMDD`, where `YYYYMMDD` is a date. For example, `release-to-prod-20250901`
       2. Create a pull request that will merge the `release-to-prod-YYYYMMDD` branch into the **follower's base branch**. With the **Always create branches** setting enabled for the model in Omni, this will create a branch in Omni with the same name.

    3. **In Omni**:

       1. Navigate to the follower model and open the model IDE.
       2. Open the `release-to-prod-YYYYMMDD` branch.
       3. Test the changes, including checking the [Content Validator](/modeling/develop/content-validator) for issues.

    4. **In the git repository**: Merge the pull request, which will merge the branch into the **follower's base branch**.

    5. **In Omni:** After the pull request is merged, confirm that the changes are present in the **follower** model.
  </Step>
</Steps>


# git follower mode
Source: https://docs.omni.co/integrations/git/follower-mode/index

Centralize model development and deploy to multiple regions or environments using Omni's git follower mode with leader/follower sync.

The git integration's Follower Mode allows you to centralize the development of a model and deploy it to multiple regions like the US and EU, or develop models using a SDLC (Software Development Lifecycle) approach.

## How it works

Follower mode works by specifying one Omni model as a **leader** and another model as a **follower**. The follower is updated when changes occur to the leader, allowing you to create a clear separation between models without manual intervention or the risk of drift.

* All development happens in the **leader**, against its own git base branch
* The **follower** is read-only, meaning direct changes can't be made to the model
* Promotion to the **follower** happens only by creating a pull request that merges changes from **leader's base branch** into the **follower's base branch**. Once merged, Omni automatically applies the changes to the follower model.

## Use cases

Follower mode is useful for:

* [Creating development & production environments](#development-and-production-environments)
* [Deploying a model to multiple regions or Omni organizations](#multi-region-or-organization-deployment)

### Development and production environments

This approach allows you to implement a permanent SDLC solution, where you develop against one model (the **leader**) and then promote vetted changes to production (the **follower**). This ensures that the production model used to build content remains stable, consistent, and protected from ad-hoc changes.

### Multi-region or organization deployment

In these cases, you may be subject to regulations that restrict where your data can reside. Instead of manually applying changes to multiple models, you can use follower mode to develop against one model (the **leader**) and then set up **followers** that will automatically absorb the changes.

## Model requirements

Follower mode should only be used with models that:

* Have the same underlying schema structure, and
* Are kept in sync (schema refreshes)

Models **do not** need to be in the same database connection or even the same Omni organization.

## Setup and best practices

Ready to get started?

* Set up [git follower mode](/integrations/git/follower-mode/setup) with step-by-step instructions
* Learn about Omni's recommended [best practices](/integrations/git/follower-mode/best-practices) for follower mode, including how to develop models


# Configuring git follower mode
Source: https://docs.omni.co/integrations/git/follower-mode/setup

Set up git follower mode in Omni by designating leader and follower models for centralized development and multi-environment sync.

Omni’s git follower mode helps you centralize model development while keeping multiple environments in sync. By designating one model as the leader and others as followers, you can make changes in one model and easily apply them to other models.

This guide demonstrates how to set up follower mode for a **development-to-production workflow**, but you can also use these instructions for multi-region or multi-organization deployments.

## Requirements

To follow the steps in this guide, you'll need:

* **In Omni**:

  * [**Connection Admin permissions**](/administration/users/permissions) for the models you want to connect to git
  * **Models with identical schemas**, meaning that the schemas and tables powering the models have the same structure

* **In your git provider**:

  * **An existing git repository** in GitHub, GitLab, or Azure DevOps

  * **Permissions in your git provider that allow you to complete the following**. Refer to the documentation for your git provider for information about their user permissions:

    * Add webhooks to repositories
    * Add deploy/SSH keys to repositories

## Setup

<Steps>
  <Step title="Set up the leader">
    The first step is to set up the **leader** model. This is where you'll make direct changes to the model, such as adding topics, curating fields, and so on.

    1. In Omni, navigate to and open the model you want to use as the leader.

    2. Follow the steps in the [git integration guides](/integrations/git/setup) to connect the model to the git repository.

    3. After you finish setting up the repository, configure the following Omni git settings:

       * **Base branch** - Enter the name of the git branch Omni should use for pull requests. Omni recommends you use the default branch, which is typically `main`.
       * **Model path** - Enter the path to the model files in the repository. For example, if you entered `blobs_r_us`, Omni will look for model files in a `/blobs_r_us` folder in the repository.
  </Step>

  <Step title="Set up the follower">
    The next step is to set up the **follower** model. This is a **read-only** model that will absorb changes from the **leader**.

    1. In Omni, navigate to and open the model you want to use as the follower.

    2. Follow the steps in the [git integration guides](/integrations/git/setup) to connect the model to the same git repository you used to set up the leader. **This includes adding a second deploy key and webhook.**

    3. In the git repository, create a new branch to use as the Omni base branch. In our dev to prod example, we'll name the branch `prod`.

    4. After you finish setting up the repository, configure the following Omni git settings:

       * **Base branch** - Enter the name of the branch you created in step 3. For example, `prod`.
       * **Always create branches** - Enable this setting, which will ensure that Omni detects and applies changes merged to the **Base branch**.
       * **Git follower mode** - Enable this setting, which will designate the model as a follower.
       * **Model path** - Enter the path to the model files in the repository. **The value of this setting must match the value for the leader.**
  </Step>

  <Step title="Verify settings configuration">
    Before you test out the setup, take a moment to verify the setting configuration for both the leader and follower.

    In our dev to prod example, the settings for the leader and follower look like this:

    | Setting                    | Leader value | Follower value |
    | -------------------------- | ------------ | -------------- |
    | **Base branch**            | `main`       | `prod`         |
    | **Always create branches** | Not enabled  | Enabled        |
    | **Git follower mode**      | Not enabled  | Enabled        |
    | **Model path**             | `blobs_r_us` | `blobs_r_us`   |
  </Step>

  <Step title="Test the setup">
    Use the following steps to perform an end-to-end test of your setup. If successful, this is also the workflow Omni recommends using for model development and deployment.

    <Steps>
      <Step title="Test leader setup">
        1. **In Omni:**

           1. Open a branch against the **leader** model. In our dev to prod example, this model would be named `dev`.
           2. Make a change to the model.
           3. When finished, click **Create pull request** in the branch header. This will prompt you to create a pull request against the `main` branch in the git repository.

        2. **In the git repository**: Merge the pull request, which will merge the branch into the repository's `main` branch.

        3. **In Omni:** Verify that the changes you merged are available in the **leader** (`dev`) model.
      </Step>

      <Step title="Test follower setup">
        1. **In Omni**: Perform a schema refresh on the **follower** model. This step is required to ensure that the follower's schema model matches the schema model of the leader.

        2. **In the git repository**:

           1. Create a new branch off of the `main` branch. Omni recommends using a name like `release-to-prod-YYYYMMDD`, where `YYYYMMDD` is a date. For example, `release-to-prod-20250901`

           2. Create a pull request that will merge the `release-to-prod-YYYYMMDD` branch into the follower's base branch. In our dev to prod example, the follower's base branch would be `prod`.

              If you enabled the **Always create branches** setting in Omni, this should create a branch in Omni with the same name.

        3. **In Omni**:

           1. Navigate to the follower model and open the model IDE.
           2. Open the `release-to-prod-YYYYMMDD` branch.
           3. Test the changes, including checking the [Content Validator](/modeling/develop/content-validator) for issues.

        4. **In the git repository**: Merge the pull request, which will merge the branch into the repository's `prod` branch.

        5. **In Omni:** After the pull request is merged, confirm that the changes are present in the **follower** model.
      </Step>
    </Steps>
  </Step>
</Steps>

## What's next?

Now that you've set up follower mode, check out the [git follower mode best practices](/integrations/git/follower-mode/best-practices) to learn how to best develop your models.


# Integrate git for model version control
Source: https://docs.omni.co/integrations/git/index

Omni's git integration allows you to sync an Omni shared model to a git repository. This is done on the model level.

<Note>
  **Looking to use GitHub repositories as AI context?** See the [GitHub AI integration](/integrations/ai/github) guide.
</Note>

Using a git integration provides added development benefits of storing backups of model files and using pull requests to create collaborative and peer reviewed changes. Additionally, it's possible to require pull requests, for those that want a more structured development lifecycle.

Enabling the git integration requires the use of [Branch Mode](/content/develop/branch-mode) for modifications to the Shared model, ensuring a structured and organized development process.

## Multiple models, one repository

Multiple Omni models can share the same git repository. When you connect additional models to a repository that's already connected to another model, they'll automatically share the repository's deploy key and webhook configuration. This simplifies management and ensures consistent behavior across all models using the same repository.

## Supported git providers

Omni's git integration currently supports the following git providers:

<CardGroup>
  <Card title="Azure DevOps" icon="microsoft" href="/integrations/git/setup/azure-devops" />

  <Card title="Bitbucket Cloud" icon="bitbucket" href="/integrations/git/setup/bitbucket-cloud" />

  <Card title="Bitbucket Data Center" icon="bitbucket" href="/integrations/git/setup/bitbucket-data-center" />

  <Card title="GitHub" icon="github" href="/integrations/git/setup/github" />

  <Card title="GitLab" icon="gitlab" href="/integrations/git/setup/gitlab" />
</CardGroup>

## Configuration

After a git repository is connected to a model, Organization Admins can configure the integration's behavior by navigating to **Model > Git Settings** in the model IDE.

For example, pull requests aren't required by default. This can be changed using the integration's settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.


# Configuring git integration settings
Source: https://docs.omni.co/integrations/git/settings

Manage git integration settings for your Omni model, including branch defaults, push behavior, and conflict resolution options.

<Note>
  Organization Admin permissions are required to access and modify a model's git settings.
</Note>

After a git repository is connected to a model, you can configure the integration's behavior by navigating to **Model > Git Settings** in the model IDE.

## Test git connection

Clicking the **Test git connection** button will test the connection's [Deploy key](#deploy-key) setup. **Note**: This doesn't currently test the repository's webhook setup.

## Unlink git

To disconnect the repository from the model, click the **Unlink git** button.

## Pull request settings

### Base branch

Defines the target branch for Omni pull requests. Omni defaults this setting to `main`, but it may be different for your repository.

If you're unsure which branch is the default for your repository, check your repository's settings page:

* [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch#changing-the-default-branch)
* [GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/default.html)
* [Microsoft Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/change-default-branch?view=azure-devops)

### Pull request required

Enabling this setting will require all changes to the model to be made through a pull request. Otherwise, changes can be directly promoted to the shared model. If you're familiar with git, this is equivalent to committing changes directly to the repository's base (default) branch.

<Tip>
  For additional control, you can define rules in the git repository that require pull requests to be reviewed and approved before they're merged. Refer to the documentation for your git provider to learn more:

  * [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging)
  * [GitLab](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
  * [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops\&tabs=browser)
</Tip>

#### Require for system syncs

Some Omni actions, such as [schema refreshes](/modeling/develop/schema-refreshes), API events, and model syncs, will automatically commit changes to the repository's [base branch](#base-branch), making them visible in the shared model. Enabling the **Pull request required > Require for system syncs** setting will require that these actions are merged via a pull request.

To use this setting, the following settings must also be enabled:

* [Pull request required](#pull-request-required)
* [Branch based schema refresh](/modeling/develop/schema-refreshes) for the connection associated with the model

<Note>
  Because this setting requires branch-based schema refresh, the connection is limited to a single shared model. See [Requiring branches for schema refreshes](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) for details and workarounds.
</Note>

### Git follower mode

Enables [follower mode](/integrations/git/follower-mode) for the model.

### Model path

The path to the model files in the connected repository. Defaults to `omni/<model-name>`. To use a custom path from the repository root, start the path with `/`, for example `/bi/models/sales`.

If follower mode is enabled, values for the leader and follower(s) must match.

### Always create branches

When the **Create Omni branches for all pull requests** setting is enabled, Omni ensures a corresponding branch exists whenever a pull request in the connected repository is opened, updated, or merged.

## Git service provider

In most cases, Omni automatically detects your git provider. Use the **Git service provider** setting to manually override the detected provider when Omni can't detect it correctly, such as when you're using a self-hosted git instance. This setting affects how Omni generates pull request URLs.

Supported providers:

* GitHub
* GitLab
* Azure DevOps
* Bitbucket Cloud
* Bitbucket Data Center

## Custom web URL

When your git repository's SSH URL goes through a tunnel or VPC, Omni may not be able to automatically generate valid web links to view pull requests or browse repository files. The **Custom web URL** setting allows you to specify an alternate HTTPS URL that Omni will use instead.

When this field is set, Omni will use the custom URL to generate:

* Pull request URLs
* Repository file browsing links

If left blank, Omni will automatically derive the web URL from the repository's SSH URL.

For example, if your repository's SSH URL is `git@github.com:your-org/your-repo.git` but it goes through a private tunnel, you can set the custom web URL to `https://github.com/your-org/your-repo` to ensure repository links work correctly.

## Authentication

### Access token

If your repository is configured with HTTPS token authentication, you can update the access token using the **Change Token** button. This is useful when:

* Your access token has expired
* You need to rotate tokens for security purposes
* You want to use a different token with updated permissions

To change the token:

1. Click the **Change Token** button.
2. Enter the new access token.
3. Click **Save** to update the connection.

The connection will be re-validated with the new token.

### Deploy key

The **Deploy key** allows Omni to read from and commit to the connected git repository when using SSH authentication. Omni supports two ways to complete deploy key setup:

* **Use the deploy key Omni generates by default** when you connect a repository, which is the key shown in the **Git settings** page. Refer to the [git integration setup guides](/integrations/git/setup) to learn how to add the public key to your repository.
* **Supply your own private key** using Omni's APIs, which allows you to rotate keys with zero downtime. Refer to the [SSH deploy key rotation guide](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.

### GitHub App

Repositories connected with GitHub App authentication are authenticated through a GitHub App installation rather than a deploy key or access token. This authentication method is only available for github.com repositories.

Commits produced using GitHub App authentication are signed and displayed as Verified in GitHub.

<Note>
  To switch authentication methods or update commit signing settings after connecting a repository, you'll need to unlink the repository and reconnect it.
</Note>

## Pull request webhook

The **Pull request webhook** settings allow Omni to be notified when pull request-related actions are taken in the repository. This is required to keep your git and Omni branches in sync. Refer to the [git integration setup guides](/integrations/git/setup) to learn how to add the webhooks to your repository.

### Webhook secret

When using SSH authentication, Omni generates a webhook secret that is used to verify webhook requests from your git provider. This secret ensures that only authorized webhook events from your repository are processed by Omni.

#### Rotating webhook secrets

<Note>
  Webhook secret rotation is only available when using SSH authentication. HTTPS token authentication does not use webhook secrets.
</Note>

Rotate your webhook secret if it has been compromised, leaked, or accessed without authorization. Common scenarios that require rotation:

* **Security incident:** Your webhook secret was exposed in logs, code, or leaked in a security breach.
* **Suspected unauthorized access:** You suspect someone has accessed your webhook secret.
* **Routine security practice:** Regular credential rotation as part of your security policy.
* **Provider notification:** Your git provider notified you that webhook secrets may have been compromised.

You can generate a new secret without unlinking and re-linking your git repository.

To rotate the webhook secret:

<Steps>
  <Step title="Open Git settings">
    Navigate to **Model > Git settings** in the model IDE.
  </Step>

  <Step title="Rotate the secret">
    In the **Pull request webhook** section, click the **Rotate secret** button.
  </Step>

  <Step title="Confirm the rotation">
    A confirmation dialog will appear warning that the current secret will stop working immediately. Click **Confirm** to proceed.
  </Step>

  <Step title="Copy the new secret">
    Copy the new webhook secret.
  </Step>

  <Step title="Update your git provider">
    Update the webhook configuration in your git provider with the new secret:

    * [GitHub](https://docs.github.com/en/webhooks/using-webhooks/editing-webhooks)
    * [GitLab](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#edit-a-webhook)
    * [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops)
  </Step>
</Steps>

<Warning>
  When you rotate the webhook secret, the old secret is immediately invalidated. You must update the webhook configuration in your git provider with the new secret to continue receiving webhook events. Until the webhook is updated, Omni will not receive notifications about pull request activity in the repository.
</Warning>


# Connect an Azure DevOps repository to Omni
Source: https://docs.omni.co/integrations/git/setup/azure-devops

Connect an Azure DevOps repository to an Omni model

Omni supports SSH authentication to connect to Azure DevOps repositories. This requires configuring both a deploy key and a webhook in Azure DevOps. For the deploy key, you can either:

* Use the deploy key Omni generates by default
* Generate your own keypair and supply Omni with the private key

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="SSH + Omni deploy key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/organizations/security/permissions?view=azure-devops) for information about user permissions.

  ## Configure SSH authentication with an Omni deploy key

  In this guide, you'll set up SSH authentication that uses the deploy key Omni generates for you.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Azure DevOps repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. Click the  option to display the repository's  URL.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Add an SSH public key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      1. Browse to the Azure DevOps web portal (ex: `https://dev.azure.com/<your-org-name>/`).
      2. Click the **User settings** icon next to your avatar in the top right corner of the page.
      3. Click **SSH public keys**.
      4. On the page that displays, click **+ New Key**.
      5. In the **Add New SSH Key** panel that displays, fill in the following:
         * **Name** - Enter a descriptive name, such as *Omni Snowflake Model*
         * **Public Key Data** -&#x20;
      6. Click **Add**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      You'll create **three** webhook subscriptions for the Azure DevOps repository:

      1. Pull request created
      2. Pull request updated with **Change** filter = **Source branch updated**
      3. Pull request updated with **Change** filter = **Status updated**

      <Steps>
        <Step title="Create the webhook subscription">
          1) Navigate to the Azure DevOps project that contains the repository you want to connect to Omni.
          2) Click **Project settings**.
          3) Click **Service hooks**, located in the **General** section of the sidebar.
          4) On the **Service Hooks** page, click the **+ icon** or **Create subscription**.
          5) On the **Service** screen, click **Web Hooks** and then **Next**.
        </Step>

        <Step title="Configure the Trigger">
          1. On the **Trigger** screen, select one of the following for the **Trigger on this type of event** field:
             1. **Pull request created**
             2. **Pull request updated** — After selecting this trigger, set the **Change** filter to **Source branch updated**
             3. **Pull request updated** — After selecting this trigger, set the **Change** filter to **Status updated**
          2. Select the **Repository** you want to connect to Omni.
          3. If the **Target branch** field displays, select the **main** branch.
          4. When finished, click **Next**.
        </Step>

        <Step title="Configure the Action">
          On the **Action** screen, fill in the fields as follows:

          * **URL** - Copy and paste the **Webhook URL** from the Omni **Git settings** page
          * **Basic auth username** - `omni`
          * **Basic auth password** - Copy and paste the **Webhook secret** from the Omni **Git settings** page
          * **HTTP headers** - The value of this field depends on the subscription you're configuring:
            1. **Pull request created** — `x-azuredevops-omni-event:created`
            2. **Pull request updated** (Change = Source branch updated) — `x-azuredevops-omni-event:update-push`
            3. **Pull request updated** (Change = Status updated) — `x-azuredevops-omni-event:update-status`

          When finished, click **Finish** to create the webhook.
        </Step>

        <Step title="Repeat steps 1-3">
          Repeat these steps for each of the three webhook subscription types.
        </Step>
      </Steps>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Your private key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/organizations/security/permissions?view=azure-devops) for information about user permissions.

  To generate the keypair and supply the private key to Omni, you'll also need:

  * An [Omni API key](/api/authentication)
  * **The shared model's `modelId`,** which you can retrieve using the [List models](/api/models/list-models) endpoint
  * **`ssh-keygen` installed locally** to generate keypairs

  ## Configure SSH authentication with your private key

  In this guide, you'll set up SSH authentication that uses the private key you generate as part of a public-private keypair.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Azure DevOps repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. Click the  option to display the repository's  URL.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Generate a new keypair">
      Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

      <Tabs>
        <Tab title="ED25519">
          ```bash wrap theme={null}
          ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>

        <Tab title="RSA">
          ```bash wrap theme={null}
          ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>
      </Tabs>

      When prompted for a passphrase:

      * **To leave the key unencrypted**, press `Enter`.
      * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

      This generates two files:

      * `omni_deploy_key` — The private key, which you'll supply to Omni
      * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

      1. Browse to the Azure DevOps web portal (ex: `https://dev.azure.com/<your-org-name>/`).
      2. Click the **User settings** icon next to your avatar in the top right corner of the page.
      3. Click **SSH public keys**.
      4. On the page that displays, click **+ New Key**.
      5. In the **Add New SSH Key** panel that displays, fill in the following:
         * **Name** - Enter a descriptive name, such as *Omni Snowflake Model*
         * **Public Key Data** -&#x20;
      6. Click **Add**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      You'll create **three** webhook subscriptions for the Azure DevOps repository:

      1. Pull request created
      2. Pull request updated with **Change** filter = **Source branch updated**
      3. Pull request updated with **Change** filter = **Status updated**

      <Steps>
        <Step title="Create the webhook subscription">
          1) Navigate to the Azure DevOps project that contains the repository you want to connect to Omni.
          2) Click **Project settings**.
          3) Click **Service hooks**, located in the **General** section of the sidebar.
          4) On the **Service Hooks** page, click the **+ icon** or **Create subscription**.
          5) On the **Service** screen, click **Web Hooks** and then **Next**.
        </Step>

        <Step title="Configure the Trigger">
          1. On the **Trigger** screen, select one of the following for the **Trigger on this type of event** field:
             1. **Pull request created**
             2. **Pull request updated** — After selecting this trigger, set the **Change** filter to **Source branch updated**
             3. **Pull request updated** — After selecting this trigger, set the **Change** filter to **Status updated**
          2. Select the **Repository** you want to connect to Omni.
          3. If the **Target branch** field displays, select the **main** branch.
          4. When finished, click **Next**.
        </Step>

        <Step title="Configure the Action">
          On the **Action** screen, fill in the fields as follows:

          * **URL** - Copy and paste the **Webhook URL** from the Omni **Git settings** page
          * **Basic auth username** - `omni`
          * **Basic auth password** - Copy and paste the **Webhook secret** from the Omni **Git settings** page
          * **HTTP headers** - The value of this field depends on the subscription you're configuring:
            1. **Pull request created** — `x-azuredevops-omni-event:created`
            2. **Pull request updated** (Change = Source branch updated) — `x-azuredevops-omni-event:update-push`
            3. **Pull request updated** (Change = Status updated) — `x-azuredevops-omni-event:update-status`

          When finished, click **Finish** to create the webhook.
        </Step>

        <Step title="Repeat steps 1-3">
          Repeat these steps for each of the three webhook subscription types.
        </Step>
      </Steps>
    </Step>

    <Step title="Supply the private key to Omni with the API">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

      <Tabs>
        <Tab title="Unencrypted keys">
          In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

          ```bash wrap theme={null}
          curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
            -H "Authorization: Bearer <YOUR_API_TOKEN>" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
          ```

          Replace the following variables:

          * `<your-subdomain>` - Your Omni subdomain
          * `<MODEL_ID>` - The shared model's UUID
          * `<YOUR_API_TOKEN>` - Your Omni API key

          A successful response will include the derived public key in the `publicKey` field.
        </Tab>

        <Tab title="Passphrase-protected keys">
          1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
          2. Run the following to create a plain shell variable for the passphrase:

             ```bash wrap theme={null}
             printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
             ```
          3. When prompted, enter the passphrase.
          4. Then, run the following to supply Omni with the private key and passphrase:

             ```bash wrap theme={null}
             curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
               -H "Authorization: Bearer <YOUR_API_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "$(jq -n \
                     --arg key "$(cat omni_deploy_key)" \
                     --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                     '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
             ```

             Replace the following:

             * `<your-subdomain>` - Your Omni subdomain
             * `<MODEL_ID>` - The shared model's UUID
             * `<YOUR_API_TOKEN>` - Your Omni API key

             A successful response will include the derived public key in the `publicKey` field.
          5. After you receive a successful response, run the following to unset the passphrase variable:

             ```bash theme={null}
             unset DEPLOY_KEY_PASSPHRASE
             ```
        </Tab>
      </Tabs>

      <Note>
        If you run into issues, see the [Troubleshooting section in the Rotate Git SSH keys guide](/guides/api/rotate-ssh-deploy-keys#troubleshooting).
      </Note>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

      <Tip>
        **Need to rotate keys?** See [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.
      </Tip>
    </Step>
  </Steps>
</View>

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.


# Connect a Bitbucket Cloud repository to Omni
Source: https://docs.omni.co/integrations/git/setup/bitbucket-cloud

Connect a Bitbucket Cloud repository to an Omni model

Omni supports SSH authentication to connect to Bitbucket Cloud repositories. This requires configuring both a deploy key and a webhook in Bitbucket Cloud. For the deploy key, you can either:

* Use the deploy key Omni generates by default
* Generate your own keypair and supply Omni with the private key

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="SSH + Omni deploy key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [Bitbucket's documentation](https://support.atlassian.com/bitbucket-cloud/docs/grant-access-to-a-workspace/) for information about user permissions.

  ## Configure SSH authentication with an Omni deploy key

  In this guide, you'll set up SSH authentication that uses the deploy key Omni generates for you.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Bitbucket repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. In the modal that displays, click the **HTTPS** dropdown, then select **SSH**.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Add an SSH key to a service account">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Bitbucket Cloud access keys are read-only. To allow Omni to push changes, you'll need to add the SSH key to a user account with write access to the repository. We recommend using a service account for this purpose.

      1. Create a service account with write access to the repository.
      2. In the service account, navigate to **Personal Bitbucket settings > SSH keys**.
      3. Click **Add key**.
      4. Fill in the fields as follows:
         * **Label** - Give your new SSH key a descriptive label
         * **Key** -&#x20;
      5. Click **Add key** to save the key.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. If the repository settings page isn't still open, open it by clicking **Repository settings** in the sidebar.
      2. Click **Webhooks**, located in the **Workflow** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title, such as *Omni Pull Request Webhook*
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Triggers** section, select **Choose from a full list of triggers**.
      6. Select only the **Pull Request** events:
         * Pull Request Created
         * Pull Request Updated
         * Pull Request Merged
      7. When finished, click **Save**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Your private key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [Bitbucket's documentation](https://support.atlassian.com/bitbucket-cloud/docs/grant-access-to-a-workspace/) for information about user permissions.

  To generate the keypair and supply the private key to Omni, you'll also need:

  * An [Omni API key](/api/authentication)
  * **The shared model's `modelId`,** which you can retrieve using the [List models](/api/models/list-models) endpoint
  * **`ssh-keygen` installed locally** to generate keypairs

  ## Configure SSH authentication with your private key

  In this guide, you'll set up SSH authentication that uses the private key you generate as part of a public-private keypair.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Bitbucket Cloud repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. In the modal that displays, click the **HTTPS** dropdown, then select **SSH**.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Generate a new keypair">
      Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

      <Tabs>
        <Tab title="ED25519">
          ```bash wrap theme={null}
          ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>

        <Tab title="RSA">
          ```bash wrap theme={null}
          ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>
      </Tabs>

      When prompted for a passphrase:

      * **To leave the key unencrypted**, press `Enter`.
      * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

      This generates two files:

      * `omni_deploy_key` — The private key, which you'll supply to Omni
      * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

      Bitbucket Cloud access keys are read-only. To allow Omni to push changes, you'll need to add the SSH key to a user account with write access to the repository. We recommend using a service account for this purpose.

      1. Create a service account with write access to the repository.
      2. In the service account, navigate to **Personal Bitbucket settings > SSH keys**.
      3. Click **Add key**.
      4. Fill in the fields as follows:
         * **Label** - Give your new SSH key a descriptive label
         * **Key** -&#x20;
      5. Click **Add key** to save the key.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. If the repository settings page isn't still open, open it by clicking **Repository settings** in the sidebar.
      2. Click **Webhooks**, located in the **Workflow** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title, such as *Omni Pull Request Webhook*
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Triggers** section, select **Choose from a full list of triggers**.
      6. Select only the **Pull Request** events:
         * Pull Request Created
         * Pull Request Updated
         * Pull Request Merged
      7. When finished, click **Save**.
    </Step>

    <Step title="Supply the private key to Omni with the API">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

      <Tabs>
        <Tab title="Unencrypted keys">
          In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

          ```bash wrap theme={null}
          curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
            -H "Authorization: Bearer <YOUR_API_TOKEN>" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
          ```

          Replace the following variables:

          * `<your-subdomain>` - Your Omni subdomain
          * `<MODEL_ID>` - The shared model's UUID
          * `<YOUR_API_TOKEN>` - Your Omni API key

          A successful response will include the derived public key in the `publicKey` field.
        </Tab>

        <Tab title="Passphrase-protected keys">
          1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
          2. Run the following to create a plain shell variable for the passphrase:

             ```bash wrap theme={null}
             printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
             ```
          3. When prompted, enter the passphrase.
          4. Then, run the following to supply Omni with the private key and passphrase:

             ```bash wrap theme={null}
             curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
               -H "Authorization: Bearer <YOUR_API_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "$(jq -n \
                     --arg key "$(cat omni_deploy_key)" \
                     --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                     '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
             ```

             Replace the following:

             * `<your-subdomain>` - Your Omni subdomain
             * `<MODEL_ID>` - The shared model's UUID
             * `<YOUR_API_TOKEN>` - Your Omni API key

             A successful response will include the derived public key in the `publicKey` field.
          5. After you receive a successful response, run the following to unset the passphrase variable:

             ```bash theme={null}
             unset DEPLOY_KEY_PASSPHRASE
             ```
        </Tab>
      </Tabs>

      <Note>
        If you run into issues, see the [Troubleshooting section in the Rotate Git SSH keys guide](/guides/api/rotate-ssh-deploy-keys#troubleshooting).
      </Note>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

      <Tip>
        **Need to rotate keys?** See [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.
      </Tip>
    </Step>
  </Steps>
</View>

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.


# Connect a Bitbucket Data Center/Server repository to Omni
Source: https://docs.omni.co/integrations/git/setup/bitbucket-data-center

Connect a self-hosted Bitbucket Data Center or Server repository to an Omni model

Omni supports SSH authentication to connect to Bitbucket Data Center or Server repositories. This requires configuring both a deploy key and a webhook in Bitbucket. For the deploy key, you can either:

* Use the deploy key Omni generates by default
* Generate your own keypair and supply Omni with the private key

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="SSH + Omni deploy key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [Bitbucket's documentation](https://confluence.atlassian.com/bitbucketserver/users-and-groups-776640439.html) for information about user permissions.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Bitbucket repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. In the modal that displays, click the **HTTPS** dropdown, then select **SSH**.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Add a repository access key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      1. In the Bitbucket repository, click **Repository settings**.
      2. Click **Access keys**, located in the sidebar.
      3. Click **Add key**.
      4. Fill in the fields as follows:
         * **Key** -&#x20;
         * **Permission** - Select **Write** to allow Omni to push changes made in Omni to the repository
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. If the repository settings page isn't still open, open it by clicking **Repository settings** in the sidebar.
      2. Click **Webhooks**, located in the **Workflow** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title, such as *Omni Pull Request Webhook*
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Triggers** section, select **Choose from a full list of triggers**.
      6. Select only the **Pull Request** events:
         * Pull Request Created
         * Pull Request Updated
         * Pull Request Merged
      7. When finished, click **Save**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Your private key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [Bitbucket's documentation](https://confluence.atlassian.com/bitbucketserver/users-and-groups-776640439.html) for information about user permissions.

  To generate the keypair and supply the private key to Omni, you'll also need:

  * An [Omni API key](/api/authentication)
  * **The shared model's `modelId`,** which you can retrieve using the [List models](/api/models/list-models) endpoint
  * **`ssh-keygen` installed locally** to generate keypairs

  ## Configure SSH authentication with your private key

  In this guide, you'll set up SSH authentication that uses the private key you generate as part of a public-private keypair.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Bitbucket repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. In the modal that displays, click the **HTTPS** dropdown, then select **SSH**.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Generate a new keypair">
      Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

      <Tabs>
        <Tab title="ED25519">
          ```bash wrap theme={null}
          ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>

        <Tab title="RSA">
          ```bash wrap theme={null}
          ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>
      </Tabs>

      When prompted for a passphrase:

      * **To leave the key unencrypted**, press `Enter`.
      * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

      This generates two files:

      * `omni_deploy_key` — The private key, which you'll supply to Omni
      * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

      1. In the Bitbucket repository, click **Repository settings**.
      2. Click **Access keys**, located in the sidebar.
      3. Click **Add key**.
      4. Fill in the fields as follows:
         * **Key** -&#x20;
         * **Permission** - Select **Write** to allow Omni to push changes made in Omni to the repository
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. If the repository settings page isn't still open, open it by clicking **Repository settings** in the sidebar.
      2. Click **Webhooks**, located in the **Workflow** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title, such as *Omni Pull Request Webhook*
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Triggers** section, select **Choose from a full list of triggers**.
      6. Select only the **Pull Request** events:
         * Pull Request Created
         * Pull Request Updated
         * Pull Request Merged
      7. When finished, click **Save**.
    </Step>

    <Step title="Supply the private key to Omni with the API">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

      <Tabs>
        <Tab title="Unencrypted keys">
          In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

          ```bash wrap theme={null}
          curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
            -H "Authorization: Bearer <YOUR_API_TOKEN>" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
          ```

          Replace the following variables:

          * `<your-subdomain>` - Your Omni subdomain
          * `<MODEL_ID>` - The shared model's UUID
          * `<YOUR_API_TOKEN>` - Your Omni API key

          A successful response will include the derived public key in the `publicKey` field.
        </Tab>

        <Tab title="Passphrase-protected keys">
          1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
          2. Run the following to create a plain shell variable for the passphrase:

             ```bash wrap theme={null}
             printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
             ```
          3. When prompted, enter the passphrase.
          4. Then, run the following to supply Omni with the private key and passphrase:

             ```bash wrap theme={null}
             curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
               -H "Authorization: Bearer <YOUR_API_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "$(jq -n \
                     --arg key "$(cat omni_deploy_key)" \
                     --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                     '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
             ```

             Replace the following:

             * `<your-subdomain>` - Your Omni subdomain
             * `<MODEL_ID>` - The shared model's UUID
             * `<YOUR_API_TOKEN>` - Your Omni API key

             A successful response will include the derived public key in the `publicKey` field.
          5. After you receive a successful response, run the following to unset the passphrase variable:

             ```bash theme={null}
             unset DEPLOY_KEY_PASSPHRASE
             ```
        </Tab>
      </Tabs>

      <Note>
        If you run into issues, see the [Troubleshooting section in the Rotate Git SSH keys guide](/guides/api/rotate-ssh-deploy-keys#troubleshooting).
      </Note>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

      <Tip>
        **Need to rotate keys?** See [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.
      </Tip>
    </Step>
  </Steps>
</View>

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.


# Connect a GitHub repository to Omni
Source: https://docs.omni.co/integrations/git/setup/github

Connect a GitHub repository to an Omni model using SSH deploy keys, HTTPS token authentication, or GitHub App authentication

Omni supports the following methods for connecting to a GitHub repository:

* **GitHub App authentication** - Uses a GitHub app to perform authentication. Enables commit signing.
* **SSH authentication** — Uses a deploy key and webhooks to connect Omni to your repository. This is the traditional method and requires configuring both a deploy key and a webhook in GitHub. You can either:
  * Use the deploy key Omni generates by default
  * Generate your own keypair and supply Omni with the private key
* **HTTPS token authentication** — Uses a GitHub fine-grained access token to authenticate

Choose the method that best fits your team's security requirements and preferences.

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="GitHub App">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) for information about user permissions.

  <Note>
    GitHub App authentication is only available for `github.com` repositories. This option only appears if your Omni instance has the GitHub App configured. If you don't see this option and want to use it, reach out to Omni support.
  </Note>

  ## Configure GitHub App authentication

  In this guide, you'll set up GitHub App authentication using the Omni GitHub App.

  <Steps>
    <Step title="Retrieve the repository's HTTPS URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Launch the Omni GitHub App installation flow">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.

      4) From the **Authentication Method** dropdown, select **GitHub App**.
      5) In the **HTTPS URL** field, copy and paste the repository's HTTPS URL from Step 1.
      6) Next to the **Installation ID** field, click the **Install the Omni GitHub App** link.

      GitHub will open in another tab in your browser. Leave this page open and finish the app installation in the other tab.
    </Step>

    <Step title="Install the Omni GitHub App">
      1. In GitHub, select the repository you want to connect.
      2. Complete the installation.
      3. After you complete the installation, retrieve the app's **installation ID** from the page URL:

         <Frame>
           <img alt="Highlighted app installation ID in the page URL" />
         </Frame>

      The installation ID is the string of numbers after the last forward slash in the page URL.
    </Step>

    <Step title="Configure the Git settings in Omni">
      1. Navigate back to the Omni Git settings page.
      2. Finish configuring the integration's settings:

         * **Installation ID** - Paste the installation ID you copied from GitHub in the previous step
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).

         <Note>
           If you want to configure [commit signing](#configure-commit-signing), enter a **Committer name** and **Committer email**. You won't be able to change these after clicking **Configure git**.
         </Note>
      3. Click **Configure Git**.
    </Step>

    <Step title="Configure commit signing">
      <Note>
        This step is optional.
      </Note>

      Authenticating through Omni's GitHub app allows you to enable commit signing. When a user with a verified email adds Omni's public signing key, Omni's commits will show up as **Verified**.

      The user with the verified **Committer email** you defined in the previous step must complete the following to configure commit signing:

      1. In GitHub, navigate to **Settings > SSH and GPG keys**. **Note**: This is an individual **user's** settings, not the connected repository's settings.
      2. Click **New SSH key**.
      3. Set the **Key type** to **Signing key**.
      4. In the **Key** field, paste the public key from the Omni Git settings page.
      5. Click **Add SSH key**.
    </Step>

    <Step title="Add repository webhooks">
      1. The repository settings page should still be open in GitHub. If not, re-open it.
      2. Click **Webhooks**, located in the **Code and automation** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Payload URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Content type** - Select the **application/json** option.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Which events would you like to trigger this webhook?** section:
      6. Click **Let me select individual events**.
      7. Select the **Pull request** event.
      8. If the **Push** event is selected, deselect it.
      9. When finished, click **Add webhook**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Omni deploy key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) for information about user permissions.

  ## Configure SSH authentication with an Omni deploy key

  In this guide, you'll set up SSH authentication that uses the deploy key Omni generates for you.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model or connected through the [dbt integration](/integrations/dbt), skip this step. Omni will use the existing deploy key.
      </Note>

      1. In the GitHub repository, click the **Settings** tab.
      2. Click **Deploy keys**, located in the **Security** section of the sidebar.
      3. Click **Add deploy key**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** -&#x20;
         * **Allow write access** -&#x20;
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. The repository settings page should still be open in GitHub. If not, re-open it.
      2. Click **Webhooks**, located in the **Code and automation** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Payload URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Content type** - Select the **application/json** option.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Which events would you like to trigger this webhook?** section:
      6. Click **Let me select individual events**.
      7. Select the **Pull request** event.
      8. If the **Push** event is selected, deselect it.
      9. When finished, click **Add webhook**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Your private key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) for information about user permissions.

  To generate the keypair and supply the private key to Omni, you'll also need:

  * An [Omni API key](/api/authentication)
  * **The shared model's `modelId`,** which you can retrieve using the [List models](/api/models/list-models) endpoint
  * **`ssh-keygen` installed locally** to generate keypairs

  ## Configure SSH authentication with your private key

  In this guide, you'll set up SSH authentication that uses the private key you generate as part of a public-private keypair.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Generate a new keypair">
      Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

      <Tabs>
        <Tab title="ED25519">
          ```bash wrap theme={null}
          ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>

        <Tab title="RSA">
          ```bash wrap theme={null}
          ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>
      </Tabs>

      When prompted for a passphrase:

      * **To leave the key unencrypted**, press `Enter`.
      * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

      This generates two files:

      * `omni_deploy_key` — The private key, which you'll supply to Omni
      * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

      1. In the GitHub repository, click the **Settings** tab.
      2. Click **Deploy keys**, located in the **Security** section of the sidebar.
      3. Click **Add deploy key**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** -&#x20;
         * **Allow write access** -&#x20;
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. The repository settings page should still be open in GitHub. If not, re-open it.
      2. Click **Webhooks**, located in the **Code and automation** section of the sidebar.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Payload URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Content type** - Select the **application/json** option.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Which events would you like to trigger this webhook?** section:
      6. Click **Let me select individual events**.
      7. Select the **Pull request** event.
      8. If the **Push** event is selected, deselect it.
      9. When finished, click **Add webhook**.
    </Step>

    <Step title="Supply the private key to Omni with the API">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

      <Tabs>
        <Tab title="Unencrypted keys">
          In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

          ```bash wrap theme={null}
          curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
            -H "Authorization: Bearer <YOUR_API_TOKEN>" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
          ```

          Replace the following variables:

          * `<your-subdomain>` - Your Omni subdomain
          * `<MODEL_ID>` - The shared model's UUID
          * `<YOUR_API_TOKEN>` - Your Omni API key

          A successful response will include the derived public key in the `publicKey` field.
        </Tab>

        <Tab title="Passphrase-protected keys">
          1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
          2. Run the following to create a plain shell variable for the passphrase:

             ```bash wrap theme={null}
             printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
             ```
          3. When prompted, enter the passphrase.
          4. Then, run the following to supply Omni with the private key and passphrase:

             ```bash wrap theme={null}
             curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
               -H "Authorization: Bearer <YOUR_API_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "$(jq -n \
                     --arg key "$(cat omni_deploy_key)" \
                     --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                     '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
             ```

             Replace the following:

             * `<your-subdomain>` - Your Omni subdomain
             * `<MODEL_ID>` - The shared model's UUID
             * `<YOUR_API_TOKEN>` - Your Omni API key

             A successful response will include the derived public key in the `publicKey` field.
          5. After you receive a successful response, run the following to unset the passphrase variable:

             ```bash theme={null}
             unset DEPLOY_KEY_PASSPHRASE
             ```
        </Tab>
      </Tabs>

      <Note>
        If you run into issues, see the [Troubleshooting section in the Rotate Git SSH keys guide](/guides/api/rotate-ssh-deploy-keys#troubleshooting).
      </Note>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

      <Tip>
        **Need to rotate keys?** See [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.
      </Tip>
    </Step>
  </Steps>
</View>

<View title="HTTPS token authentication">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) for information about user permissions.

  ## Configure HTTPS token authentication

  In this guide, you'll set up HTTPS token authentication.

  <Steps>
    <Step title="Retrieve the repository's HTTPS URL">
      1. In your browser, navigate to the GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Create a GitHub fine-grained personal access token">
      <Note>
        If the repository belongs to an organization, the organization must have a [personal access token policy](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) that allows the creation of personal access tokens.
      </Note>

      In GitHub, create a fine-grained personal access token with the following permissions for the repository:

      * **Contents**: Read and write
      * **Metadata**: Read-only (automatically included)
      * **Pull requests**: Read and write

      See [GitHub's documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) for instructions on creating a fine-grained personal access token.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **HTTPS (Token)** from the dropdown.
         * **HTTPS URL** - Copy and paste the repository's **HTTPS URL** from Step 1.
         * **Access Token** - Paste the  from Step 2.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.

## Related

* [Troubleshooting the Git integration](/integrations/git/troubleshooting)
* [Git best practices](/integrations/git/best-practices)
* [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys)
* [Sync model with Git repository API](/api/model-git-configuration/sync-model-with-git-repository)


# Connect a GitLab repository to Omni
Source: https://docs.omni.co/integrations/git/setup/gitlab

Connect a GitLab repository to an Omni model using SSH deploy keys or HTTPS token authentication

Omni supports the following methods for connecting to  repositories:

* **SSH authentication** — Uses a deploy key and webhooks to connect Omni to your repository. This is the traditional method and requires configuring both a deploy key and a webhook in . You can either:
  * Use the deploy key Omni generates by default
  * Generate your own keypair and supply Omni with the private key
* **HTTPS token authentication** — Uses a   to authenticate. This method is simpler to set up because it doesn't require deploy keys or webhooks.

Choose the method that best fits your team's security requirements and preferences.

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    **To view instructions**, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame>
      <img alt="Authentication method selection menu on right side of this page" />
    </Frame>
  </Note>
</View>

<View title="SSH + Omni deploy key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitLab's documentation](https://docs.gitlab.com) for information about user permissions.

  ## Configure SSH authentication with an Omni deploy key

  In this guide, you'll set up SSH authentication that uses the deploy key Omni generates for you.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model or connected through the [dbt integration](/integrations/dbt), skip this step. Omni will use the existing deploy key.
      </Note>

      1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
         <Note>
           GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
         </Note>
      2. Fill in the deploy key fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** -&#x20;
         * **Grant write permissions to this key** -&#x20;
      3. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. The repository settings page should still be open in GitLab. If not, re-open it.
      2. Click **Webhooks**.
      3. Click **Add new webhook**.
      4. Fill in the fields as follows:
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret token** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Custom headers** section:
         1. Click **Add custom header**.
         2. In the **Header name** field, enter `Content_type`.
         3. In the **Header value** field, enter `application/json`.
      6. In the **Trigger** section, select **Merge request events**.
      7. When finished, click **Add webhook**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Your private key">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitLab's documentation](https://docs.gitlab.com) for information about user permissions.

  To generate the keypair and supply the private key to Omni, you'll also need:

  * An [Omni API key](/api/authentication)
  * **The shared model's `modelId`,** which you can retrieve using the [List models](/api/models/list-models) endpoint
  * **`ssh-keygen` installed locally** to generate keypairs

  ## Configure SSH authentication with your private key

  In this guide, you'll set up SSH authentication that uses the private key you generate as part of a public-private keypair.

  <Steps>
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Generate a new keypair">
      Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

      <Tabs>
        <Tab title="ED25519">
          ```bash wrap theme={null}
          ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>

        <Tab title="RSA">
          ```bash wrap theme={null}
          ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>
      </Tabs>

      When prompted for a passphrase:

      * **To leave the key unencrypted**, press `Enter`.
      * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

      This generates two files:

      * `omni_deploy_key` — The private key, which you'll supply to Omni
      * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
    </Step>

    <Step title="Add a repository deploy key">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

      1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
         <Note>
           GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
         </Note>
      2. Fill in the deploy key fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** -&#x20;
         * **Grant write permissions to this key** -&#x20;
      3. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      1. The repository settings page should still be open in GitLab. If not, re-open it.
      2. Click **Webhooks**.
      3. Click **Add new webhook**.
      4. Fill in the fields as follows:
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret token** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Custom headers** section:
         1. Click **Add custom header**.
         2. In the **Header name** field, enter `Content_type`.
         3. In the **Header value** field, enter `application/json`.
      6. In the **Trigger** section, select **Merge request events**.
      7. When finished, click **Add webhook**.
    </Step>

    <Step title="Supply the private key to Omni with the API">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

      <Tabs>
        <Tab title="Unencrypted keys">
          In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

          ```bash wrap theme={null}
          curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
            -H "Authorization: Bearer <YOUR_API_TOKEN>" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
          ```

          Replace the following variables:

          * `<your-subdomain>` - Your Omni subdomain
          * `<MODEL_ID>` - The shared model's UUID
          * `<YOUR_API_TOKEN>` - Your Omni API key

          A successful response will include the derived public key in the `publicKey` field.
        </Tab>

        <Tab title="Passphrase-protected keys">
          1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
          2. Run the following to create a plain shell variable for the passphrase:

             ```bash wrap theme={null}
             printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
             ```
          3. When prompted, enter the passphrase.
          4. Then, run the following to supply Omni with the private key and passphrase:

             ```bash wrap theme={null}
             curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
               -H "Authorization: Bearer <YOUR_API_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "$(jq -n \
                     --arg key "$(cat omni_deploy_key)" \
                     --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                     '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
             ```

             Replace the following:

             * `<your-subdomain>` - Your Omni subdomain
             * `<MODEL_ID>` - The shared model's UUID
             * `<YOUR_API_TOKEN>` - Your Omni API key

             A successful response will include the derived public key in the `publicKey` field.
          5. After you receive a successful response, run the following to unset the passphrase variable:

             ```bash theme={null}
             unset DEPLOY_KEY_PASSPHRASE
             ```
        </Tab>
      </Tabs>

      <Note>
        If you run into issues, see the [Troubleshooting section in the Rotate Git SSH keys guide](/guides/api/rotate-ssh-deploy-keys#troubleshooting).
      </Note>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

      <Tip>
        **Need to rotate keys?** See [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.
      </Tip>
    </Step>
  </Steps>
</View>

<View title="HTTPS token authentication">
  ## Requirements

  To , you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing  repository**
  * **Permissions in  that allow you to:**

  Refer to [GitLab's documentation](https://docs.gitlab.com) for information about user permissions.

  ## Configure HTTPS token authentication

  In this guide, you'll set up HTTPS token authentication.

  <Steps>
    <Step title="Retrieve the repository's HTTPS URL">
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the  option.

      Keep this page open - you'll need it in the next step.
    </Step>

    <Step title="Create a project access token">
      In the GitLab repository, create a project access token with the following [project scopes](https://docs.gitlab.com/user/project/settings/project_access_tokens/#project-access-token-scopes):

      * `api` - Full API access
      * `read_repository` - Read repository contents
      * `write_repository` - Write repository contents

      See the [GitLab documentation](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token) for token creation steps.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. If your organization has more than one model, click the model you want to connect to git. If you have only one model, Omni opens it automatically.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **HTTPS (Token)** from the dropdown.
         * **HTTPS URL** - Copy and paste the repository's **HTTPS URL** from Step 1.
         * **Access Token** - Paste the  from Step 2.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.


# Setting up the git integration
Source: https://docs.omni.co/integrations/git/setup/index

Connect a git repository to an Omni model

<Note>
  **Looking to use GitHub repositories as AI context?** See the [GitHub AI integration](/integrations/ai/github) guide.
</Note>

Omni's git integration allows you to version control your model files by connecting an Omni model to a git repository. Select your git provider below for setup instructions:

<CardGroup>
  <Card title="Azure DevOps" icon="microsoft" href="/integrations/git/setup/azure-devops" />

  <Card title="Bitbucket Cloud" icon="bitbucket" href="/integrations/git/setup/bitbucket-cloud" />

  <Card title="Bitbucket Data Center" icon="bitbucket" href="/integrations/git/setup/bitbucket-data-center" />

  <Card title="GitHub" icon="github" href="/integrations/git/setup/github" />

  <Card title="GitLab" icon="gitlab" href="/integrations/git/setup/gitlab" />
</CardGroup>

<Note>
  Multiple Omni models can share the same git repository. If you're connecting a model to a repository that's already connected to another model, you only need to complete the Omni-side setup—the repository's deploy key and webhooks are already configured.
</Note>

## Requirements

To set up the git integration, you'll need:

* [**Omni Connection Admin permissions**](/administration/users/permissions) for the model you want to connect to git
* **An existing git repository** in GitHub, GitLab, Bitbucket, or Azure DevOps
* **Authentication credentials for your git provider:**

  * **SSH authentication** (all providers): Requires permissions to add webhooks and deploy/SSH keys to repositories
  * **HTTPS authentication** (GitHub and GitLab): Requires a personal access token or project access token with appropriate permissions
  * **GitHub App authentication** (GitHub only): Requires permission to install GitHub Apps on the repository or organization

  The authentication method you use will depend on your git provider. Refer to the documentation for your git provider for information about their user permissions and available authentication methods.

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.


# Troubleshooting the Git integration
Source: https://docs.omni.co/integrations/git/troubleshooting

Diagnose and resolve common issues with Omni's Git integration, including branches not appearing in Git, merges not reflecting, merged PRs reverting other changes, corrective commit overwrites, and follower mode problems.

Use this page to diagnose common issues with Omni's Git integration. Each scenario describes what you're seeing, why it happens, and how to fix it.

## Git authentication failed

<Steps>
  <Step title="What you're seeing" icon="eye">
    You receive a `"Git authentication failed"` error when Omni attempts to connect to your Git repository using HTTPS authentication.
  </Step>

  <Step title="Why it happens" icon="question">
    This error indicates an issue with your HTTPS access token, including:

    * Expired or revoked tokens
    * Insufficient permissions
    * Incorrect token format, including a partial token, extra characters, or whitespaces
  </Step>

  <Step title="How to fix it" icon="hammer">
    1. **Confirm your token is still valid.** If the token has expired or been revoked, generate a new one with the appropriate permissions.
    2. **Verify the token's permissions.** The following permissions are required:
       * **GitHub** - Contents (read and write), Metadata (read-only), and Pull requests (read and write)
       * **GitLab** - `api`, `read_repository`, and `write_repository` scopes
    3. **Check the token's formatting.** Ensure you've copied the entire token without any extra spaces or characters.

    If you created a new token, you'll also need to update the token in Omni:

    1. Open your model in the IDE.
    2. Navigate to **Model > Git settings**.
    3. Click **Change token**.
    4. Enter the new token and save.
  </Step>
</Steps>

## Omni doesn't react to PRs

<Steps>
  <Step title="What you're seeing" icon="eye">
    Omni isn't reacting to PRs in your Git repository. This includes not creating branches in Omni when PRs are opened and not reflecting merged changes in the shared model.
  </Step>

  <Step title="Why it happens" icon="question">
    Omni relies entirely on PR webhooks from your Git provider. If the webhook isn't configured correctly, Omni never receives the events it needs. Common misconfiguration causes:

    * **Wrong content type:** The webhook content type must be set to `application/json`. This mainly affects GitHub, where new webhooks default to `application/x-www-form-urlencoded` — Omni can't parse payloads sent with that content type. Other providers send JSON payloads by default; see your provider's [setup guide](/integrations/git/setup) for the exact webhook configuration.
    * **Wrong event types:** The webhook must be configured to send pull request events only. Push events should be turned off — Omni doesn't react to them, and leaving push events enabled adds noise without benefit.
    * **Wrong payload URL:** The payload URL must reference your specific Omni model ID. If the model ID in the URL doesn't match the model you're trying to integrate, events will be ignored.
    * **Wrong or missing webhook secret:** The webhook secret in your Git provider must match the secret generated by Omni during setup. A mismatch causes Omni to reject incoming events.
  </Step>

  <Step title="How to fix it" icon="hammer">
    In Omni, open your model in the IDE, navigate to **Model > Git settings**, and locate the Git configuration section. Cross-check each value against what's configured in your Git provider:

    <Steps>
      <Step title="Confirm the payload URL">
        Verify the payload URL contains the correct model ID.
      </Step>

      <Step title="Confirm the content type">
        The content type must be set to `application/json`.
      </Step>

      <Step title="Confirm the event types">
        Only **pull request events** should be selected. Disable **push events**.
      </Step>

      <Step title="Confirm the webhook secret">
        The webhook secret must match the value shown in Omni.
      </Step>
    </Steps>

    After updating your webhook, use the **Test Git connection** button in Omni's Git settings to verify connectivity.

    <Note>
      This button tests the deploy key connection; it does not validate the webhook configuration itself. To confirm webhook delivery, check the **Recent Deliveries** log in your Git provider's webhook settings. A failed delivery with a signature verification error indicates a webhook secret mismatch.
    </Note>
  </Step>
</Steps>

## 'Protect branch hook declined' error in Omni

<Steps>
  <Step title="What you're seeing" icon="eye">
    You're receiving the following error when Omni tries to push to the repository:

    ```text wrap theme={null}
    Failed to sync Git repo — Git push failed; status: REJECTED_OTHER_REASON, message: protect branch hook declined
    ```
  </Step>

  <Step title="Why it happens" icon="question">
    This error occurs when Omni tries to commit directly to your base branch but your repository has branch protection rules that block direct pushes.
  </Step>

  <Step title="How to fix it" icon="hammer">
    See [Schema refresh commits on default branch](#schema-refresh-commits-on-default-branch) for the three options that resolve this conflict.
  </Step>
</Steps>

## 'No write access due to repository rule violation' error in Omni

<Steps>
  <Step title="What you're seeing" icon="eye">
    You're receiving the following error when Omni tries to push to the repository — for example, during a schema refresh, a model sync, or when creating or updating a pull request:

    ```text wrap theme={null}
    No write access due to repository rule violation.
    ```
  </Step>

  <Step title="Why it happens" icon="question">
    A repository rule in your Git provider rejected Omni's push. Omni's Git credentials are working — the push was blocked by a rule, not by missing permissions.

    The most common cause is a branch protection rule or ruleset that requires pull requests for all changes to your base branch. By default, Omni commits directly to the base branch for schema refreshes, API events, and model syncs, and a "require a pull request before merging" rule blocks those commits.

    Rules that target other branches can also trigger this error — for example, branch naming restrictions or push restrictions that apply to the branch Omni pushes when you create a pull request.
  </Step>

  <Step title="How to fix it" icon="hammer">
    **If your repository requires pull requests for changes to the base branch**, you can resolve this in Omni: in **Model > Git settings**, enable the **Pull request required** toggle and its **Require for system syncs** sub-setting. This routes Omni's system-generated commits through the branch and PR workflow instead of pushing directly to the base branch.

    <Note>
      [**Branch-based schema refresh**](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) must be enabled before you can enable **Require for system syncs**. See [Schema refresh commits on default branch](#schema-refresh-commits-on-default-branch) for details and for alternative setups, such as a machine user bypass or a dedicated Omni-owned base branch.
    </Note>

    **Otherwise**, review your repository's branch protection rules and rulesets in your Git provider to identify which rule is rejecting Omni's push — for example, a branch naming restriction — then adjust the rule or add a bypass so Omni's pushes are allowed. See [Options for protected branches](/integrations/git/best-practices#options-for-protected-branches) for recommended setups.
  </Step>
</Steps>

## Branch not appearing in Git

<Steps>
  <Step title="What you're seeing" icon="eye">
    You created a branch in Omni and made changes, but the branch doesn't exist in your Git repository.
  </Step>

  <Step title="Why it happens" icon="question">
    Omni's version control is separate from Git. When you create a branch in Omni, it exists only inside Omni until you explicitly trigger a sync with your Git repository. Omni only pushes a branch to Git when you click **Create pull request** in the model IDE or update the branch through the [Create or update YAML files API](/api/models/create-or-update-yaml-files).
  </Step>

  <Step title="How to fix it" icon="hammer">
    In the Omni model IDE, open your branch and click **Create pull request**. This triggers Omni's backend to sync the branch to your Git repository, at which point the branch will appear and you can open a pull request. If you're working through the API, use the [Create or update YAML files endpoint](/api/models/create-or-update-yaml-files) with a `branchId` — writing YAML to a branch syncs it to Git the same way clicking **Create pull request** does.

    <Note>
      The **Create pull request** button will be disabled until at least one model change is saved to the branch. Save a change before trying to sync.
    </Note>
  </Step>
</Steps>

## Pushing to Git from Omni fails

<Steps>
  <Step title="What you're seeing" icon="eye">
    You're unable to open PRs, sync the repository in Omni, or push changes. You may receive messages similar to the following in Omni when this occurs:

    ```txt theme={null}
    No write access. Check deploy key or token configuration.

    Failed to sync git repo
    ```
  </Step>

  <Step title="Why it happens" icon="question">
    The deploy key or access token used to connect the repository to Omni doesn't have `write` access to the repository.
  </Step>

  <Step title="How to fix it" icon="hammer">
    1. In Omni, open your model in the IDE and navigate to **Model > Git settings**.
    2. Copy the **Public key**.
    3. In your Git provider:
       1. Create a new deploy key, using the **Public key** you copied in the previous step. Make sure it has **write** access.
       2. Remove the old key.
  </Step>
</Steps>

## Omni is creating branches from PRs you didn't initiate

<Steps>
  <Step title="What you're seeing" icon="eye">
    Omni is creating branches automatically whenever a PR is opened in your Git repository, including PRs that weren't started from the model IDE or API.
  </Step>

  <Step title="Why it happens" icon="question">
    The **Always create branches** setting is enabled on your model (labeled **Create Omni Branches for all pull requests** in the IDE). When this is on, Omni creates a matching branch for every PR opened in Git, regardless of whether it was initiated from the Omni IDE or API. For PRs that don't include model changes, this creates empty Omni branches that can clutter your branch list.
  </Step>

  <Step title="How to fix it" icon="hammer">
    In Omni, open your model in the IDE and navigate to **Model > Git settings**. Turn off **Always create branches**.

    Omni branches should always be initiated from the model IDE or API, not directly from Git. With the setting off, Omni will only create a branch when you explicitly click **Create pull request** in the IDE or call the equivalent API endpoint.
  </Step>
</Steps>

## 'Key already in use' message in your Git provider

<Steps>
  <Step title="What you're seeing" icon="eye">
    You receive a `Key already in use` error when trying to add a deploy key to your connected Git repository.
  </Step>

  <Step title="Why it happens" icon="question">
    Omni automatically shares a single deploy key and webhook configuration across all model and Git integrations connected to the same repository. This also includes dbt, if your dbt project lives in the same repository and you've connected it to Omni with the [dbt integration](/integrations/dbt). You only need to register one deploy key and one webhook in your Git provider — Omni handles the coordination internally.
  </Step>

  <Step title="How to fix it" icon="hammer">
    No action is required. Omni will use the repository's deploy key for all models connected to the repository, and a dbt connection if one exists.
  </Step>
</Steps>

## Merge not reflected in Omni

<Steps>
  <Step title="What you're seeing" icon="eye">
    You merged a PR in Git, but Omni doesn't show the updated model or Omni pushed its own model state back to your base branch, overwriting the changes you merged.
  </Step>

  <Step title="Why it happens" icon="question">
    Omni only reacts to pull request webhook events — opened, updated, and merged. It does not watch for direct pushes.

    Two things result in this scenario:

    * **The PR was created outside of Omni.** This happens when the PR was opened directly in Git rather than initiated from the model IDE or API, so the branch has no corresponding Omni branch. When the merge webhook arrives, Omni looks for its branch, finds nothing, and pushes its current model state back to your base branch instead. This resets the base branch to Omni's internal state and deletes any model YAML that was added only in Git.
    * **The change was pushed directly without a PR.** A direct push or fast-forward to the base branch generates no PR webhook, so Omni is never alerted to the change.
  </Step>

  <Step title="How to fix it" icon="hammer">
    For both cases, the fix is to make the change through an Omni branch:

    1. Create the branch in Omni
    2. Make your changes in the branch
    3. Click **Create PR** to sync the branch to Git,
    4. Open and merge the PR through your Git provider

    Omni will receive the merge webhook, find its branch, and apply the changes.

    If the change is already on your base branch in Git but not in Omni, re-create the change on an Omni branch and go through the PR workflow. Don't try to restore the state by pushing to Git directly, as Omni will overwrite it again on the next sync.

    <Warning>
      Omni treats its own model state as authoritative. If you push model YAML directly to your base branch, Omni will overwrite it the next time it syncs. See [Corrective commit overwrites changes](#corrective-commit-overwrites-changes) for the related scenario involving branches.
    </Warning>
  </Step>
</Steps>

## Corrective commit overwrites changes

<Steps>
  <Step title="What you're seeing" icon="eye">
    You made edits directly in the Git repository on a branch — during a PR review, through an automated script, or through an external tool — and those changes were overwritten by a commit from Omni.
  </Step>

  <Step title="Why it happens" icon="question">
    Every time Omni receives a PR webhook event, it pulls the branch from Git and validates the YAML. If any file fails validation — due to invalid syntax, an unrecognized parameter, or improper indentation — Omni rejects the change and makes a corrective commit that restores the branch to its last known good state. The corrective commit appears in history with the author `Omni Model Webhook Service`. Git history is preserved, but any changes bundled with the bad YAML are also reverted.

    **Omni rejects syntactically invalid YAML only.** It accepts semantically broken code — for example, a join that references a field that doesn't exist — but those problems will surface as model validator errors rather than triggering a corrective commit.
  </Step>

  <Step title="How to fix it" icon="hammer">
    Make model changes through Omni, either in the IDE or through the Omni API, rather than editing the Git repository directly. Omni validates changes at save time and gives you immediate feedback, so bad YAML never reaches the repository in the first place. If you need to make programmatic changes, use the [Omni CLI](/developers/cli) or model APIs rather than committing to Git.

    If you're reviewing a PR and want to suggest a change to the YAML, make the edit in Omni on the branch. Once you save a change, the **Update Pull request** button will become active — click it to sync the corrected state to Git.

    Non-model files committed to your repository are not affected by corrective commits or Omni's model syncs. For example, CI configuration, scripts, or root-level ownership files.

    However, nested metadata files placed inside model subdirectories (for example, `OWNERS.yaml` files under `omni/<model>/`) may be removed when Omni regenerates its projection. If you're using code ownership tooling, keep those files at the root of your `omni/` directory rather than nested inside model folders.

    <Note>
      If you're using automation or an AI agent that interacts with your Git repository, redirect it to use the Omni APIs instead. Agents that commit directly to Git will reliably trigger corrective commits whenever their output contains a YAML error. See [Omni agent skills](/developers/agent-skills) for more information.
    </Note>
  </Step>
</Steps>

## Merging a PR reverts changes from another branch

<Steps>
  <Step title="What you're seeing" icon="eye">
    You merged a pull request and changes that were previously merged from a different pull request disappeared from the shared model. In the model IDE's [model history](/modeling/develop/history), the **Webhook merge** entry for the PR shows a diff that changes files the PR didn't touch in Git — for example, a re-uploaded CSV reverting to older data or fields added by an earlier merge being removed.
  </Step>

  <Step title="Why it happens" icon="question">
    When a pull request merges, Omni doesn't apply Git's merge result to the shared model. Instead, it promotes the Omni branch associated with the PR: every model file stored on that branch is applied on top of the current shared model, replacing the shared version of those files. The most recently merged branch wins, file by file.

    An Omni branch only re-syncs from Git when new commits are pushed to its open PR. If a PR sits open while other PRs merge, its Omni branch keeps the older state of any files it carries. Merging it then overwrites the newer shared model state for those files, even if the PR's Git diff never touched them.

    Because Omni treats its own model state as authoritative, it also pushes the post-merge state back to your base branch. The revert lands in Git too, even though Git's own merge of the PR was correct.
  </Step>

  <Step title="How to fix it" icon="hammer">
    To recover the lost changes, re-apply them through Omni by either redoing them on a new branch or by restoring the affected files from a version prior to the merge. **Don't attempt recovery by pushing YAML directly to Git.** See [Model is in broken state](#broken-model-state) for the restoration steps.

    To prevent this from happening:

    1. **Update stale PRs before merging them.** Push a new commit to the PR branch or merge the base branch into it (for example, GitHub's **Update branch** button). This sends Omni a webhook that re-syncs the Omni branch against the current shared model. Alternatively, open the branch in the model IDE, save a change, and click **Update pull request**.
    2. **Keep branches short-lived.** The longer a PR stays open while other changes merge, the more likely its Omni branch is carrying stale copies of shared files.
    3. **Review the merge in model history.** After merging a long-lived PR, open the model history and check the **Webhook merge** entry's diff. If it changed files the PR shouldn't have touched, restore or re-apply promptly.
  </Step>
</Steps>

## Schema refresh commits on default branch

<Steps>
  <Step title="What you're seeing" icon="eye">
    Omni is committing directly to your base branch (for example, `main`) outside of the PR workflow. This may conflict with branch protection rules that require PRs for all changes to the base branch.
  </Step>

  <Step title="Why it happens" icon="question">
    By default, certain Omni actions — schema refreshes, API events, and model syncs — commit directly to your base branch without going through a pull request. Omni fetches the latest commit, then pushes the regenerated model directly on top using a normal commit, not a force push. If your repository has branch protection rules that require PRs for all changes to the base branch, this direct commit will conflict with those rules.

    Manual changes you make directly to model YAML on the base branch may also be overwritten the next time one of these syncs runs, since Omni regenerates the full model state when it writes. Non-model files in the repository are not affected.
  </Step>

  <Step title="How to fix it" icon="hammer">
    There are three approaches. Pick the one that fits your team's workflow:

    * Use **Option 1** if you need to satisfy strict branch protection rules with no bypass exceptions.
    * Use **Option 2** if you want schema refreshes to stay direct while keeping human developers gated behind pull requests.
    * Use **Option 3** if you want to keep Omni's writes off your protected `main` branch entirely.

    <AccordionGroup>
      <Accordion title="Option 1: Enable pull request required with system syncs">
        In **Model > Git settings**, enable the **Pull request required** toggle, then enable its **Require for system syncs** sub-setting. This routes schema refreshes and other system-generated commits through the branch and PR workflow, satisfying strict branch protection requirements with no exceptions needed.

        <Note>
          [**Branch-based schema refresh**](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) must be enabled before you can enable **Require for system syncs**.

          Branch-based schema refreshes can't be enabled for connections with more than one model. The tradeoff is that schema changes appear in PRs alongside model changes, which can make reviews less focused.
        </Note>
      </Accordion>

      <Accordion title="Option 2: Add a dedicated Omni machine user to your bypass list">
        Switch Omni's Git credentials from the default SSH deploy key to [HTTPS token authentication](/integrations/git/setup/github) using a token that belongs to a dedicated machine user, then add that machine user to your branch protection rule's bypass list. This keeps schema refreshes direct and low-friction while leaving all human developers gated behind pull requests.

        <Note>
          HTTPS token authentication is only available for GitHub and GitLab. If you're using Azure DevOps or Bitbucket, use Option 1 or Option 3 instead.
        </Note>
      </Accordion>

      <Accordion title="Option 3: Use a dedicated Omni-owned base branch">
        In **Model > Git settings**, set the [**Base branch** field](/integrations/git/settings#base-branch) to a branch that isn't your protected `main` — for example, `omni-prod` — and leave that branch unprotected.

        Omni's pushes land there without issue and `main` is never touched.

        <Note>
          Omni never force-pushes your base branch. The applicable branch protection rule in this scenario is *"require a pull request before merging,"* not *"restrict force pushes."* Clarifying this with your platform team early can prevent the force-push concern from blocking setup.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Follower not picking up changes

This scenario applies to models configured with [Git follower mode](/integrations/git/follower-mode).

<Steps>
  <Step title="What you're seeing" icon="eye">
    You merged a change to your follower's watched branch in Git, but the follower's model hasn't updated.
  </Step>

  <Step title="Why it happens" icon="question">
    There are two potential causes:

    1. **Changes were made without going through a PR merge.** Like the leader, a follower only reacts to PR merge events on the branch it's configured to watch. If a change was pushed or committed directly to that branch without going through a PR merge, the follower won't detect it.

       <Note>
         If you're using a release branch as a validation step before merging to your follower's watched branch, make sure the PR targets the correct watched branch. A PR merged to `main` won't trigger a follower that's watching a `prod` branch.
       </Note>
    2. **Schema mismatches between the leader and follower schema model.** The follower reconciles the Git projection against its own schema model to determine what belongs in the shared layer. If the follower's database schema differs from the leader's, the follower may accept the change but surface errors when users query topics that reference fields missing from its schema. For example, tables are missing or are named differently.
  </Step>

  <Step title="How to fix it" icon="hammer">
    * **To resolve an event trigger issue**, confirm the change reached the follower's watched branch through a PR merge. If you pushed directly, open a PR from that branch to the watched branch and merge it.

    * **To resolve a schema mismatch issue**, verify that the database schemas on the leader and follower are identical. The follower needs to be able to account for every field referenced in the Git projection using its own schema model.

      If schemas have diverged, run a schema refresh on the follower after confirming the underlying database matches, then trigger the follower by merging a PR to its watched branch.
  </Step>
</Steps>

## Model is in a broken state

<Steps>
  <Step title="What you're seeing" icon="eye">
    Your Omni model is in a broken state and you need to restore it to a known good state. For example, dashboards aren't loading, topics are missing, or a schema refresh has removed a large portion of your views.
  </Step>

  <Step title="Why it happens" icon="question">
    Omni is the source of truth and Git is a projection of Omni's state. This means you can't restore Omni by pushing the correct YAML to Git, as Omni will overwrite whatever you push the next time it syncs.
  </Step>

  <Step title="How to fix it" icon="hammer">
    <Warning>
      Don't attempt recovery by pushing or restoring YAML directly in Git. Omni regenerates its projection from its internal model state, so Git-only changes will be overwritten. The steps below are the only correct recovery path.
    </Warning>

    The correct recovery path is through Omni's own model history:

    1. In Omni, open your model in the IDE.
    2. Click the <Icon icon="clock" /> icon in the sidebar.
    3. Find the entry that represents the last known good state, then restore to that version.
    4. Once Omni's model state is correct, it will push that state to Git on the next sync, bringing the repository back into alignment.
  </Step>
</Steps>


# Omni Slack Agent
Source: https://docs.omni.co/integrations/omni-slack-agent

Ask data questions directly in Slack and get AI-powered answers, charts, and tables from your Omni semantic model.

<Note>
  See [Scheduling Slack deliveries](/share/deliveries/slack) and the [Slack AI integration](/integrations/ai/slack) for more information about other ways to use Slack with Omni.
</Note>

The Omni Slack Agent lets your team ask data questions directly in Slack. Users can DM the agent or `@Omni` it in any channel to get AI-powered answers from your semantic model without leaving Slack.

## Setting up the Omni Slack Agent

### Requirements

To configure the Omni Slack Agent for your organization, you'll need:

* A Slack workspace
* **Organization Admin** permissions in Omni
* An Omni organization with [AI features enabled](/ai/settings/features)
* At least one [topic](/modeling/topics) configured in your model

### Connecting Omni to your Slack workspace

<Steps>
  <Step title="Connect your Slack workspace">
    1. In Omni, navigate to **Settings > Integrations**.
    2. Click **Connect to Slack** and complete the Slack authorization flow.

    You'll be redirected back to Omni once the connection is established. Admins will receive a welcome message in Slack confirming the integration is active.

    <Tip>
      **Already connected for deliveries?** If your Slack workspace is already connected for [scheduled deliveries](/share/deliveries/slack), you'll see an option to upgrade the connection with additional permissions required by the Omni Slack Agent. Click **Reconnect** to authorize the expanded permissions.
    </Tip>
  </Step>

  <Step title="Verify the agent and introduce it to your team">
    After connecting, the agent will send you a welcome message in Slack confirming the integration is active. To help your team discover the Omni Slack Agent, we recommend using the workflow in the welcome message that will allow the agent to introduce itself in a public channel. You can see a preview of the message in the welcome message.

    <Note>
      Introducing the Omni Slack Agent in a public channel is the best way to drive broad awareness and encourage your team to connect their accounts and start asking questions.
    </Note>
  </Step>
</Steps>

### Configuring agent settings

<Note>
  **Organization Admin** permissions are required to modify integration settings in Omni.
</Note>

In Omni, navigate to **Settings > Integrations** and open the **Slack** tab to manage your integration's settings:

#### Default model

Defines the default model the agent uses when [answering questions](#ask-questions). Users will still be able to use other models they have access to.

#### Channel response privacy

Restricts the behavior of how the agent's responses are shared within Slack channels and group direct messages. The **Require private responses** setting controls the default:

* **Disabled** (default) — Responses post to channel threads, unless the prompting user has [private channel responses configured](#omni-privacy).
* **Enabled** — Users always receive a private response and can choose to share it with the thread.

### Reconnecting the Slack integration

The **Reconnect** action in **Settings > Integrations > Slack** runs a fresh OAuth flow against your existing installation. Reconnect is non-destructive — it does not affect scheduled deliveries, per-user account links, or other Omni-side resources. Use it to:

* **Refresh an invalidated token** — If Omni's stored token stops working for any reason, run Reconnect to install a new one.
* **Upgrade an older install to support new features** — Some features added after your workspace originally installed Omni require additional Slack scopes (the Omni Slack agent is one example). Re-running OAuth grants those scopes.
* **Grant optional scopes you previously skipped** — If the installer opted out of an [optional scope](#optional-scopes) at install time and later wants to enable it, Reconnect re-runs the authorization screen so they can select it.

<Note>
  Reconnect can add scopes to your existing Slack installation, but it cannot remove ones that were previously granted — see [Changing scopes after install](#changing-scopes-after-install).
</Note>

### Changing scopes after install

* **Adding scopes** — Use [Reconnect](#reconnecting-the-slack-integration) and select the additional scopes at Slack's authorization screen.
* **Removing scopes** — Requires a Slack workspace admin to uninstall and reinstall the Omni Slack app. Slack does not let an app remove a previously granted scope from an existing installation, so a full reinstall is the only way. See the procedure below.

#### Removing a previously granted scope

<Warning>
  **Do not click Disconnect in Omni when your goal is to change scopes.** [Disconnect](#disconnecting-the-slack-integration) deletes scheduled Slack deliveries and per-user account links. The flow below preserves them.
</Warning>

<Steps>
  <Step>
    Your Slack workspace admin uninstalls Omni from the Slack admin console. This removes the installation in Slack and invalidates Omni's stored token, but does not delete any deliveries, account links, or other resources in Omni.
  </Step>

  <Step>
    In Omni, navigate to **Settings > Integrations** and open the **Slack** tab. Because the token is no longer valid, you'll see an error state with a **Reconnect** action.
  </Step>

  <Step>
    Click **Reconnect** to run a fresh OAuth flow. Slack treats this as a new installation — no scopes carry over from the previous one — so select only the scopes you want at Slack's authorization screen.
  </Step>

  <Step>
    On confirmation, Omni stores the new token. Your scheduled deliveries, per-user account links, and other Omni resources from the previous installation are preserved.
  </Step>
</Steps>

### Disconnecting the Slack integration

<Warning>
  **Disconnect is destructive.** It deletes all scheduled Slack deliveries in your Omni organization, clears every user's Omni↔Slack account link, and stops the agent from responding in your workspace. If you only want to refresh the token or change scopes, use [Reconnect](#reconnecting-the-slack-integration) or the [scope-change procedure](#changing-scopes-after-install) instead.
</Warning>

To remove the Slack integration from Omni, navigate to **Settings > Integrations**, open the **Slack** tab, and click **Disconnect**. This:

* Deletes all scheduled Slack deliveries (channel and DM)
* Clears every user's Omni↔Slack account link — users will need to [reconnect their accounts](#connecting-your-omni-account) before they can interact with the agent again
* Stops the agent from responding to `@Omni` mentions, DMs, and `/omni` slash commands in your workspace

Disconnect does not uninstall the Omni app from your Slack workspace. To remove the app from Slack itself, a Slack workspace admin must uninstall it from the Slack admin console.

## Slack permissions

When connecting Omni to your Slack workspace, your Slack workspace admin can deselect any of the **optional** scopes at Slack's authorization screen to install Omni with a reduced permission footprint. **Required** scopes cannot be deselected — opting out of them prevents the integration from working.

Omni's Slack integration is installed as a single app, so this scope selection applies to everything Omni does in Slack — agent mentions, slash commands, scheduled deliveries, link unfurling, and emoji reactions. Review the **Impact if removed** column below before deselecting any scope.

<Warning>
  Opting out of `channels:join` or the `files:*` scopes significantly changes how Omni behaves in Slack. Review the impact below before deselecting.
</Warning>

### Required scopes

These scopes are needed for the integration to function. They cannot be opted out of without breaking core functionality.

| Permission                                                                          | How Omni uses it                                                                         |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [`app_mentions:read`](https://docs.slack.dev/reference/scopes/app_mentions.read/)   | Receives `@Omni` mention events                                                          |
| [`channels:read`](https://docs.slack.dev/reference/scopes/channels.read/)           | Reads public channel metadata                                                            |
| [`chat:write`](https://docs.slack.dev/reference/scopes/chat.write/)                 | Sends messages to Slack                                                                  |
| [`commands`](https://docs.slack.dev/reference/scopes/commands/)                     | Registers and handles `/omni` slash commands                                             |
| [`groups:read`](https://docs.slack.dev/reference/scopes/groups.read/)               | Reads private channel metadata (only channels Omni is a member of)                       |
| [`im:read`](https://docs.slack.dev/reference/scopes/im.read/)                       | Reads DM channel metadata                                                                |
| [`im:write`](https://docs.slack.dev/reference/scopes/im.write/)                     | Opens DM channels with users                                                             |
| [`links:read`](https://docs.slack.dev/reference/scopes/links.read/)                 | Reads URL metadata for unfurling Omni links in Slack                                     |
| [`links:write`](https://docs.slack.dev/reference/scopes/links.write/)               | Provides rich unfurl previews when Omni URLs are shared in Slack                         |
| [`reactions:read`](https://docs.slack.dev/reference/scopes/reactions.read/)         | Observes emoji reactions on messages                                                     |
| [`reactions:write`](https://docs.slack.dev/reference/scopes/reactions.write/)       | Adds and removes emoji reactions on messages                                             |
| [`team:read`](https://docs.slack.dev/reference/scopes/team.read/)                   | Reads workspace metadata to identify the workspace and display its name in Omni settings |
| [`users:read`](https://docs.slack.dev/reference/scopes/users.read/)                 | Resolves Slack user IDs to names                                                         |
| [`users.profile:read`](https://docs.slack.dev/reference/scopes/users.profile.read/) | Reads Slack profile metadata for users surfaced in Omni                                  |
| [`users:read.email`](https://docs.slack.dev/reference/scopes/users.read.email/)     | Resolves a Slack user to an Omni user by matching on email                               |

### Optional scopes

These scopes can be deselected at Slack's authorization screen. Omni recommends keeping all of them enabled for the best experience, but the **Impact if removed** column describes what changes if you opt out.

<Note>
  Slack OAuth scopes are additive within a single installation. To add a scope after install, use [Reconnect](#reconnecting-the-slack-integration). To remove a previously granted scope, a workspace admin must uninstall the Omni Slack app and reinstall it — see [Changing scopes after install](#changing-scopes-after-install) for the procedure that preserves your deliveries and account links.
</Note>

| Permission                                                                                                                                                                                                                                                                                                 | How Omni uses it                                                                                | Impact if removed                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`channels:join`](https://docs.slack.dev/reference/scopes/channels.join/)                                                                                                                                                                                                                                  | Auto-joins public channels so workspace members don't need to add Omni manually                 | **Scheduled deliveries to channels Omni isn't a member of will fail** until a workspace member adds Omni to the destination channel.                                                                                                                                           |
| [`files:read`](https://docs.slack.dev/reference/scopes/files.read/), [`files:write`](https://docs.slack.dev/reference/scopes/files.write/)                                                                                                                                                                 | Attaches dashboard screenshots, exports, and other files to messages Omni sends                 | Scheduled deliveries in a file format (PDF, PNG, XLSX, CSV) are sent as a secure, expiring link (7 days) instead of a file attachment. Agent responses cannot include image or file attachments; users click **Open in Omni** to view visualizations or the full conversation. |
| [`channels:history`](https://docs.slack.dev/reference/scopes/channels.history/), [`groups:history`](https://docs.slack.dev/reference/scopes/groups.history/), [`im:history`](https://docs.slack.dev/reference/scopes/im.history/), [`mpim:history`](https://docs.slack.dev/reference/scopes/mpim.history/) | Reads Slack message history so the agent can use thread and conversation context when answering | The agent answers only from the prompting message and cannot pull context from earlier messages in channels, threads, DMs, or group DMs. Omni recommends building robust context directly in your semantic model rather than relying on conversational history.                |
| [`assistant:write`](https://docs.slack.dev/reference/scopes/assistant.write/)                                                                                                                                                                                                                              | Lets Omni act as a Slack AI assistant in Slack's native assistant-thread UI                     | Future Omni functionality that depends on Slack's native assistant integration will not be available.                                                                                                                                                                          |

## Connecting your Omni account

<Note>
  **This section applies to all users**, not only Slack admins. Every user who wants to interact with the Omni Slack Agent must connect their Omni account.
</Note>

Before you can ask questions, you'll need to link your Slack account to your Omni account:

<Steps>
  <Step>
    Send a message to the Omni Slack Agent in a channel or DM by mentioning it with `@Omni`.
  </Step>

  <Step>
    The agent will reply with a **Connect account** button.
  </Step>

  <Step>
    Click the button and follow the prompts to link your Slack identity to your Omni account.
  </Step>
</Steps>

Once connected, you'll receive a confirmation message and a welcome message explaining what you can do with the Omni Slack Agent. The agent will also pick up your original question automatically.

<Tip>
  Use the [`/omni disconnect`](#omni-disconnect) slash command to disconnect your Slack account.
</Tip>

## Asking questions

You can interact with the Omni Slack Agent in three ways:

* **Direct message**: DM the Omni Slack Agent directly starting your request with `@Omni`.
* **`@mention` in a channel**: Type `@Omni` followed by your question in any channel.
* **Group DM**: To include the Omni Slack Agent in a DM with other people, you must start a new group DM with the agent as one of the participants — you cannot add it to an existing DM.

The agent responds with an answer that can include:

* **Text** — A written explanation or summary. Dashboard names found via search are automatically hyperlinked to the dashboard.
* **Tables** — Tabular data rendered in Slack's Block Kit format
* **Open in Omni** link — Click to view the full result in Omni

The agent can also [create routines](#routines) when you ask for something on a recurring schedule.

<Tip>
  Response visibility depends on your organization's [privacy settings](#admin-privacy-setting), and [your own preferences](#omni-privacy) if user-controlled privacy is enabled.
</Tip>

### Creating and finding routines

Ask the agent for anything recurring and it will create a [routine](/ai/routines) — a saved prompt Omni runs on a schedule and delivers by email or Slack:

> *"@Omni every Monday at 9am, post a summary of last week's signups to this channel"*

The routine is created active and runs with your permissions. Name a Slack channel, people, or a user group in your prompt to choose where it delivers; otherwise it's delivered to you.

You can also ask the agent to find your routines — for example, *"what do I have scheduled?"* or *"find the routine that posts to #growth"* — and it replies with matching routines as edit links. To view, edit, pause, or delete routines, use the [Routines page](/ai/routines#managing-routines) in Omni.

### Editing dashboards

When you ask the Omni Slack Agent to edit an existing dashboard, the changes land in a [draft](/content/develop/drafts). The changes won't be live until you review and manually publish the changes. Brand new dashboards created by the agent are published immediately.

### Follow-up questions

To ask a follow-up question, type `@Omni` followed by your question in the same Slack thread. The agent maintains conversation context within a thread, so you can refine results — add filters, change groupings, or drill into a metric.

### Providing response feedback

You can rate the quality of agent responses using the <Icon icon="thumbs-up" /> and <Icon icon="thumbs-down" /> buttons that appear on AI responses. Your feedback helps improve the accuracy and usefulness of future responses.

When you click the <Icon icon="thumbs-up" /> button, a form opens where you can optionally share additional context about what worked well. You can also skip providing details and simply register the positive feedback.

When you click the <Icon icon="thumbs-down" /> button, a form opens where you can select a category that describes the issue and optionally provide additional details. You can also skip providing details and simply register the negative feedback.

## Scoping responses

The Omni Slack Agent enforces the same permissions and model-level access controls as the rest of Omni. Each user's access in Slack mirrors their access in the Omni app — the agent can only query connections, models, topics, and fields that the user is already permitted to see, including any restrictions applied through [access grants](/modeling/develop/data-access-control), [user attributes](/administration/users/attributes), and [connection-level permissions](/administration/users/permissions).

The topics the Omni Slack Agent can use are controlled by the [`ai_chat_topics`](/modeling/models/ai-chat-topics) model parameter, which is also honored by the [Omni Agent](/ai/chat) and [embedded chat instances](/embed/customization/ai-chat).

## Using slash commands

The Omni Slack Agent supports slash commands as an alternative way to interact with the agent. All slash commands use the `/omni` prefix.

### /omni or /omni help

Shows a list of available commands. When you're connected to Omni, this displays the full command reference. If you're not yet connected, this shows a prompt to connect your account.

### /omni ask \[question]

Asks a question to the Omni Slack Agent. You can use this command in two ways:

* **With the `ask` keyword**: `/omni ask what was revenue last quarter?`
* **Without the `ask` keyword**: `/omni what was revenue last quarter?`

The agent posts your question to the channel or DM and responds in a thread, just like with `@mentions`. The response can include text, tables, and a link to open the full result in Omni.

<Note>
  If you use `/omni ask` while your account isn't connected, you'll see a prompt to connect. Unlike `@mentions`, the agent will not automatically resume your original question after you connect — you'll need to ask again.
</Note>

### /omni model

Opens a menu to select your preferred Omni model. This is the model the agent will use when answering your questions.

* If your organization has multiple models, you'll see a dropdown to choose from
* If only one model is available, you'll see that model displayed
* If you don't have access to any models, you'll see a message asking you to contact your administrator

### /omni privacy

Toggles whether your responses in channels are visible to everyone or only to you.

* If your administrator allows **user-level** privacy control, you'll see a checkbox to toggle private responses on or off
* If your administrator has enforced **workspace-level** privacy, you'll see a message indicating that privacy is managed by your administrator

### /omni disconnect

Disconnects your Slack account from your Omni account. You'll be asked to confirm before the disconnection is completed. After disconnecting, you'll need to reconnect to ask questions again.

## Next steps

* [Delivering content to Slack](/share/deliveries/slack) - Schedule automated dashboard deliveries to Slack channels
* [Omni Agent](/ai/chat) - Use the Omni Agent directly in the Omni app
* [Workbook Agent](/ai/queries) - Get AI help building queries in workbooks


# Library
Source: https://docs.omni.co/library/index

Browse Omni Apps, Skills, and Routines by line of business and vertical. Copy a rebuild prompt, skill YAML, or routine prompt straight into your own Omni instance.

<div>
  <h1>Library</h1>

  <p>
    Explore, discover, and deploy <a href="/visualize-present/apps">Apps</a>, <a href="/ai/routines">Routines</a>, and <a href="/ai/skills">Skills</a> to jumpstart your AI transformation.
  </p>

  <ul>
    <li><strong>Apps</strong> are fully custom HTML and JavaScript interfaces — their own layout, components, and interactivity — powered by live queries from your workbook.</li>
    <li><strong>Routines</strong> run a prompt on a schedule and deliver the Omni Agent's written answer to the people you choose.</li>
    <li><strong>Skills</strong> package a set of instructions into a button anyone on your team can click in AI chat.</li>
  </ul>

  <LibraryGallery />
</div>


# Create a composite topic
Source: https://docs.omni.co/modeling/composite-topics/create

Create a composite topic in the model IDE, then refine its shared views, dimensions, and measures.

<Note>
  Composite topics are currently in beta, but available on all Omni instances.
</Note>

A composite topic combines existing topics so users can query across them from a single workbook. This guide covers creating one in the model IDE and optionally refining its shared views, dimensions, and measures.

## Requirements

To follow the steps in this guide, you'll need:

* At least **Modeler** permissions to create a composite topic in the shared model
* At least **two existing topics** that share at least one logical dimension (date, customer ID, region, etc.)

## Create the composite topic

<Steps>
  <Step title="Create the file">
    Composite topics live in their own file with the `.composite_topic` extension.

    1. Open the **Model IDE**.
    2. Click **File > New Composite topic**.
    3. Enter a name. This becomes the filename and the unique identifier — for example, `revenue_and_spend`.
    4. Pick the topics you want to combine.
    5. **Optional**. Choose whether Omni should auto-detect shared views across the topics.
    6. **Optional**. Add a **Group Label**.
    7. Click **Create**.

    Omni creates a `<name>.composite_topic` file with:

    * The `topics:` list you picked
    * A `shared_views:` list populated with any dimension tables joinable from every included topic, if you enabled auto-detection

    For many use cases, this file is enough — skip to [Save and use the composite topic](#save-and-use). Steps 2–4 cover optional refinements.
  </Step>

  <Step title="Optional: Refine shared views">
    A *shared view* is a dimension table joinable from every topic — typically a date spine, region table, or product catalog. If you enabled auto-detection during creation, Omni populates the list for you. Edit it as needed:

    ```yaml title="Refining shared_views" theme={null}
    topics: [orders_topic, marketing_topic]
    shared_views: [date_spine, regions]   # auto-detected; remove or add as needed
    ```

    Each shared view must be joinable from every included topic — either as the base view of every topic or through the model's relationships. The validator surfaces an error otherwise.

    Any topic can use a shared view's dimensions as join keys. Measures on a shared view are aggregated per topic, not combined. For example, if both an `orders` topic and a `marketing` topic use a shared `regions` view, the field picker shows a separate region count for each topic instead of one shared total.
  </Step>

  <Step title="Optional: Add shared dimensions">
    Shared dimensions handle the case where each topic has its own field for the same logical concept but at a different path.

    <Note>
      You don't need a shared dimension for a field that already lives in a shared view — the shared view's columns are usable as join keys directly.
    </Note>

    To define shared dimensions, use the `mappings:` syntax — each topic name is a key, and each value is the field path within that topic:

    ```yaml title="orders_and_marketing.composite_topic" theme={null}
    topics: [orders_topic, marketing_topic]
    label: "Revenue & Marketing"

    shared_dimensions:
      activity_date:
        label: "Activity date"
        description: "Aligns orders and marketing activity by day"
        mappings:
          orders_topic:
            field: orders.created_at
          marketing_topic:
            field: campaigns.start_date
    ```

    The shared dimension `activity_date` becomes a single selectable field in the workbook. When a user picks it, Omni includes `orders.created_at` in the orders subquery and `campaigns.start_date` in the marketing subquery, then joins on the resulting columns.
  </Step>

  <Step title="Optional: Add shared measures">
    A shared measure combines values from multiple topics in a single SQL expression. Define it in the `shared_measures` block and reference topic-scoped fields with `${topic_name.view.field}`.

    <Tip>
      To get the exact `${@topic.view.field}` reference, open a workbook on the composite topic, find the measure you want to reference, click the <Icon icon="ellipsis-vertical" type="solid" /> menu, and select **Modeling > Copy reference**. This copies the fully-resolved reference (for example, `${@orders_topic.orders.total_revenue}`) to your clipboard, which you can then paste directly into the shared measure SQL.

      <img alt="The field picker context menu showing Modeling > Copy reference highlighted" />
    </Tip>

    ```yaml title="Adding a shared measure" theme={null}
    topics: [orders_topic, marketing_topic]

    shared_dimensions:
      activity_date:
        label: "Activity date"
        mappings:
          orders_topic:
            field: orders.created_at
          marketing_topic:
            field: campaigns.start_date

    shared_measures:
      revenue_per_dollar_spent:
        label: "Revenue per $ spent"
        sql: ${orders_topic.orders.total_revenue} / NULLIF(${marketing_topic.campaigns.total_spend}, 0)
        format: usdcurrency_2
    ```

    A few important things about shared measures:

    * **Fields arrive pre-aggregated.** Each `${topic.view.field}` is already aggregated by the time the shared measure sees it — every topic runs its own subquery first.
    * **Referenced fields are auto-included.** Any field you reference is added to the right subquery; you don't need to also add it to the workbook.
    * **Filters on a shared measure run after the join.** For example, `revenue_per_dollar_spent > 1.5` is applied as a `WHERE` on the joined result in the generated SQL.

    <Warning>
      Write the `sql` as plain math over already-aggregated values — arithmetic, `CASE`, `COALESCE`, `NULLIF`, etc. Each referenced field is already a single aggregated value, so wrapping it in `SUM(...)` or `COUNT(...)` or setting `aggregate_type` re-aggregates over the post-join result, which usually isn't desirable.
    </Warning>
  </Step>

  <Step title="Save and use the composite topic">
    Save the file. The composite topic appears in the topic picker for any workbook on the same model. Open a workbook, select the composite topic, and mix fields from any of the included topics in a single query.
  </Step>
</Steps>

## Next steps

* [Composite topic examples](/modeling/composite-topics/examples) — worked composite topics you can adapt.
* [Composite topic parameters](/modeling/composite-topics/parameters) — the full parameter reference.


# Composite topic examples
Source: https://docs.omni.co/modeling/composite-topics/examples

Worked composite topics — a complete example, plus orders vs. shipments, a marketing funnel, and a constellation schema with a date spine.

<Note>
  Composite topics are currently in beta, but available on all Omni instances.
</Note>

Use these composite topic examples as adaptable starting points for your own model. See [Composite topic parameters](/modeling/composite-topics/parameters) for more information about specific parameters.

## Complete example

A composite topic using the most common parameters:

```yaml title="orders_and_marketing.composite_topic" wrap theme={null}
topics: [orders_topic, marketing_topic]

label: "Orders & Marketing"
description: "Revenue and marketing performance, aligned by date and region"

shared_views: [date_spine]

shared_dimensions:
  activity_date:
    label: "Activity date"
    description: "Date the order was placed or the campaign was active"
    ai_context: "Use this for any time-series comparison between orders and marketing."
    timeframes: [date, week, month, quarter, year]
    timeframe_metadata:
      date:
        label: "Day"
      week:
        label: "Week starting"
      month:
        label: "Month of activity"
      year:
        label: "Activity year"
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date

  region:
    label: "Region"
    mappings:
      orders_topic:
        field: orders.customer_region
      marketing_topic:
        field: campaigns.target_region

shared_measures:
  revenue_per_dollar_spent:
    label: "Revenue per $ spent"
    sql: ${orders_topic.orders.total_revenue} / NULLIF(${marketing_topic.campaigns.total_spend}, 0)
    format: usdcurrency_2

  total_activity:
    label: "Orders + campaigns"
    sql: ${orders_topic.orders.count} + ${marketing_topic.campaigns.count}
```

<Note>
  Shared measures should use plain math - such as arithmetic, `CASE`, `COALESCE`, `NULLIF`, etc. - over already-aggregated values. See [shared\_measures](/modeling/composite-topics/parameters/shared-measures) for details.
</Note>

## Orders vs. shipments by week

A classic fan-out scenario: every order has one or more shipments. Joining directly inflates order revenue.

```yaml title="orders_and_shipments.composite_topic" wrap theme={null}
topics: [orders_topic, shipments_topic]
label: "Orders & Shipments"

shared_dimensions:
  week:
    label: "Week"
    mappings:
      orders_topic:
        field: orders.created_at
      shipments_topic:
        field: shipments.shipped_at

shared_measures:
  fulfillment_rate:
    label: "Fulfillment rate"
    sql: ${shipments_topic.shipments.count} / NULLIF(${orders_topic.orders.count}, 0)
    format: percent_2
```

Pick **Week**, **Orders → Total revenue**, **Shipments → Shipment count**, and **Fulfillment rate** in a workbook, resulting in one row per week.

## Marketing funnel across systems

Each funnel stage lives in its own topic (separate fact tables in different schemas). The composite topic stitches them together by cohort week.

```yaml title="acquisition_funnel.composite_topic" wrap theme={null}
topics: [signups_topic, trials_topic, conversions_topic, churn_topic]
label: "Acquisition funnel"

shared_dimensions:
  cohort_week:
    label: "Cohort week"
    mappings:
      signups_topic:
        field: signups.signed_up_at
      trials_topic:
        field: trials.started_at
      conversions_topic:
        field: conversions.converted_at
      churn_topic:
        field: churn_events.churned_at

shared_measures:
  trial_to_paid_rate:
    label: "Trial → paid"
    sql: ${conversions_topic.conversions.count} / NULLIF(${trials_topic.trials.count}, 0)
    format: percent_2

  net_new_customers:
    label: "Net new customers"
    sql: ${conversions_topic.conversions.count} - ${churn_topic.churn_events.count}
```

Pick **Cohort week** plus the per-stage counts and shared measures in a workbook. This results in one row per cohort week, with each stage's volume and conversion rates side by side.

## Constellation schema with a date spine

When you want to chart multiple fact tables alongside a continuous date axis (no gaps for days with zero activity), use a `date_spine` shared view.

```yaml title="daily_kpis.composite_topic" wrap theme={null}
topics: [orders_topic, support_topic, product_usage_topic]
label: "Daily KPIs"

shared_views: [date_spine]
```

Pick the spine's date (**Date spine > Date**) plus one measure from each topic. Because `date_spine` is a shared view joined into every topic, every day appears as a row. This includes days with no orders, tickets, or usage events.

## Next steps

* [Create a composite topic](/modeling/composite-topics/create) — set one up in the model IDE.
* [Composite topic parameters](/modeling/composite-topics/parameters) — the full parameter reference.


# Composite topics
Source: https://docs.omni.co/modeling/composite-topics/index

Query across two or more topics in a single result — aligned on shared dimensions and views, without fan-out.

<Note>
  Composite topics are currently in beta, but available on all Omni instances.
</Note>

Composite topics — also called multi-fact tables — let you query across two or more independent topics in a single result set, sharing dimensions across them and filtering each topic by its own attributes. Each topic is aggregated independently in its own subquery, and the results are stitched together with a `FULL OUTER JOIN` on the dimensions and views you mark as shared.

Because each fact stays in its own subquery, every measure is computed against the correct grain. The result is a single analysis surface that pulls fields and filters from every topic.

## When to use a composite topic

Reach for a composite topic when both of the following are true:

* You want measures from two or more fact tables in the same chart, table, or dashboard tile
* The fact tables share at least one dimension you'd join on (date, customer, region, product)

If you only need measures from a single fact table — even if it joins to several dimension tables — a regular [topic](/modeling/topics) is the right choice.

### Common patterns

| Pattern                     | Example                                                                         |
| --------------------------- | ------------------------------------------------------------------------------- |
| **Multi-fact dashboard**    | Compare orders revenue vs. marketing spend by month and region in one tile      |
| **Cross-domain KPI report** | A single table with weekly metrics from sales, support, and product domains     |
| **Constellation schema**    | Multiple fact tables that all join to the same date or customer dimension       |
| **Funnel across systems**   | Trials, conversions, and churn — each as their own topic, joined on cohort date |

### Composite topics vs. XLOOKUP

[`XLOOKUP`](/analyze-explore/calculations/position#xlookup) also lets you pull values from another query into the current one. For one-off, exploratory work, it's often the faster choice. Composite topics are the right tool when the cross-fact analysis needs to be reusable, governed, and available to other users.

| Use case                                                               | Reach for           |
| ---------------------------------------------------------------------- | ------------------- |
| Quick ad-hoc lookup between two query tabs in a workbook               | **XLOOKUP**         |
| One-off comparison you don't expect to repeat                          | **XLOOKUP**         |
| Cross-fact analysis you want to publish, share, or build dashboards on | **Composite topic** |
| Reusable definition where the join logic should live in the model      | **Composite topic** |

## How it works

```mermaid theme={null}
flowchart TD
    User["You select fields from a composite topic in a workbook"]
    Split["Omni splits the query into one subquery per topic"]
    A["Topic A<br/>aggregates its facts"]
    B["Topic B<br/>aggregates its facts"]
    C["Topic C<br/>aggregates its facts"]
    Join["FULL OUTER JOIN on shared dimensions<br/>(CROSS JOIN if no shared dims selected)"]
    Post["Shared measures, calcs, sorts, pivots,<br/>and limits applied to the post-join result"]

    User --> Split
    Split --> A
    Split --> B
    Split --> C
    A --> Join
    B --> Join
    C --> Join
    Join --> Post
```

Each topic computes its measures independently. This means that results align on shared dimensions, ensuring there isn't any fan out.

## Field picker behavior

The workbook field picker organizes a composite topic's fields into a few groups:

| Group                 | Contents                                                                                                    |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Shared dimensions** | One entry per `shared_dimensions` definition. Selectable as a regular dimension.                            |
| **Shared measures**   | One entry per `shared_measures` definition. Selectable as a regular measure.                                |
| **Shared views**      | Dimensions from each shared view. Selectable. (Measures from shared views appear under each topic instead.) |
| **Per-topic**         | One group per included topic. Measures are selectable; dimensions are filter-only.                          |

## Limitations

* **Topic-specific dimensions cannot be in `SELECT`.** They can only be used as filters; selecting one returns a query error. This is by design — there's no outer `GROUP BY` to make the result deterministic.
* **Shared dimensions can map differently-named columns, but the values must align.** Use `mappings:` to point each topic at its own field — the columns don't need to share a name or SQL definition. They do need to represent the same logical value: if the underlying SQL differs in a way that changes the result (different timezone conversions, different casing, etc.), rows won't align on the join even though the model validates.
* **Shared measures don't re-aggregate.** Each per-topic subquery aggregates first, then the shared measure runs over the joined result row-by-row. Wrapping a field in `SUM(...)` or setting `aggregate_type:` won't re-aggregate the joined result — see [shared\_measures](/modeling/composite-topics/parameters/shared-measures) for details.
* **Filters on shared measures can't be pushed down.** They're applied as a `WHERE` on the post-join result. This is correct, but means a filter on a shared measure won't reduce the size of the per-topic subqueries.
* **Only topics with selected fields are included in the join by default.** To improve query performance, Omni only includes topics with selected fields in the `FULL OUTER JOIN`. If you need all topics included regardless of selection, set [`always_join_all_topics: true`](/modeling/composite-topics/parameters/always-join-all-topics).
* **Fields directives on included topics are enforced at query runtime.** If an included topic excludes fields via the [fields](/modeling/topics/parameters/fields) directive, those fields cannot be queried through the composite topic. Queries attempting to use excluded fields will return an error.
* **Included topics keep their access controls and AI context.** Access grants, row-level security, and AI context defined on each included topic apply when that topic is queried as part of a composite. A composite topic can also set its own [`required_access_grants`](/modeling/composite-topics/parameters/required-access-grants) to restrict access further. Member topics' grants are still enforced.

  <Note>
    Member-topic AI context is excluded when the composite topic itself is selected as the active topic in the Omni Agent. In this case, the composite's own `ai_context` and `sample_queries` govern the system prompt.
  </Note>

### Known bugs

* **Errors when flattening a pivot on a shared dimension.** If you build a pivot table on a composite topic where the pivot field is a shared dimension and click **Flatten**, the query returns `No such topic <subtopic name>`. A fix is in progress.

## Roadmap

<Tip>
  Composite topics are in beta and we want your feedback! We're especially interested in:

  * **Use cases that don't fit** — What cross-fact analyses are you trying to do that this doesn't support?
  * **YAML ergonomics** — Is the `shared_dimensions` / `shared_measures` / `shared_views` shape intuitive? Are there parameters you expected to find?
  * **Workbook UX rough edges** — Confusing menus, unclear errors, missing affordances
  * **Performance** — Slow plans, surprising query shapes, cases where the subquery breakdown produces expensive SQL

  Share feedback with your Omni representative or through Omni support.
</Tip>

See the following sections for future development plans for composite topics. If Omni plans to make breaking changes, we'll publish a migration note before release.

### Workbook

* **Consolidate composite topics into the main topic picker.** Composite topics appear in their own group rather than mixing into existing topic subfolders alongside regular topics. We plan to surface them together so end users don't need to distinguish between the two.
* **Workbook-side editing for composite topics**, similar to the topic editor for regular topics.
* **Promote a calculation to a shared measure.** If you build a calculation in a workbook that combines fields from multiple topics, you'll be able to promote it directly into the composite topic's `shared_measures` block.
* General workbook UI improvements

## Next steps

* [Create a composite topic](/modeling/composite-topics/create) — Set up a composite topic in the model IDE and refine its shared views, dimensions, and measures
* [Composite topic examples](/modeling/composite-topics/examples) — Worked composite topics you can adapt
* [Composite topic parameters](/modeling/composite-topics/parameters) — Full parameter reference for composite topics
* [Curating datasets with topics](/modeling/topics) — Overview of regular topics and how they fit into the model


# always_join_all_topics - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/always-join-all-topics

Controls whether all topics are included in the FULL OUTER JOIN or only those with selected fields.

Controls whether all topics defined in the composite topic are included in the `FULL OUTER JOIN` or only those with selected fields. Defaults to `false`, meaning only topics with selected fields are included for better query performance.

## Syntax

```yaml theme={null}
always_join_all_topics: <boolean>
```

## Properties

<ParamField type="boolean">
  When `false` (default), only topics with selected fields are included in the `FULL OUTER JOIN`, improving performance by pruning unused topics. When `true`, all topics are included in the join regardless of whether fields are selected from them.
</ParamField>

## Behavior

By default (`always_join_all_topics: false`), Omni optimizes composite topic queries by only including topics in the `FULL OUTER JOIN` that have selected fields. This can significantly improve query performance, especially when you have several topics defined but only need measures or dimensions from a subset of them.

Setting `always_join_all_topics: true` restores the original behavior where all topics are included in the join regardless of selection. This guarantees that dimension values from all topics appear in the result, even when no fields from a particular topic are selected.

**Consider setting `always_join_all_topics: true` when:**

* You need dimension values from all topics to appear in results, even when fields from some topics aren't selected
* You're migrating from the original composite topic behavior and need to maintain backward compatibility
* The completeness of dimension values across all topics is more important than query performance

## Examples

### Default behavior (performance optimized)

In this example, if you select only fields from the `orders` topic, the `FULL OUTER JOIN` will only include `orders` rather than all three topics.

```yaml theme={null}
topics:
  - orders
  - marketing_spend
  - customer_support

# always_join_all_topics defaults to false
```

### Include all topics

In this example, all three topics are included in the `FULL OUTER JOIN` even if you only select fields from `orders`.

```yaml theme={null}
topics:
  - orders
  - marketing_spend
  - customer_support

always_join_all_topics: true
```


# cache_policy - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/cache-policy

Sets the cache policy for the composite topic.

Sets the cache policy for the composite topic. Cache policies are defined at the model level using the [`cache_policies`](/modeling/models/cache-policies) parameter.

## Syntax

```yaml theme={null}
cache_policy: <policy_name>
```

## Properties

<ParamField type="string">
  The name of a cache policy defined in the model file. Must reference a policy from the model's [`cache_policies`](/modeling/models/cache-policies) configuration.
</ParamField>

## Behavior

When `cache_policy` is unset, the composite topic resolves its effective cache policy to the shortest `max_cache_age` among its sub-topics. This ensures the composite is never served staler than its strictest member.

## Examples

### Explicit cache policy

```yaml theme={null}
cache_policy: daily_cache_policy
```

### Default resolution behavior

If `cache_policy` is unset, the composite uses the shortest `max_cache_age` from its component topics:

```yaml theme={null}
# Composite topic with no explicit cache_policy
topics:
  - orders_topic        # has cache_policy: hourly_cache (max_cache_age: 1 hour)
  - marketing_topic     # has cache_policy: daily_cache (max_cache_age: 24 hours)
  - support_topic       # no cache_policy, falls back to model's default_cache_policy

# The composite resolves to the shortest max_cache_age (1 hour from orders_topic)
```


# default_filters - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/default-filters

Applies a filter to all queries that start on the composite topic.

Applies a filter to all queries that start on the composite topic. Filters created using this parameter are visible in workbooks and can be removed by users.

When a new `default_filter` is defined, it will only apply to new queries. The filter will not be added to existing queries.

Refer to the [Filters documentation](/modeling/filters) for filter operator syntax and examples.

## Syntax

```yaml theme={null}
default_filters:
  <field_reference>:
    <filter_operator>: <value>
```

## Properties

<ParamField type="object">
  A map of field references to filter conditions.

  <Expandable title="default_filter properties">
    <ParamField type="object">
      The field to filter on, specified in one of the following formats:

      * **Shared dimension or measure name**: `created_date`
      * **Shared view field**: `view.field` (e.g., `users.state`)
      * **Topic-scoped field**: `topic.view.field` (e.g., `orders_topic.orders.status`)

      <Expandable title="filter operators">
        <ParamField type="any">
          The filter operator and value to apply. Refer to the [filter syntax documentation](/modeling/filters) for available operators like `is`, `not`, `contains`, `greater_than`, etc.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Default filter on shared dimension

```yaml theme={null}
default_filters:
  created_date:
    time_for_duration: '30 days ago for 30 days'
```

### Default filter on topic-scoped field

```yaml theme={null}
default_filters:
  orders_topic.orders.status:
    is: complete
```

### Default filter on shared view field

```yaml theme={null}
default_filters:
  users.state:
    is: California
```

### Multiple default filters

```yaml theme={null}
default_filters:
  created_date:
    time_for_duration: '30 days ago for 30 days'
  orders_topic.orders.status:
    is: complete
  users.state:
    is: California
```


# description - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/description

Free text describing the composite topic, shown in the topic picker.

Free text describing the composite topic. The description is shown in the topic picker to help users choose the right dataset.

## Syntax

```yaml theme={null}
description: <string>
```

## Properties

<ParamField type="string">
  A description of the composite topic, surfaced in the topic picker. Quote the value if it contains a colon, comma, or other special character.
</ParamField>

## Examples

```yaml theme={null}
description: "Revenue and marketing performance, aligned by date and region"
```


# fields - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/fields

Curates which fields each sub-topic contributes to the field picker.

Curates which fields each sub-topic contributes to the field picker. Use the `@topic`-scoped syntax to include or exclude specific fields, views, or tags from individual sub-topics — or apply global directives across all sub-topics.

The `fields:` parameter addresses the "too many filterable dimensions" noise that can occur when combining multiple topics. It filters which fields appear in the field picker, but doesn't restrict queries — queries against excluded fields still execute, so existing saved queries don't break.

<Note>
  The `fields:` parameter intersects with each sub-topic's own `fields:` directive — it can only narrow what a sub-topic already exposes, not add fields the sub-topic has already excluded.
</Note>

## Syntax

```yaml theme={null}
fields:
  - "@<topic_name>.<view>.<field>"       # include a specific field from one topic
  - "@<topic_name>.<view>.*"             # include all fields from a view in one topic
  - "@<topic_name>.<view>"               # include all fields from a view in one topic
  - "@<topic_name>.<view>:tag:<tag>"     # include fields by tag from one topic
  - "-@<topic_name>.<view>.<field>"      # exclude a specific field from one topic
  - "-@<topic_name>.<view>"              # exclude an entire view from one topic
  - "<view>.<field>"                     # global: applies to all sub-topics
  - "-tag:<tag>"                         # global: exclude tagged fields from all sub-topics
```

## Properties

<ParamField type="string[]">
  A list of field directives. Each directive either includes or excludes fields from the field picker.

  **`@topic`-scoped directives** apply to a single sub-topic:

  * `@<topic_name>.<view>.<field>` — include a specific field
  * `@<topic_name>.<view>.*` or `@<topic_name>.<view>` — include all fields from a view
  * `@<topic_name>.<view>:tag:<tag>` — include fields by tag
  * `-@<topic_name>.<view>.<field>` — exclude a specific field
  * `-@<topic_name>.<view>` — exclude an entire view

  **Global directives** (without `@topic`) apply to every sub-topic:

  * `<view>.<field>`, `tag:<tag>`, `set:<set>` — include patterns across all topics
  * `-tag:<tag>`, `-<view>.<field>` — exclude patterns across all topics

  **Include vs. exclude behavior:**

  * If all directives are excludes (start with `-`), everything else is included
  * If any directive is an include (no `-`), the list becomes a whitelist — only explicitly included fields appear

  **A sub-topic with no matching `@topic`-scoped directive is left untouched** — so scoping to topic A never hides fields from topic B.
</ParamField>

## Examples

The following examples assume a composite topic that combines sub-topics named `sales` and `marketing`.

```yaml title="Include specific views from each topic" theme={null}
fields:
  - "@sales.orders.*"              # include all orders fields from sales
  - "@marketing.campaigns.*"       # include all campaigns fields from marketing
```

```yaml title="Exclude specific fields" theme={null}
fields:
  - "-@sales.orders.internal_id"   # exclude one field from sales' orders view
  - "-@marketing.campaigns"        # drop the entire campaigns view from marketing
```

```yaml title="Global exclusions across all topics" theme={null}
fields:
  - "-tag:pii"                     # exclude PII-tagged fields from all topics
```

```yaml title="Mix scoped includes with global excludes" theme={null}
fields:
  - "@sales.orders.*"              # include all of orders from sales
  - "-@sales.orders.internal_id"   # but exclude one specific field
  - "-@marketing.campaigns"        # drop campaigns view from marketing
  - "-tag:pii"                     # global: exclude PII fields everywhere
```

## Intersection with sub-topic `fields:`

The composite topic's `fields:` parameter is applied **on top of** each sub-topic's own `fields:` directive. The result is an intersection — the composite can only narrow what the sub-topic already exposes.

If a sub-topic has:

```yaml theme={null}
fields:
  - orders.*
  - -orders.internal_notes
```

And the composite topic has:

```yaml theme={null}
fields:
  - "@sales_topic.orders.total_revenue"
```

The field picker shows only `orders.total_revenue` from that topic — the intersection of the sub-topic's `orders.*` (minus `internal_notes`) and the composite's scoped include.

## Picker-only filtering

The `fields:` parameter only affects which fields appear in the field picker. Queries against excluded fields still execute — this ensures existing saved queries and dashboards don't break when you refine the field list.

If a user has a saved query that references `@sales.orders.internal_id`, that query continues to run even after you add `-@sales.orders.internal_id` to the composite topic's `fields:` list.

<Note>
  Picker-only filtering applies to the composite topic's **own** `fields:` parameter. It does **not** relax an included topic's own [`fields:`](/modeling/topics/parameters/fields) directive, which is enforced at query runtime — fields that a sub-topic excludes cannot be queried through the composite topic and will return an error.
</Note>


# Composite topic parameters
Source: https://docs.omni.co/modeling/composite-topics/parameters/index

Composite topic files define configuration for querying across two or more topics.

<Note>
  Composite topics are currently in beta, but available on all Omni instances.
</Note>

Composite topics are defined in `.composite_topic` files. The parameters below configure which topics are combined and how their fields align. For an overview, see [Composite topics](/modeling/composite-topics); for setup, see [Create a composite topic](/modeling/composite-topics/create).

| Parameter                                                                                 | Description                                                                                                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [always\_join\_all\_topics](/modeling/composite-topics/parameters/always-join-all-topics) | Controls whether all topics are included in the `FULL OUTER JOIN` or only those with selected fields.              |
| [cache\_policy](/modeling/composite-topics/parameters/cache-policy)                       | Sets the cache policy for the composite topic; defaults to the shortest `max_cache_age` among its sub-topics.      |
| [default\_filters](/modeling/composite-topics/parameters/default-filters)                 | Applies a filter to all queries that start on the composite topic.                                                 |
| [description](/modeling/composite-topics/parameters/description)                          | Free text describing the composite topic, shown in the topic picker.                                               |
| [fields](/modeling/composite-topics/parameters/fields)                                    | Curates which fields each sub-topic contributes to the field picker.                                               |
| [label](/modeling/composite-topics/parameters/label)                                      | Defines a display name for the composite topic.                                                                    |
| [required\_access\_grants](/modeling/composite-topics/parameters/required-access-grants)  | Defines a list of access grants for the composite topic itself, in addition to its member topics' grants.          |
| [sample\_queries](/modeling/composite-topics/parameters/sample-queries)                   | Defines sample queries that can be performed on the composite topic, used by the Omni Agent and shown as examples. |
| [shared\_dimensions](/modeling/composite-topics/parameters/shared-dimensions)             | Defines cross-topic join keys that align the included topics.                                                      |
| [shared\_measures](/modeling/composite-topics/parameters/shared-measures)                 | Defines measures that combine values across topics after the join.                                                 |
| [shared\_views](/modeling/composite-topics/parameters/shared-views)                       | Defines dimension tables joinable from every included topic, such as a date spine.                                 |
| [topics](/modeling/composite-topics/parameters/topics)                                    | **Required**. The two or more topics to combine.                                                                   |


# label - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/label

Defines a display name for the composite topic.

Defines a display name for the composite topic as it appears in the topic picker. Defaults to a humanized version of the filename.

## Syntax

```yaml theme={null}
label: <display_name>
```

## Properties

<ParamField type="string">
  The display name for the composite topic that appears in the topic picker. Quote the value if it contains a colon, comma, or other special character.
</ParamField>

## Examples

```yaml theme={null}
label: "Orders & Marketing"
```


# required_access_grants - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/required-access-grants

Defines a list of access grants for the composite topic itself, in addition to its member topics' grants.

Defines a list of access grants for the composite topic, which are used to control access. These grants apply in addition to the grants on each member topic. The values of this parameter must match the name of an access grant in the model file's [`access_grants`](/modeling/models/access-grants) parameter.

Refer to the [Controlling data access guide](/modeling/develop/data-access-control) for more information and examples.

## Syntax

```yaml theme={null}
required_access_grants: [<grant_name>]

# OR condition
required_access_grants: [<grant_one>|<grant_two>]

# AND/OR conditions
required_access_grants: [<grant_one>|<grant_two>&<grant_three>]

# Opt out of the model's default_topic_required_access_grants.
# Access is controlled by the member topics' grants only.
required_access_grants: []
```

## Properties

<ParamField type="string[]">
  An array of access grant names that control access to the composite topic. Each value must match an access grant defined in the model file. Use `|` for `OR` conditions and `&` for `AND` conditions within the same array element.
</ParamField>

## Behavior

These grants apply in addition to each member topic's grants. They can restrict access to the composite topic, but they can't grant access to member topic data a user is otherwise denied.

If omitted, the model's [`default_topic_required_access_grants`](/modeling/models/default-topic-required-access-grants) applies, even when every member topic opts out of it. Set `required_access_grants: []` to exclude the composite topic from the default.

## Examples

The examples in this section use the following model and topics. In each table, the columns are user groups, where **Both** is a user in Finance and Marketing.

```yaml title="Model file" theme={null}
access_grants:
  finance:
    user_attribute: omni_user_groups
    allowed_values: [Finance]
  marketing:
    user_attribute: omni_user_groups
    allowed_values: [Marketing]
```

`campaigns` requires the `marketing` grant. `orders` has no grants.

```yaml title="campaigns.topic" theme={null}
required_access_grants: [marketing]
```

### Restrict the composite topic

The composite topic requires `finance`.

```yaml title="orders_and_marketing.composite_topic" highlight={2} theme={null}
topics: [orders, campaigns]
required_access_grants: [finance]
```

With the `marketing` grant from `campaigns`, a user needs both `finance` and `marketing` to query it.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Topic</th>
      <th>Finance</th>
      <th>Marketing</th>
      <th>Both</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orders</code></td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><code>campaigns</code></td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><strong><code>orders\_and\_marketing</code></strong></td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

### Grant access if either condition is met

Use a pipe (`|`) to require one of several grants. The composite topic requires `finance` or `marketing`.

```yaml title="orders_and_marketing.composite_topic" highlight={2} theme={null}
topics: [orders, campaigns]
required_access_grants: [finance|marketing]
```

With the `marketing` grant from `campaigns`, a user needs `marketing` to query it.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Topic</th>
      <th>Finance</th>
      <th>Marketing</th>
      <th>Both</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orders</code></td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><code>campaigns</code></td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><strong><code>orders\_and\_marketing</code></strong></td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

### Opt out of the model default

The model default is `finance`, and both member topics opt out of it.

```yaml title="Model file" theme={null}
default_topic_required_access_grants: [finance]
```

```yaml title="orders.topic" theme={null}
required_access_grants: []
```

```yaml title="campaigns.topic" theme={null}
required_access_grants: [marketing]
```

Two composite topics use the same member topics. `orders_and_marketing` sets `required_access_grants: []`, so it requires only `marketing`.

```yaml title="orders_and_marketing.composite_topic" highlight={2} theme={null}
topics: [orders, campaigns]
required_access_grants: []
```

`campaign_performance` does not set `required_access_grants`, so the model default applies and it requires `finance` and `marketing`.

```yaml title="campaign_performance.composite_topic" theme={null}
topics: [orders, campaigns]
```

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Topic</th>
      <th>Finance</th>
      <th>Marketing</th>
      <th>Both</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orders</code></td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><code>campaigns</code></td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><strong><code>orders\_and\_marketing</code></strong></td>
      <td>❌</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td><strong><code>campaign\_performance</code></strong></td>
      <td>❌</td>
      <td>❌</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>


# sample_queries - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/sample-queries

Defines a list of sample queries that could be performed on the composite topic.

Defines a list of sample queries that could be performed on the composite topic, which is used:

* **To present example queries** when a composite topic is selected in the workbook or using the [Omni Agent](/ai/chat).

  To hide the query, set the `hidden` parameter to `true`.
* [**By the Omni Agent to improve results.**](/ai/chat) To exclude the query from the composite topic's AI context, set the `exclude_from_ai_context` to `true`.

You can add a workbook query to this parameter using one of the following methods:

* **From the Model menu**: Click **Model > Save as sample query to topic** in the workbook.
* **From the inspector**: Click the <Icon icon="bug" /> near the bottom left corner of the page to open the [workbook inspector](/analyze-explore/workbook-inspector). Click **Copy query and visualization YAML** in the inspector header to copy the query and visualization configuration in the sample query format, then paste it into your composite topic file in the model IDE.

## Syntax

```yaml theme={null}
sample_queries:
  <query_name>:
    query:
      fields: [ "<field_one>", "<field_two>", ... ]
      base_view: "<composite_topic_name>"
      calculations:
        <calculation_name>:
          sql: "<sql_expression>"
      limit: <number>
      sorts:
        - field: "<field_name>"
          desc: true/false
      topic: "<composite_topic_name>"
    description: "<query_description>"
    hidden: true/false
    prompt: "<natural_language_prompt>"
    ai_context: "<ai_context_description>"
    exclude_from_ai_context: true/false
```

## Properties

<ParamField type="object">
  The name of the sample query (e.g., "Summary Stats"). Each query is defined as a key in the `sample_queries` object.

  <Expandable title="query properties">
    <ParamField type="object">
      The query definition object containing the structure of the query to be executed.

      <Expandable title="query properties">
        <ParamField type="string[]">
          List of fields to include in the query. Can include shared dimensions, shared measures, and per-topic fields from the composite topic.
        </ParamField>

        <ParamField type="string">
          The composite topic to query from.
        </ParamField>

        <ParamField type="object">
          Optional calculations to include in the query. Each calculation is defined with a name and SQL expression.

          <Expandable title="calculation properties">
            <ParamField type="string">
              The SQL expression for the calculation.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="number">
          Maximum number of rows to return.
        </ParamField>

        <ParamField type="object[]">
          List of fields to sort the results by.

          <Expandable title="sort properties">
            <ParamField type="string">
              The field name to sort by.
            </ParamField>

            <ParamField type="boolean">
              When set to `true`, sorts the field in descending order. Omit or set to `false` to sort in ascending order.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          The name of the composite topic used in the query.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      A human-readable description of what the query does or what insights it provides.
    </ParamField>

    <ParamField type="boolean">
      When set to `true`, hides the query from being presented as an example query in the workbook or embedded Omni Agent.
    </ParamField>

    <ParamField type="string">
      A natural language prompt that represents how a user might ask for this query. Used by the Omni Agent.
    </ParamField>

    <ParamField type="string">
      Additional context to help the Omni Agent understand how to use this query or what it demonstrates.
    </ParamField>

    <ParamField type="boolean">
      When set to `true`, excludes this query from the composite topic's AI context, preventing the AI from using it as a reference.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
sample_queries:
  Cross-Topic Summary:
    query:
      fields: [ shared_date.month, order_items.sale_price_sum, marketing.spend_sum, calc_1 ]
      base_view: orders_marketing_composite
      calculations:
        calc_1:
          sql: OMNI_FX_SAFE_DIVIDE(${order_items.sale_price_sum}, ${marketing.spend_sum})
      limit: 1000
      sorts:
        - field: shared_date.month
          desc: true
      topic: orders_marketing_composite
    description: Monthly revenue, marketing spend, and revenue per dollar spent
    hidden: false
    prompt: show me monthly revenue compared to marketing spend with ROI
    ai_context: demonstrates querying across multiple topics with a shared date dimension and custom calculation for ROI
    exclude_from_ai_context: false
```


# shared_dimensions - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/shared-dimensions

Defines cross-topic join keys that align the included topics.

Defines cross-topic join keys for the composite topic. A shared dimension handles the case where each topic has its own field for the same logical concept at a different path — for example, an order date in one topic and a campaign start date in another. The shared dimension becomes a single selectable field, and Omni joins each topic's subquery on its mapped field.

<Note>
  You don't need a shared dimension for a field that already lives in a [shared view](/modeling/composite-topics/parameters/shared-views) — the shared view's columns are usable as join keys directly.
</Note>

## Syntax

```yaml theme={null}
shared_dimensions:
  <dimension_name>:
    label: <string>
    description: <string>
    ai_context: <string>
    display_order: <integer>
    timeframes: [<timeframe>, ...]   # date/timestamp dimensions only
    timeframe_metadata:              # date/timestamp dimensions only
      <timeframe_name>:
        label: <string>
        format: <string>
        group_label: <string>
    mappings:
      <topic_name>:
        field: <view.field>
```

## Properties

<ParamField type="object">
  A map of shared dimension definitions, keyed by the dimension's name. The name becomes the selectable field in the workbook.

  <Expandable title="shared dimension properties">
    <ParamField type="string">
      The display name for the shared dimension in the field browser.
    </ParamField>

    <ParamField type="string">
      A description of the shared dimension.
    </ParamField>

    <ParamField type="string">
      Context passed to the Omni Agent for this shared dimension.
    </ParamField>

    <ParamField type="integer">
      Overrides the ordering of the shared dimension in the field browser.
    </ParamField>

    <ParamField type="object">
      One entry per included topic, mapping the topic to the field it contributes to the join. Each shared dimension needs a `mappings` entry for **every topic in the composite** — missing mappings surface as a validator error in the IDE. The mapped columns don't need to share a name, but they must represent the same logical value.

      <Expandable title="mappings properties">
        <ParamField type="string">
          The field within that topic, in the format `view.field`. Use the bare field name — for date and timestamp dimensions, the timeframe (Day, Week, Month, …) is chosen when querying the shared dimension, not set in the mapping.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string[]">
      For shared dimensions that map to date or timestamp fields, this array specifies which timeframes are available for selection. If absent, Omni uses default timeframes: `raw`, `date`, `week`, `month`, `quarter`, `year`. See the [timeframes reference](/modeling/dimensions/parameters/timeframes) for all supported timeframe values.
    </ParamField>

    <ParamField type="object">
      For shared dimensions that map to date or timestamp fields, this allows you to override properties for specific timeframes. Common use cases include customizing labels or formats for individual timeframes.

      <Expandable title="timeframe_metadata properties">
        <ParamField type="object">
          The name of the timeframe (e.g., `date`, `week`, `month`). Each timeframe can have the following properties:

          * `label` — custom display name for this timeframe
          * `format` — formatting override for this timeframe
          * `group_label` — group label override for this timeframe
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Align orders and marketing by day" theme={null}
shared_dimensions:
  activity_date:
    label: "Activity date"
    description: "Date the order was placed or the campaign was active"
    ai_context: "Use this for any time-series comparison between orders and marketing."
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date
```

```yaml title="Custom timeframes on shared dimension" theme={null}
shared_dimensions:
  activity_date:
    label: "Activity date"
    timeframes: [date, week, month, quarter]
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date
```

```yaml title="Custom timeframe labels with timeframe_metadata" theme={null}
shared_dimensions:
  activity_date:
    label: "Activity date"
    timeframes: [date, week, month, quarter, year]
    timeframe_metadata:
      date:
        label: "Day"
      week:
        label: "Week starting"
      month:
        label: "Month of activity"
      year:
        label: "Activity year"
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date
```


# shared_measures - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/shared-measures

Defines measures that combine values across topics after the join.

Defines measures that combine already-aggregated values from multiple topics in a single SQL expression. Each topic runs its own subquery first, so every `${topic.view.field}` reference is a single aggregated value by the time the shared measure sees it. Any field you reference is auto-included in the right subquery — you don't need to also add it to the workbook.

<Warning>
  Write the `sql` as plain math over already-aggregated values — arithmetic, `CASE`, `COALESCE`, `NULLIF`, etc. Each referenced field is already a single aggregated value, so wrapping it in `SUM(...)` or `COUNT(...)` or setting `aggregate_type` re-aggregates over the post-join result, which usually isn't desirable.
</Warning>

## Syntax

```yaml theme={null}
shared_measures:
  <measure_name>:
    label: <string>
    description: <string>
    format: <format>
    sql: <expression using ${topic_name.view.field}>
```

## Properties

<ParamField type="object">
  A map of shared measure definitions, keyed by the measure's name. The name becomes the selectable measure in the workbook.

  <Expandable title="shared measure properties">
    <ParamField type="string">
      The SQL expression combining topic-scoped fields, referenced as `${topic_name.view.field}`. Filters on a shared measure are applied as a `WHERE` on the post-join result.
    </ParamField>

    <ParamField type="string">
      The display name for the shared measure in the field browser.
    </ParamField>

    <ParamField type="string">
      A description of the shared measure.
    </ParamField>

    <ParamField type="string">
      The number format for the measure's values. Accepts any Omni [named format](/modeling/models/format-values) (for example, `usdcurrency_2` or `percent_2`), an Excel-style string, or a conditional format.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Revenue per dollar of marketing spend" theme={null}
shared_measures:
  revenue_per_dollar_spent:
    label: "Revenue per $ spent"
    sql: ${orders_topic.orders.total_revenue} / NULLIF(${marketing_topic.campaigns.total_spend}, 0)
    format: usdcurrency_2
```


# shared_views - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/shared-views

Dimension tables joinable from every included topic, such as a date spine.

Defines dimension tables that are joinable from every included topic — typically a date spine, region table, or product catalog. Omni auto-detects shared views on file creation; edit the list as needed.

Dimensions from a shared view are selectable as join keys for any topic. Measures on a shared view are aggregated **per topic**, not combined.

## Syntax

```yaml theme={null}
shared_views: [<view_name>, <view_name>, ...]
```

## Properties

<ParamField type="string[]">
  A list of view names joinable from every included topic — either as the base view of every topic or through the model's relationships. The validator surfaces an error if a listed view is not joinable from every topic.
</ParamField>

## Examples

```yaml theme={null}
shared_views: [date_spine, regions]
```

Because a shared view like `date_spine` is joined into every topic, every row in the spine appears in the result — for example, every day appears even when a topic has no activity that day.


# topics - Composite topics
Source: https://docs.omni.co/modeling/composite-topics/parameters/topics

The two or more topics to combine into a composite topic.

**Required**. The two or more existing topics to combine into a composite topic. Each topic is aggregated independently in its own subquery, then aligned on the shared dimensions and views.

## Syntax

```yaml theme={null}
topics: [<topic_name>, <topic_name>, ...]
```

## Properties

<ParamField type="string[]">
  A list of two or more existing topic names in the same model. Each must resolve to a topic the composite can query.
</ParamField>

## Examples

```yaml theme={null}
topics: [orders_topic, marketing_topic]
```


# Optimize models for Omni AI
Source: https://docs.omni.co/modeling/develop/ai-optimization

Use context to curate your models and improve the accuracy & relevance of Omni's 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What does Omni AI use for context?">
    Omni uses the following for context, in priority order:

    <Steps>
      <Step title="Context and tuning pre-built by the Omni Engineering team" />

      <Step title="The ai_context parameters in the model, topics and views, if provided" />

      <Step title="Topic's description, if provided" />

      <Step title="Topic's name and base_view" />

      <Step title="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?](#context-limits)
      </Step>

      <Step title="Pruned field properties">
        If a topic's metadata exceeds the space Omni allots for it (see [What limitations does context have?](#context-limits)), Omni prunes the following properties, starting with the lowest priority. Each property is removed from every field before the next is considered:

        1. `all_values` - The field's possible values. Pruned first because the AI can retrieve a field's values on demand when it needs them.
        2. `sql` - The field's SQL definition, when included
        3. `sample_values` - Example values for the field
        4. `description`
        5. `group_label` - The categorization of the field
        6. `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`
        7. `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.
        8. `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.
        9. `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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Where does context apply?">
    Context applies to:

    * Omni Agent and [embedded chat instances](/embed/customization/ai-chat), including topic selection and model search
    * [Workbook Agent](/ai/queries), including query and SQL generation
    * [Chat with Content](/ai/dashboard-assistant) summaries
    * AI visualization generation and summary visualizations
    * AI filter generation
    * [Modeling Agent](/ai/model-assistant) and modeling workflows, such as topic metadata generation and learn-from-conversation
  </Accordion>

  <Accordion title="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?](#context-priority).
    * **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`](/modeling/models/parameters/ai-settings/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](/analyze-explore/workbook-inspector#ai-messages) to see the context the AI actually received, and curate with [`ai_fields`](/modeling/topics/parameters/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](/modeling/models/parameters/ai-settings/conversation-prune-length) for more information.
  </Accordion>

  <Accordion title="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](/ai/security) for more information.
  </Accordion>
</AccordionGroup>

## 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.

<Tip>
  Use the [workbook inspector](/analyze-explore/workbook-inspector#ai-messages) to view and debug the context for a given AI session.
</Tip>

## Curate AI outputs across the model

You can use the model parameter [`ai_context`](/modeling/models/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](/administration/users/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.

```yaml title="Topic ai_context using user attributes" wrap theme={null}
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}}.
```

<Note>
  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.
</Note>

### 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`:

```yaml title="Model-level ai_context with omni_llm" wrap theme={null}
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:

```yaml title="Topic-level ai_context with omni_llm" wrap theme={null}
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](/modeling/models/ai-context), [topics](/modeling/topics/parameters/ai-context), and [views](/modeling/views/parameters/ai-context) 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:

```yaml title="Model-level ai_context with omni_agent" wrap theme={null}
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:

```yaml title="Topic-level ai_context with omni_agent" wrap theme={null}
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](/modeling/models/ai-context), [topics](/modeling/topics/parameters/ai-context), and [views](/modeling/views/parameters/ai-context) for more information and examples.

### Use constants for reusable AI context

You can define reusable AI instruction blocks as [`constants`](/modeling/models/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.

```yaml title="Model file with reusable AI context constants" theme={null}
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](/modeling/models/constants#reusable-ai-context) 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`](/modeling/models/ai-context).

This can be altered and tweaked if needed, but the reference to `GenerateQuery` is required for proper behavior.

```yaml wrap theme={null}
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](#model-specific-context) 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:

```yaml wrap theme={null}
ai_context: |
  When generating a summary, always output the summary in both English and Spanish.
```

## Curate topics

[Topics](/modeling/topics) have an [`ai_context`](/modeling/topics/parameters/ai-context) parameter, which is useful for providing behavioral prompts and guidance for handling certain questions specific to the topic.

For example:

```yaml title="ai_context for e-commerce orders topic" wrap expandable theme={null}
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
```

<Tip>
  You can use the [`ai_chat_topics`](/modeling/models/ai-chat-topics) model parameter to curate the list of topics that the Omni Agent or [embedded chat instances](/embed/customization/ai-chat) have access to.
</Tip>

### 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`](/modeling/topics/parameters/ai-fields) parameter in a topic. For included fields, you can also provide additional [context at the field level](#curate-views-and-fields).

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`](/modeling/topics/parameters/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:

```yaml title="Order Transactions topic" theme={null}
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:

```yaml title="Orders for AI querying topic, extended from Order Transactions" theme={null}
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`](/modeling/topics/parameters/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:

1. Create a query in a workbook that contains the correct answer to the question.
2. In the workbook, click **Model > Save as sample query to topic**.
3. 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
4. When finished, click **Save**.

<Tip>
  You can also use the [model-level `sample_queries` parameter](/modeling/models/sample-queries) to define example queries that could be performed using the topics contained in the model.
</Tip>

## Curate views and fields

[Views](/modeling/views) also have an [`ai_context`](/modeling/views/parameters/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](/integrations/dbt/setup) 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.

<AccordionGroup>
  <Accordion title="In the workbook">
    1. In the field browser, click the <Icon icon="ellipsis-vertical" /> (three dots icon) next to the field.
    2. Click **Modeling > Edit** to open the **Edit field** side panel.

       <img alt="Workbook AI parameters panel" />
  </Accordion>

  <Accordion title="In the IDE">
    In the IDE, navigate to the view containing the field to add the parameters. For example:

    ```yaml title="products.view" wrap theme={null}
    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.
    ```
  </Accordion>
</AccordionGroup>


# Validating model changes with the Content Validator
Source: https://docs.omni.co/modeling/develop/content-validator

Keep your content accurate and up-to-date as your data model evolves with the Content Validator.

If a field is renamed, a table is swapped, or a topic is removed, the validator makes it easy to spot where things broke and quickly fix them - either one by one or in bulk.

Additionally, the Content Validator is a powerful discovery tool: you can search for all the content that references a specific field, view, or topic to see how widely it’s used before making changes. This way, you can make updates with confidence and ensure nothing slips through the cracks.

<img alt="" />

## Content Validator basics

<AccordionGroup>
  <Accordion title="What is the Content Validator?">
    The Content Validator is a tool that allows you to visualize how content is impacted when the model or references in the database change. You can use it to identify where topics, views, and fields are being used and make updates before (or when) things break.
  </Accordion>

  <Accordion title="Who can use the Content Validator?">
    Users with [**Connection Admin**, **Modeler**, or **Querier** permissions](/administration/users/permissions) can access the Content Validator.

    **Note**: Queriers will only be able to see metadata for the content that they have access to. Otherwise, document and query titles will be displayed as `[Content not accessible]` and `[Query not accessible]`:

    <img alt="" />
  </Accordion>

  <Accordion title="Do I have to use a branch with the Content Validator?">
    No, **but it's strongly recommended**. Using a branch allows you to test and review your changes before making any modifications to the live environment. Refer to the [Developing content & models with Branch Mode guide](/content/develop/branch-mode) for more information about using branches in Omni.
  </Accordion>
</AccordionGroup>

## Accessing the Content Validator

Users with **Connection Admin**, **Modeler**, or **Querier** permissions can access the Content Validator by opening a model in the IDE and clicking the <ContentValidatorIcon /> icon in the sidebar.

## Searching for content

<Note>
  Queriers will only be able to see metadata for the content that they have access to. Otherwise, document and query titles will be displayed as `[Content not accessible]` and `[Query not accessible]`.
</Note>

The Content Validator is useful for seeing how a topic, view, or field is being used across your workspace. For example, check where a field appears before removing it, identify the dashboards that depend on a view before swapping in a new table, or find all queries tied to a topic. This way, you know exactly what will be affected before making changes.

Use the search box and the **Choose find type** dropdown to search the content in your instance, clicking **Find** to execute the search. You can search for content by:

* View name
* Field name. **Note**: This must be a fully qualified field name, meaning the name of the view containing the field must be included. For example, `shipped_items.item_price`
* Topic name
* Document name
* Query name

### Including personal content and queries without issues

By default, search results will only include content in your organization's [**Hub**](/content/navigate) that has a broken query. To include:

* **Content in users' [**My documents** folders](/content/navigate)**, use the **Include personal documents** toggle
* **Queries without issues**, click the ✓ (green checkmark) near the top-right corner of the page

### Branches and search result impact

The content included in search results is also impacted by whether you're performing the search while in a branch.

#### Searching while not in a branch

If you're not in a branch while searching, the results will include:

* Published content
* Drafts that are not attached to a branch

In this example, the results include the published `Bug deep-dive` document and a draft not attached to a branch, `Draft not in branch`.

<img alt="Content Validator search results while not in a branch in the model IDE. Includes published content and drafts not currently attached to a branch." />

#### Searching in a branch

If you're in a branch while searching, results will include:

* Published content
* Drafts attached to the branch

In this example, the results include the published `Bug deep-dive` document and a draft (`Draft in branch`) attached to the `field-cleanup` branch.

**See an out of date draft?** Refer to the [Working with out of date drafts](#working-with-out-of-date-drafts) section for more information.

<img alt="Content Validator search results while in a branch in the model IDE. Includes published content and the drafts attached to the branch." />

## Suppressing validator issues

You can suppress specific validator issues by adding a `!suppress(issue_slug)` comment to your model YAML files. This is useful when you want to acknowledge a validation warning or error but choose not to fix it immediately.

When the validator identifies an issue, you can suppress it using the IDE's autofixer, which will automatically add the appropriate comment to your model file. The autofixer knows which issue slug to use and where to place the comment, so you don't need to manually look up or remember issue identifiers.

### Suppression scopes

Suppressions work at different levels depending on where you add the comment:

* **Property level**: Adding a `!suppress(issue_slug)` comment to any property suppresses the issue for the entire object
* **View level**: Adding the comment to a view suppresses the issue for all fields within that view
* **Model level**: Adding the comment to the top-level model suppresses the issue for the entire model

The IDE autofixer will place the comment on the most relevant property when possible for better readability. However, because comments can attach to different properties based on YAML structure, a comment added to any property will suppress the issue for the whole object.

## Updating documents

<Warning>
  Omni strongly recommends using a branch when making changes to content through the Content Validator. Otherwise, changes may be applied directly to the published version of documents and can only be manually reverted on a document-by-document basis.
</Warning>

You can make single document changes or bulk updates right from the Content Validator:

1. In the Content Validator, click the **Replace** button next to one of the content results.

2. In the **Replace** dialog, select the type of object you want to replace:

3. Enter the name of the object to replace and the name it should be replaced with. If replacing a field, make sure you include the name of the view, like `<view_name>.<field_name>`:

   <img alt="" />

   <Check>
     If you're in a branch and applying changes to a published document, Omni will create a new draft with the changes and attach it to the branch. The changes will be published when the branch is merged. If performing a global find and replace, Omni will create a draft for each affected document.
   </Check>

4. To apply the changes to all content, toggle the **Replace for all content** setting.

5. Click **Replace**.

At this point, you can navigate to individual documents to verify the changes are working as expected. If you're working in a branch, merging the branch will publish the changes in any drafts attached to the branch.

### Working with out of date drafts

When a draft is marked **out of date**, it means that a new version of the document has been published since the draft was created. If the outdated draft is published, it will overwrite the currently published version of the document.

We recommend taking the following steps to resolve this issue:

1. Identify the changes in the outdated draft.
2. In the Content Validator, discard the outdated draft by clicking the  (red trash can) next to the draft.
3. In your branch, complete content replacements as needed. Omni will create a new draft and attach it to the branch.
4. In the new draft, redo any changes you identified in step 1.
5. When finished with all your changes, merge the branch.

## Related

* [Migrating tables](/modeling/develop/table-migration) - Swap to new tables or perform soft-deletes from your model in bulk when your database changes


# Controlling data access using the modeling layer
Source: https://docs.omni.co/modeling/develop/data-access-control

Control how data is accessed through the modeling layer.

Using a combination of [user attributes](/administration/users/attributes) and modeling parameters, you can control how data is accessed in your Omni models. To gain access to data - such as a topic, table, field, or row - users must have a user attribute with the required value.

## Requirements

To follow the steps in this guide, you'll need permissions in Omni that allow you to:

* Edit models
* Create and/or edit [user attributes](/administration/users/attributes)

<Check>
  Best practice when controlling data access with `access_grants` and `access_filters` is to ensure the [user attributes](/administration/users/attributes) do not have default values set.
</Check>

## Granting topic and field access with access grants

To apply an access grant, the first step is to create an [`access_grant`](/modeling/models/access-grants) in the model file. You'll need to specify a `user_attribute` to use and the `allowed_values` that are necessary to gain access under the grant.

For example, the `nw_region` access grant will grant access to users with a `region` user attribute that has a value of `washington`, `idaho`, `oregon`, `wyoming`, or `alaska`:

```yaml theme={null}
access_grants:
  nw_region:    
    user_attribute: region    
    allowed_values: [washington, idaho, oregon, wyoming, alaska]
  finance:
    user_attribute: omni_user_groups
    allowed_values: [Finance]
  marketing:    
    user_attribute: omni_user_groups    
    allowed_values: [Marketing]
```

[Default access grants can also be applied to a model](#default-access-grants-for-topics), ensuring all new topics have access grants applied unless specifically excluded.

### Omni system attributes in access grants

[Omni system attributes](/administration/users/attributes) can be used in access grants. In the following example, the `omni_is_org_admin` attribute is used to control the topics that are accessible only to Admin users.

```yaml title="Apply omni_admin grant to all topics in model" highlight={5} theme={null}
access_grants:
  omni_admin:
    user_attribute: omni_is_org_admin  
    allowed_values: [ "true" ]
    default_topic_required_access_grants: [ omni_admin ]
```

### Topic access grants

After an access grant is created in the model file, you can use [`required_access_grants`](/modeling/topics/parameters/required-access-grants) in topic files to apply specific access grants to individual topics:

```yaml title="Topic file" highlight={3} theme={null}
joins:
  distribution_centers: {}
required_access_grants: [ marketing, finance ]
```

**Note**: The values specified in `required_access_grants` must match an existing `access_grant` in the model file.

### Composite topic access grants

You can also use [`required_access_grants`](/modeling/composite-topics/parameters/required-access-grants) in a `.composite_topic` file to restrict access to the composite topic. Member topics' grants still apply. The composite's grants can only restrict access further. They can't grant access to member data a user can't otherwise see.

```yaml title="Composite topic file" highlight={2} theme={null}
topics: [ order_items, products ]
required_access_grants: [ finance ]
```

### Default access grants for topics

Using [`default_topic_required_access_grants`](/modeling/models/default-topic-required-access-grants) in the model file allows you to set a default required access grant for all topics contained in the model, including composite topics, unless others are applied. In the following example, `finance` will be the default access grant for the topics in the model:

```yaml title="Model file" highlight={1} theme={null}
default_topic_required_access_grants: [finance]
access_grants:
  nw_region:
    user_attribute: region
    allowed_values: [washington, idaho, oregon, wyoming, alaska]
  finance:
    user_attribute: omni_user_groups
    allowed_values: [Finance]
  marketing:
    user_attribute: omni_user_groups
    allowed_values: [Marketing]
```

In this topic, the default `finance` access grant will be used because a `required_access_grants` isn't defined:

```yaml title="products topic" theme={null}
joins:
  distribution_centers: {}
```

<Note>
  Topics created from [CSV/Excel uploads](/analyze-explore/data-input-csvs#modeling-and-promoting-data-input-tables) are an exception to this behavior. They automatically receive empty `required_access_grants` at creation time to ensure they remain accessible to all users, including embed users.
</Note>

#### Overriding default topic access grants

You can override a [default topic access grant](#default-access-grants-for-topics) if needed:

* **To allow all users to see a topic**, add a blank `required_access_grants` parameter:

  ```yaml title="Topic visible to all users" highlight={8} theme={null}
  label: Transactional
  joins:
    inventory_items:    
      products:      
        distribution_centers: {}  
    users: {}

  required_access_grants: [ ]
  ```

* **To override the default and use a different access grant**, add a `required_access_grants` parameter and include the access grant you want to use:

  ```yaml title="Topic requires the marketing access grant" highlight={2} theme={null}
  joins: {}
  required_access_grants: [ marketing ]
  ```

### Table (view) access grants

To apply an access grant to a table ([database view](/modeling/views)), use the [`required_access_grants`](/modeling/views/parameters/required-access-grants) parameter in a view file:

```yaml title="View requires finance access grant" highlight={4} theme={null}
required_access_grants: [ finance ]

dimensions:
  margin:
    sql: ${order_items.sale_price} - ${products.cost}
```

### Field access grants

If you need to restrict access to specific fields instead of an entire view, you can apply access grants to individual [dimensions](/modeling/dimensions/parameters/required-access-grants) and [measures](/modeling/measures/parameters/required-access-grants) with the `required_access_grants` parameter:

```yaml title="View file" highlight={6,12} theme={null}
dimensions:
  margin:
    sql: ${order_items.sale_price} - ${products.cost}
    format: CURRENCY
    description: margin = sale price - cost
    required_access_grants: [ finance ]
     
measures:
  sensitive_measure:
    sql: ${orders.sale_price} * ${fancy_formula}
    aggregate_type: sum
    required_access_grants: [ finance ]
```

### Conditional access grants

You can also conditionally allow access when specifying `required_access_grants` by using pipes (`|`) and ampersands (`&`) to create `OR` and `AND` conditions, respectively.

```yaml theme={null}
# Grant access if either condition is met:
required_access_grants: [ finance|marketing ]

# Grant access if conditions for (`marketing` OR `finance`) AND `nw_region` are met
required_access_grants: [ marketing|finance&nw_region ]
```

Conditional syntax can be used anywhere the `required_access_grants` parameter is supported.

### AccessBoostable access grants

By default, access grant checks will restrict query access even if [AccessBoost](/share#boosting-permissions-with-accessboost) is enabled on a dashboard. For content built on topics or views that use access grants, you'll need to add an `access_boostable: true` property to the grant to enable permission boosting via AccessBoost:

```yaml title="Model file" highlight={5} theme={null}
access_grants:
  omni_admin:
    user_attribute: is_marketing_member
    allowed_values: [ "true" ]
    access_boostable: true
```

## Granting row-level access with access filters

Row-level permissions are specified at the topic level with the [`access_filters`](/modeling/topics/parameters/access-filters) parameter or at the model level with the [`default_topic_access_filters`](/modeling/models/default-topic-access-filters) parameter.

Like access grants, access filters use [user attributes](/administration/users/attributes) to determine if a user should have access to the data in a given row. You can also [selectively permit access for users](#permit-access-for-specific-users) if needed.

### Fields in a topic

Use the `access_filter` parameter in a topic file to specify a list of fields in the topic where access should be limited.

In this example, the `order_items` topic will be filtered so that each brand can only see their own transactions and the associated metadata for each transaction.

```yaml title="order_items topic" highlight={7-9} theme={null}
joins:
  orders:
    user: {}
  inventory_items:
    products: {}

access_filters:
  - field: products.brand                    # field to use in the filter, specifies the product's brand    
    user_attribute: customer                 # user attribute to match to    
    values_for_unfiltered: [is_admin]        # users with the is_admin attribute bypass this filter
```

Under the hood, any query would require a join to `orders` > `inventory_items` > `products` and use a filter like the following, which limits access to rows with a `brand` value that matches the user attribute:

```sql theme={null}
WHERE products.brand = <the_value_in_user_attribute_customer>
```

### Default access filters for topics

Using `default_topic_access_filters` in the model file allows you to set default access filters for all topics contained in the model, unless others are applied. In the following example, an access filter for the `products.brand` field is defined:

```yaml title="Model file" theme={null}
default_topic_access_filters:
  - field: products.brand
    user_attribute: customer
```

In this topic, the default access filter will be used because an `access_filters` parameter isn't defined:

```yaml title="order_items topic" theme={null}
joins:
  orders:  
    user: {}  
  inventory_items:  
    products: {}
```

**Note**: If a default access filter can't be mapped to a given topic, an error like the following will display in the model IDE:

```shell theme={null}
No such access filter field "brand" (resolved to "main__users.brand") specified in default_topic_access_filters
```

Apply the following to the topic to avoid this:

```yaml theme={null}
access_filters: []
```

#### Default access filters with unscoped table references

`default_topic_access_filters` can also be applied with an unscoped table reference, allowing for a common field across multiple tables to be applied universally with ease.

The following example demonstrates how to apply an `access_filter` for the `user_id` field to both the `order_items` and the `users` topics, allowing for a more generalized approach:

```yaml title="Model file" theme={null}
default_topic_access_filters:
  - field: user_id  
    user_attribute: user_id  
    values_for_unfiltered: [is_admin]
```

In the `order_items` topic, which includes a `user_id` field:

```yaml title="order_items topic" theme={null}
joins:
  orders:  
    users: {} 
 inventory_items:  
   products: {}
```

In the `users` topic, which includes a `user_id` field:

```yaml title="users topic" theme={null}
joins:
  orders:  
    users: {}
```

### Permit access for specific users

There may be situations where you want to generally restrict data for a field, but still allow specific users like Admins to access all data for the field. To achieve this, you can set a special value for the user's user attribute and then specify it in the access filter with the `values_for_unfiltered` parameter:

```yaml highlight={4} theme={null}
access_filters:
  - field: products.brand  
    user_attribute: customer  
    values_for_unfiltered: [is_admin]
```

In this example, the access filter won't be applied to users who have a `customer` user attribute with a value of `is_admin`. **Note**: Users who don't have a defined value for the user attribute - in this case, `customer = null` will receive an error. Omni expects a value for any assigned access filter.


# Developing in Omni: Advanced modeling concepts
Source: https://docs.omni.co/modeling/develop/guides/advanced-concepts

Advanced modeling topics for admins and developers, including row-level security, access grants, templated filters, and dbt integration.

While Omni aims to empower business users to contribute to the centralized data model, there are several features that are intentionally made unavailable in the UI. This section will cover topics that an Admin or Developer is explicitly responsible for maintaining in the data model as well as other helpful integrations to complement the broader data stack.

<Steps>
  <Step title="Row, column & topic security">
    <iframe title="Row, column & topic security" />

    In this tutorial, you'll explore how to implement robust security measures in Omni, including row, column, and topic-level security. Key features covered include:

    * **Row-level security**: Apply access filters based on user attributes, enabling tailored data visibility. Admins can bypass these filters for comprehensive access.
    * **User attributes**: Create and manage attributes that define user access levels, enhancing security and customization.
    * **Column-level security**: Use required access grants to control visibility of specific fields or topics based on user eligibility.
    * **Scalable configuration**: Set security parameters across the entire model efficiently, avoiding repetitive setups for individual datasets.

    These features collectively ensure a secure and manageable data environment while promoting user-specific access to relevant information.
  </Step>

  <Step title="Caching policies and aggregate awareness">
    <iframe title="Caching policies & aggregate awareness" />

    In this tutorial, you'll learn how to optimize performance in Omni through effective caching policies and aggregate awareness. Key features include:

    * **Caching policies**: Define granular caching strategies at the shared, workbook, or topic level to control data refresh rates, enhancing performance and user experience. Set maximum cache ages to balance data freshness and cache hit rates, with the flexibility to refresh data on-demand.

    * **Aggregate awareness**: Streamline query performance by routing traffic to pre-aggregated tables, reducing the need for expensive real-time calculations. This feature intelligently directs queries to the most efficient data sources, improving overall system efficiency. For more information on setting up aggregate awareness see our [guide in the community](https://community.omni.co/t/i-have-tables-in-my-dwh-that-have-different-levels-of-aggregation-how-can-i-use-aggregate-awareness-to-query-dynamically/123)

    By leveraging these tools, you can significantly enhance your data processing capabilities, ensuring users access both detailed and summarized information quickly and efficiently.
  </Step>

  <Step title="Row-level security, SDK, & user attributes">
    <iframe title="Embed row-level Security, SDK, & user attributes" />

    In this tutorial, you'll discover how to leverage Omni for robust embedded analytics, emphasizing key features such as:

    * **Row-level security**: Learn how to implement dynamic security measures that ensure users only access data relevant to them. This is facilitated through programmatically injected filters that maintain privacy across shared dashboards.

    * **Customizable dashboards**: Explore how to create interactive dashboards embedded within your application, complete with drill-down capabilities, data export options, and customizable visualizations to enhance user engagement.

    * **Self-service analytics**: Understand how to empower users with the ability to build their own reports and dashboards using an embedded workbook experience, while applying topic and column-level security for tailored data access.

    * **Secure user sessions**: Dive into the technical aspects of secure session management using a TypeScript SDK, including unique session URLs and encrypted data transmission for enhanced security.

    By harnessing these features, you can provide a powerful and secure analytics experience that scales efficiently for diverse user needs.
  </Step>

  <Step title="dbt integration">
    <iframe title="dbt integration" />

    In this tutorial, we explore the powerful integration between Omni and dbt, focusing on three key pillars:

    1. **Seamless data sync**: Discover how Omni automatically absorbs new columns, tables, and updates from dbt, including view descriptions, ensuring users have the most current information without redundant effort.

    2. **Push changes to dbt**: Learn how to easily push new models and queries from Omni back to dbt. This feature streamlines the process of codifying your analytics logic directly into your warehouse setup, enhancing collaboration with existing dbt models.

    3. **Development environment access**: Understand how to point Omni to different dbt environments—like production and development—to preview changes before they go live. This functionality helps prevent downtime and breaking changes by allowing you to test and validate modifications in a safe environment.

    Join us to see how this integration enhances your analytics workflow, ensures data accuracy, and supports a robust development lifecycle!
  </Step>

  <Step title="Branch mode">
    <iframe title="Branch mode" />

    In this tutorial, we delve into Omni's branching feature within the modeling layer, which enhances collaborative development and workflow management.

    1. **Branch creation and management**: Learn how to create, rename, and manage branches within the shared model, ensuring changes are made in a contained environment before merging back to production.

    2. **Enhanced workflow with git integration**: Discover how Omni's Git integration enforces a structured workflow where users must work in branches and submit pull requests, promoting best practices in development and reducing the risk of direct commits to the main branch.

    3. **Collective changes across workbooks**: Explore how to gather changes from multiple workbooks into a shared branch, making it easy to manage and merge isolated modifications into the main model seamlessly.

    Join us to see how these features streamline collaboration, safeguard production environments, and foster efficient development cycles within your analytics workflows!
  </Step>
</Steps>


# Developing in Omni: Model IDE
Source: https://docs.omni.co/modeling/develop/guides/model-ide

Navigate the Omni Model IDE to edit auto-generated schema files, define views and fields, and manage your data model structure.

Omni works on your behalf to understand how to navigate your database. This allows for both accelerated initial deployments and long term scalability as the underlying schema changes.

You will notice that several files are automatically generated when you connect your database and initialize a data model. This section will walk through the different types of files in the model and orient you on how to use them.

<Steps>
  <Step title="Model IDE basics">
    <iframe title="Model IDE basics" />

    Start with learning about the key features of Omni's modeling IDE, which offers powerful tools for managing data models at scale.

    **In this video, you'll learn about:**

    * **Files in the IDE**, such as [models](/modeling/models), [relationships](/modeling/relationships), [topics](/modeling/topics), and [views](/modeling/views)
    * **Development tools** such as [branching](/content/develop/branch-mode) and [version control](/modeling/develop/history)
    * [**The content validator**](/modeling/develop/content-validator), which identifies and fixes errors across dashboards and workbooks
    * [**The dbt IDE**](/integrations/dbt/models), which provides a read-only view of dbt projects

    <Tip>
      If you have connection access permissions, you can navigate directly to connection settings from any model IDE page by clicking **Model** in the top navigation and selecting **Go to connection**. This opens the connection settings page in a new tab.
    </Tip>
  </Step>

  <Step title="Model files">
    <iframe title="Model files" />

    Explore the powerful customization options within Omni's [model file](/modeling/models) to curate experiences for your end users. Model files are used to define configuration for the analytical environment (topics, views, and so on) associated with a specific connection.

    **In this video, you'll learn to**:

    * Streamline navigation and reduce complexity by including and excluding schemas, views, and fields
    * Utilize [access grants](/modeling/develop/data-access-control) to restrict user access to topics and fields based on [user attributes](/administration/users/attributes)
    * Balance performance and data freshness with [caching policies](/analyze-explore/performance/caching)
  </Step>

  <Step title="Relationships file">
    <iframe title="Relationships file" />

    Enable your users to explore data without fear of disruption by utilizing the [relationship management file](/modeling/relationships). In this file, you can pre-define joins and automatically propagate them to workbook queries, thus removing the need for manual updates.

    **In this video, you'll learn to:**

    * Define relationships between tables using Omni's YAML syntax and [the workbook](/modeling/relationships/build)
    * Specify [relationship types](/modeling/relationships/parameters/relationship-type) and [direction](/modeling/relationships/parameters/reversible)
    * Create advanced custom joins with [SQL logic](/modeling/relationships/parameters/on-sql), [table aliases](/modeling/relationships/parameters/join-to-view-as), and [filters](/modeling/relationships/parameters/where-sql)
  </Step>

  <Step title="View files">
    <iframe title="View files" />

    Define what users see when accessing tables in the workbook by customizing the table's [view file](/modeling/views).

    **In this video, you'll learn to:**

    * Improve discovery with metadata such as [labels](/modeling/views/parameters/label), descriptions, [tags](/modeling/views/parameters/tags), and field groups
    * Refine the data by adding filters and including or excluding specific fields
    * Encourage deeper exploration with [drill fields](/modeling/views/parameters/default-drill-fields)
  </Step>

  <Step title="Topic files">
    <iframe title="Topic files" />

    Curate an entire dataset by using [topics](/modeling/topics), which allow you to organize and structure data around a specific area of interest or analysis.

    **In this video, you'll learn to:**

    * Refine the dataset by specifying which [tables](/modeling/topics) and fields to include
    * Define pre-configured [filters](/modeling/topics/parameters/default-filters) to apply to workbook queries
    * Improve [Blobby AI's](/ai/security) understanding of the topic by providing [context](/modeling/topics/parameters/ai-context)
  </Step>
</Steps>


# Developing in Omni: Permissions & content organization
Source: https://docs.omni.co/modeling/develop/guides/permissions-content-org

Configure data and content permissions in Omni across connection, model, and folder levels to control who can see and edit what.

One of the most important responsibilities of an Omni admin is ensuring that the data Omni has access to and the content built off that data is restricted to those who should see it. This section will walk through the different layers of permissions both at the data and content level available to you in Omni.

## About this tutorial

This video tutorial covers into Omni's permission roles, explaining how connection-level and content-level permissions work together to control access to data and documents. You will learn about the five base roles for connection permissions, ranging from No Access to Connection Admin, and how these roles can be overlaid and customized for individual users or groups.

The tutorial also covers content permissions for documents and folders, including features like access boosts and the ability to elevate or restrict access levels. Ideal for administrators, this video provides valuable insights into securing and managing access within Omni.

<Steps>
  <Step title="Create your first workbook analysis">
    <iframe title="Developing in Omni: Best practices" />

    Part one of this tutorial explains the common permission settings in Omni, focusing on how content and connection permissions interact. It uses a matrix to illustrate the spectrum from a secure setup (no access to both content and connections) to a more open environment (manager-level access to content and admin-level access to connections).

    The video highlights typical default settings, like granting content viewers access to dashboards, while connection permissions can vary from viewer to restricted querier, depending on user needs. It also touches on how SAML and SCIM protocols simplify user management as well.
  </Step>

  <Step title="Content organization best practices">
    <iframe title="Content Organization best practices" />

    This tutorial explores the content organization tools in Omni, focusing on the use of folders and labels. Viewers will learn how to create folders to organize documents by department or project, and how labels provide a cross-sectional way to categorize content across folders for easier access to key reports and KPIs.

    The tutorial also covers advanced features like managing folder permissions, controlling access to shared spaces, and using labels for verified content. This video is a valuable resource for admins and users looking to streamline content management and improve collaboration within Omni.
  </Step>

  <Step title="Content organization overview">
    <iframe title="Content Organization Overview" />

    This tutorial provides an overview of Omni's content structure, highlighting the personal and shared spaces available to users. Viewers will learn how to organize and access their personal favorites, create and manage documents, and utilize labels for cross-sectional organization.

    The tutorial also covers sharing content with colleagues, managing permissions in shared spaces, and navigating sections like **My Activity** and **Trash**. Ideal for users looking to optimize content management, this video showcases best practices for structuring and curating information within Omni.
  </Step>
</Steps>


# Developing in Omni: Modeling in workbooks
Source: https://docs.omni.co/modeling/develop/guides/workbook-modeling

Get started building and contributing to your Omni data model from workbooks and the IDE, including field promotion and governance.

The centralized data model is one of Omni’s core principles and allows data teams to maintain governance over their business logic. However, what makes Omni unique is that it allows for business users to define their own logic and contribute to the centralized data model while still maintaining the single source of truth. In this section, we will cover getting started with the data model both using the UI and from within the IDE itself.

## Where workbook model changes are saved

For a side-by-side view of the three modeling layers, see [How the model layers interact](/modeling/develop/promotion#how-the-model-layers-interact).
Fields you create in a workbook (quick aggregates, custom SQL fields, and calculations) are saved to that **workbook’s model layer**. They are local to the workbook and not visible outside of the workbook until you explicitly promote them. You can edit the workbook model in the model IDE (**Model > Model Layers > Workbook**). Duplicating or exploring from an existing workbook will copy any workbook model changes into the new workbook.

<Steps>
  <Step title="Create a new model">
    <iframe title="Net New Model" />

    In this tutorial, we walk through setting up an initial data model in Omni after establishing a connection. Omni simplifies the process by automatically building the model, which can then be enhanced through a click-based UI or directly in the IDE. We'll start by creating a *topic*, a curated data set that makes it easier for users to navigate relevant information, reducing overwhelm while enabling deep self-service.

    Key features include the ability to enforce *row-level* and *column-level security*, hide fields, and automate the discovery of joins between tables based on column names. Omni intelligently identifies join opportunities, and users can further refine these joins through the UI by selecting join keys and types (e.g., left, inner, outer joins) or leveraging the *infer relationship* feature for unknown cardinality. These interactive UI components generate code behind the scenes, streamlining model creation and allowing even non-technical users to explore data without deep database knowledge. We'll also dive into the modeling layer in future sessions to explore direct code editing.
  </Step>

  <Step title="Create new fields">
    <iframe title="Creating New Fields (Quick aggregates, Add Field, Excel Promotion)" />

    In this tutorial, we explore three powerful ways to create new fields within Omni's workbook interface, designed to simplify data manipulation for users at all skill levels.

    1. **Quick Aggregates**: Instantly generate sums, averages, and other aggregations by right-clicking on a field, making complex calculations accessible without coding.

    2. **Custom SQL Fields**: Use the "Add Field" feature to write custom SQL definitions, such as concatenating user names, and leverage Omni's own field syntax for flexibility and consistency across the model. This allows for easy changes and propagations across the dataset.

    3. **In-Workbook Calculations**: Create Excel-like calculations directly in the workbook by combining columns. These calculations can be promoted for repeated use, making them accessible across multiple areas in Omni for non-technical users.

    We'll also explore the underlying code generated by these actions and cover advanced model curation techniques to ensure best practices when building out topics within Omni.
  </Step>
</Steps>


# Viewing and restoring model versions in the model IDE
Source: https://docs.omni.co/modeling/develop/history

Model history in the developer IDE allows users to see the changes made to the model and restore to an older version.

To access a model's history, click the <Icon icon="clock" /> icon in the IDE sidebar.

<img alt="" />

## Exploring and comparing older versions

The left-hand menu includes a chronological list of time-stamped changes. The detailed view to the right of the list of changes, compares the previous change to the currently selected version.

<img alt="" />

## Restoring an older model version

Restore a previously saved version of your model files by navigating to the change you want to restore to.

1. In the list of model changes, select the one you want to restore.
2. Click **Preview restore**.
3. Compare the changes in all affected files.
4. Click **Restore this version**.

## Viewing file history

File history provides a detailed view of all changes made to individual model files, including who made each change and when. This is distinct from the model version history, which shows changes across all files in your model.

To view the history for a model file, open the file in the IDE and click the <Icon icon="clock" /> icon near the top right corner of the page.

<Frame>
  <img alt="Annotated history for a view file in the Omni model IDE" />
</Frame>

Once opened, the file history view displays a chronological list of changes specific to that file.

<Note>
  History entries older than 6 months are included in the list of changes, but viewing the specifics of the change is not currently supported.
</Note>


# Model generation
Source: https://docs.omni.co/modeling/develop/model-generation

Models are automatically generated after a connection is added. Each model is divided into two layers:

* The **schema model** that stays in sync with raw database tables and views, and
* The **model extension**, where user-defined, virtualized data models live in Omni. Think fields, joins, and additional metadata such as formats, descriptions, and so on.

These layers make up the model you see in the model IDE in **Combined** mode.

## Schema Model

The schema model is intended to serve as a baseline version of the database schema, for simple point and click query, and some inferred key relationships. The schema model can be viewed by clicking the Parent model name at the bottom of the shared model page.

To refresh the schema, click **Model > Refresh schema** inside the given schema model (see [Schema Refreshes](/modeling/develop/schema-refreshes)) for more details:

<img alt="" />

When a model is generated or refreshed, Omni will use a combination of the schema metadata we get from your connected database and heuristics about the names of views and fields to auto-generate join relationships in the relationships model file and primary key designations in each view file.

**Note**: When deleting or ignoring schema fields, they will still be editable in SQL queries by users who have permissions to use SQL.

## Model extension

The model extension is the core user-curated data model in Omni. Fields, joins, and other metadata extend / supplement the schema model.

In addition to entirely new fields and relationships, schema fields can be extended with new metadata - formatting, labels, or deleted by "ignoring" them. Refer to the next section for more information.

**Note:** The model extension described here is the **shared model extension.** [Workbook models](/modeling/develop/guides/workbook-modeling) can have their own workbook model extensions.

## Browse Modes

The model IDE has two browse modes that control which layers of the model are visible. You can switch between them using the **browse mode** selector at the top of the model file tree.

### Combined mode (default)

By default, the IDE displays the model in **Combined** mode. In this mode, the layers of the model are combined to create a comprehensive view.

<img alt="" />

### Model mode

Model mode shows only the model extension, any fields, joins, and metadata you've explicitly defined. The auto-generated schema layer is hidden.

#### Interaction between browse modes

Changes made while in **Combined** mode will be included in the model extension - that is, visible when you toggle the mode to **Model**.

To delete a field or view from the schema model, delete it while in **Combined** mode. When you toggle into **Model** mode, the field or view will be marked as `ignored`.

Conversely, in **Model** mode, you can delete an "ignored" field or view to resurface it from the schema model.

## Branch Model Browse Modes

When working in a [branch](https://docs.omni.co/modeling/develop/model-management#branch-mode), the model IDE provides three browse modes that let you inspect different states of the model relative to your in-progress changes. These are accessible via the **browse mode** dropdown in the IDE.

### Staged

Only the changes you've added or modified in your branch.

### Merged

The shared model extension as it exists today, including your branch's pending changes.

### Combined

The full model as it will look after your branch is merged. This is the schema + model extension + your branch's pending changes, all layered together. It's the same view as using the model normally outside of a branch.

### Fully Resolved

Resolved combination of layers, with inherited content from extends


# Managing your models
Source: https://docs.omni.co/modeling/develop/model-management

Manage Omni models through the workbook layer or IDE, including promoting changes between workbook and shared model layers.

Managing your models in Omni can be done through the workbook layer or the development IDE. This is made possible by Omni's layered approach to maintaining your data and allowing users to promote those changes to the different layers, i.e. model layer and workbook layer.

## Using AI with your models

Omni AI is woven into the modeling experience in a few different ways: you can build and maintain your model with an in-IDE chat agent, curate your model so AI-generated queries are more accurate, and tune how the AI behaves on a per-model basis.

### Building models with the Modeling Agent

The [Modeling Agent](/ai/model-assistant) is a chat panel in the Model IDE that helps you build and maintain your semantic model. Use it to ask questions about your model, get suggestions for fields and relationships, and draft YAML edits — all without leaving the IDE.

### Optimizing models for AI

Providing context to Omni AI — such as field descriptions, possible values, and usage hints — improves the accuracy and relevance of AI-generated queries and suggestions. See [Optimize models for Omni AI](/modeling/develop/ai-optimization) to learn how to curate your models for better AI performance.

### Tuning AI behavior

The `ai_settings` model parameter lets you control how Omni's AI behaves within a specific model — including what data it can query, whether it validates its own analysis, and which model tier and thinking level it uses for different tasks. See the [`ai_settings` reference](/modeling/models/parameters/ai-settings) for more information.

## Branch Mode

More structured than [document drafts](/content/develop) but less complex than the [git integration](/integrations/git), Branch Mode allows you to test changes to models and content before making them visible to your teammates.

By creating a separate space to experiment with updates, you can develop confidently without disrupting production data. This approach supports scalable and reliable workflows, reducing the need for reactive fixes while improving traceability and accountability in the development process.

Refer to the [Using Branch Mode for collaboration guide](/content/develop/branch-mode) for more information.

## Local development with the Omni model editor CLI

<Note>
  The Omni model editor CLI is currently in beta and under active development.
</Note>

The [`@omni-co/model-local-editor`](https://www.npmjs.com/package/@omni-co/model-local-editor) CLI tool lets you edit Omni model YAML files locally in your preferred editor with real-time synchronization back to Omni. Changes you save locally are automatically pushed to your Omni branch, giving you full IDE support for syntax highlighting, autocomplete, and version control.

To install the CLI, run the following:

```bash theme={null}
npm install -g @omni-co/model-local-editor
```

The tool requires an [API key](/api/authentication) and works with [branches](/content/develop/branch-mode) for isolated development. Refer to the [Local development guide](/guides/modeling/local-development) for full setup and usage instructions.

## Shared model promotion

Shared model promotion pushes changes made in the workbook layer into the model layer so the changes are reusable and available in all workbooks. Refer to the [Promoting workbook changes to the shared model](/modeling/develop/promotion) to learn more.

## Incorporating database changes with schema refreshes

Keeping your BI tool in sync with your database when schema changes occur can be a challenge. As such, there may be times when you need to manually refresh the schema model - or make Omni aware of the changes - that your Omni model is built on. Refer to the [Schema refresh guide](/modeling/develop/schema-refreshes) for more information.

## Validating models against content

The **Content Validator,** accessible by clicking the <ContentValidatorIcon /> in the IDE's sidebar, helps you keep your content accurate and up-to-date as your data model evolves. If a field is renamed, a table is swapped, or a topic is removed, the validator makes it easy to spot where things broke and quickly fix them - either one by one or in bulk.

<img alt="" />

Additionally, the Content Validator is a powerful discovery tool: you can search for all the content that references a specific field, view, or topic to see how widely it’s used before making changes. This way, you can make updates with confidence and ensure nothing slips through the cracks. Refer to the [Content Validator guide](/modeling/develop/content-validator) for more information.

## Shared extension models

[Shared extension models](/modeling/develop/shared-extensions) let you create specialized versions of a parent model that inherit its core logic — joins, topics, metrics — while allowing their own customizations. Using shared extensions, you could create:

* **Multi-tenant environments** - Dynamically route users to tenant-specific extensions based on [user attribute mapping](/administration/users/attributes), giving each customer a tailored data experience from a single parent model.
* **Departmental models** - Use an extension as the static base model for a workbook, giving teams like Finance or Marketing their own curated view of shared data without affecting other groups.

Extensions can also support [isolated branches](/modeling/develop/shared-extensions/extension-branches) for independent development workflows, letting teams develop and test changes without affecting the parent model.

## Export to dbt

Omni aims to make model management easy both in Omni and below the BI layer. To this end, Omni can export a view file's dbt SQL. This will allow users to build fact tables, or virtualized fields into their dbt models.

**Note**: This will require some rework of your Omni model, as new dbt views will be populated into the model upon schema refresh. This means field references would need to be remapped to maintain continuity.


# Promoting workbook changes to the shared model
Source: https://docs.omni.co/modeling/develop/promotion

Shared model promotion pushes changes made in the workbook layer into the model layer so the changes are reusable and available in all workbooks.

<Note>
  **Connection Admin** or **Modeler** permissions are required to promote workbook changes to the shared model.
</Note>

Depending on your workflow preferences, you can promote changes to the shared model from a workbook or by editing the model directly in the model IDE.

## How the model layers interact

Omni's model has three layers that stack on top of each other:

| Layer                 | Scope                                                  | How changes get there                                                                                                 |
| --------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Shared model**      | Global. Governs every workbook on the connection.      | Promoted from a workbook, merged from a branch, or saved directly in the model IDE.                                   |
| **Branch** (optional) | Isolated development space on top of the shared model. | Added from a workbook, or saved from the model IDE with **Save to branch**.                                           |
| **Workbook model**    | Local to a single workbook.                            | Created automatically as you build in the workbook UI (quick aggregates, custom SQL fields, calculations, and so on). |

Changes you make in a workbook land in the **workbook model** first. They're local to that workbook and invisible to other workbooks until you promote them up a layer.

## Reviewing and promoting workbook changes

<Tip>
  Working in Branch Mode? See [Promoting workbook changes in a branch](#promoting-workbook-changes-in-a-branch) below.
</Tip>

Promoting workbook changes directly to the shared model requires that you are in the **published** version of the workbook. Then, to view and promote changes, you can:

* Click **Model > View & promote changes**
* Click the <Icon icon="layer-group" /> icon in the workbook's sidebar

Either option will open the workbook model changes drawer, where you can review changes before promoting them. This drawer shows all changes made in the current workbook layer, including added, modified, and removed model items:

<img alt="Workbook model changes Summary tab" />

### Reviewing changes

To quickly understand what changed without opening the IDE, click the **Code** tab to view the "diff" of the underlying model YAML:

<img alt="Workbook model changes Code tab" />

The **Code** tab includes:

* The change type (added, modified, or removed) with color-coded styling
* A YAML snippet of the model item showing relevant properties
* For modified items, a side-by-side comparison of the shared model version and workbook version

### Selecting and promoting changes

In the **Summary** tab of the workbook model changes drawer, review the changes. When ready, click **Promote to shared** to promote all of them to the shared model.

When ready, click the **Promote to shared** button to promote the changes.

<Note>
  If you only want to promote some of the changes, use the checkboxes to uncheck the ones to leave out. Partial promotion requires a branch, so the button becomes **Add to branch** and Omni creates a new branch for the selected changes when you confirm. Merge that branch to apply them to the shared model.
</Note>

## Removing unused objects from the workbook

If you've created fields, views, topics, or relationships in your workbook that are no longer referenced by any queries, you can use the **Remove unused** button to clean up the workbook layer. This will not affect the shared model.

While in edit mode, the **Remove unused** button appears in the workbook model changes drawer alongside the **Revert** and **Promote** buttons.

When you click **Remove unused**:

<Steps>
  <Step>
    A confirmation dialog appears showing what will be removed
  </Step>

  <Step>
    After confirmation, Omni identifies all model objects (fields, views, topics, and relationships) that aren't referenced by any query in the workbook
  </Step>

  <Step>
    These unreferenced objects are removed from the workbook layer
  </Step>
</Steps>

Dependencies between fields are preserved. For example, if field A is used by a query and depends on field B, and B depends on C, then B and C are both preserved — even though no query references them directly. Views with non-field metadata changes (such as label or description updates) are also preserved even if their fields are unused.

<Note>
  The **Remove unused** button is disabled when incremental promotion changes are selected, similar to the **Revert** button behavior.
</Note>

## Promoting workbook changes in a branch

If you're working in Branch Mode, you can stage workbook model changes to your branch instead of promoting them directly to the shared model. This lets you validate changes alongside content updates and merge everything to production at once.

<Note>
  **Connection Admin**, **Modeler**, or **Querier** permissions are required to add changes to a branch. **Connection Admin** or **Modeler** permissions are required to merge.
</Note>

To add workbook model changes to a branch:

1. Open the workbook model changes drawer by clicking **Model > View & promote changes** or the <Icon icon="layer-group" /> icon in the workbook's sidebar.
2. Review the changes and use the checkboxes to select what to include.
3. Click **Add to branch** to stage the selected changes.

<Warning>
  **Add to branch** is a required step. Workbook model fields that haven't been added to the branch stay in the workbook model and won't be in the shared model after the branch is merged. This is distinct from document edits, which are saved to the branch draft as you work.
</Warning>

Once staged, the changes are part of the branch model and appear in the model IDE when viewing the branch. When you're ready, [merge the branch](/content/develop/branch-mode#publishing-and-merging-branches) to apply your model and content changes to production at the same time.

## Directly editing the model

Edits made directly in the model IDE will be promoted to the shared model as soon as the file is saved.

For more structured development processes, explore the [Branch Mode](/content/develop/branch-mode) and [git integration](/integrations/git) options.


# Incorporating database changes with schema refreshes
Source: https://docs.omni.co/modeling/develop/schema-refreshes

Trigger manual or scheduled schema refreshes to keep your Omni model in sync when database tables, columns, or schemas change.

When your database schema changes — new tables, renamed columns, removed schemas — your Omni model can fall out of sync. Run a schema refresh to tell Omni about those changes.

## Requirements

To trigger schema refreshes, you'll need **Modeler** or **Connection Admin** permissions:

* **Modelers** can perform schema refreshes on connections with exactly **one** shared model
* **Connection Admins** can refresh schemas on any connection they are an admin of, whether the connection has one or multiple models

<Note>
  Refreshes to multi-model connections affect every shared model on the connection, so they can only be triggered by Connection Admins.
</Note>

## Types of schema refreshes

There are two types of schema refreshes: hard and soft.

| Type             | What's refreshed?                           | What's reflected in Omni?                                                                                                                                        |
| ---------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hard refresh** | Entire model (all schemas and tables)       | **All** changes: <br /><br /><CheckIcon label="New objects" /><br /><CheckIcon label="Updated objects" /><br /><CheckIcon label="Removed objects" />             |
| **Soft refresh** | Entire model or specific schemas and tables | **Additive** changes only: <br /><br /><CheckIcon label="New objects" /><br /><CheckIcon label="Updated objects" /><br /><XCircleIcon label="Removed objects" /> |

## Triggering schema refreshes

Schema refreshes can be triggered manually or automated on a schedule. Kicking off a refresh starts a background job that can take several minutes depending on the size of the database.

### Manually

Schema refreshes can be triggered on an as-needed basis from the model IDE, from a connection's settings page, or with the API.

<AccordionGroup>
  <Accordion title="In the IDE" icon="code">
    <Steps>
      <Step title="Open the model IDE">
        Navigate to the model IDE.
      </Step>

      <Step title="Open the refresh schema dialog">
        Click **Model > Refresh schema**.
      </Step>

      <Step title="Choose hard or soft refresh">
        * **Hard refresh** of the entire model: leave the schema and table fields blank.
        * **Soft refresh** of specific schemas and tables: add the objects you want to refresh, individually or with wildcard syntax (e.g., `sales_*`).
      </Step>

      <Step title="Trigger the refresh">
        Click **Refresh schema**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="In the connection's settings" icon="database">
    <Steps>
      <Step title="Open the connection settings">
        Navigate to **Settings > Connections** and open the connection.
      </Step>

      <Step title="Open the refresh schema dialog">
        Click **Refresh now**.
      </Step>

      <Step title="Choose hard or soft refresh">
        * **Hard refresh** of the entire model: leave the schema and table fields blank.
        * **Soft refresh** of specific schemas and tables: add the objects you want to refresh, individually or with wildcard syntax (e.g., `sales_*`).
      </Step>

      <Step title="Trigger the refresh">
        Click **Refresh schema**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="With the API" icon="cloud">
    Use the [Refresh schema endpoint](/api/models/refresh-schema) to manually trigger a refresh.
  </Accordion>
</AccordionGroup>

### On a schedule

<Note>
  Scheduled refreshes don't currently support selectively refreshing schemas and tables.
</Note>

Use scheduled refreshes to automatically pull database changes into your Omni model. You can create refresh schedules in Omni on a connection's settings page or with the API.

<AccordionGroup>
  <Accordion title="In the connection's settings" icon="database">
    <Steps>
      <Step title="Open the connection settings">
        Navigate to **Settings > Connections** and open the connection.
      </Step>

      <Step title="Open the refresh schedule dialog">
        Click **Create schedule**.
      </Step>

      <Step title="Define the schedule">
        Enter a cron string to define the schedule.

        <Tip>
          Omni uses Amazon Web Services (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information and examples.
        </Tip>

        If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every day at 6am" or "every Monday and Thursday at midnight."
      </Step>

      <Step title="Choose hard or soft refresh">
        **Optional**. By default, scheduled refreshes perform soft refreshes. Check the **Hard refresh** option to create a schedule that discards the existing schema model and rebuilds it from scratch.
      </Step>

      <Step title="Create the schedule">
        Click **Schedule**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="With the API" icon="cloud">
    Use the [Create schema refresh schedule endpoint](/api/schema-refresh-schedules/create-schema-refresh-schedule) to programmatically create a schedule, and the [Update schema refresh schedule](/api/schema-refresh-schedules/update-schema-refresh-schedule) to modify it.
  </Accordion>
</AccordionGroup>

## Requiring branches for schema refreshes

<Note>
  Branch-based schema refreshes can't be enabled if a connection has multiple models or if connection environments ([dynamic connections](/connect-data/dynamic-environments)) are currently in use.
</Note>

If you prefer to review schema changes before they impact the shared model, enable the connection's **Branch based schema refresh** setting. This will force schema refreshes to be performed in an [Omni branch](/content/develop/branch-mode) before they can be promoted to the shared model.

When this setting is enabled:

* **On-demand and scheduled refreshes will be disabled**
* **Schema refreshes can only be triggered from the IDE**. If you're not in an existing branch, selecting **Model > Refresh schema** will prompt you to create a branch first.
* **Only one shared model can exist on the connection.** This is enforced continuously, not just at the time you enable the setting. If you try to create a second model using the same connection, it will appear as unavailable in the model creation flow.

  This restriction exists because a connection's schema is a single shared resource. Branch-based schema refresh routes schema changes through one model's branch/pull request workflow, and that only resolves accurately when there is exactly one shared model on the connection.

  This restriction also applies if [**Require for system syncs**](/integrations/git/settings#require-for-system-syncs) is enabled, as this setting requires branch-based schema refreshes.

  <Tip>
    If you need two independently git-managed models backed by the same database, create a **second connection** pointing at the same database. Each connection gets its own schema and its own single-model branch-based schema refresh pipeline.
  </Tip>

## Resolving broken references

Changes made as a result of a schema refresh may result in broken references in Omni. Use the [Content Validator](/modeling/develop/content-validator) to identify and resolve any issues. If you need to update references after renaming tables in your database, use [table migration](/modeling/develop/table-migration).

## Common questions

<AccordionGroup>
  <Accordion title="Will a schema refresh overwrite manual changes to Omni view files?">
    No. Omni uses an additive method for modifying files. If you programmatically update a `view.yaml` with parameters like `ai_context` or `synonyms`, those parameters persist through a refresh.
  </Accordion>
</AccordionGroup>


# Using isolated branches with extension models
Source: https://docs.omni.co/modeling/develop/shared-extensions/extension-branches

Extension models can have their own independent branches that are isolated from the parent shared model.

Extension models can be configured to support isolated branches. When enabled, these branches are scoped to the extension model and remain separate from the parent shared model's branches. This enables you to:

* Develop and test changes specific to an extension without affecting the parent model
* Maintain separate development workflows for different use cases or teams
* Create branches from existing branches within the extension

## Limitations

Extension branches have some restrictions:

* **Schema refresh** - Branch schema refresh is not supported in shared extension model branches
* **View migrations** - View migrations cannot be used with shared extension model branches

## Requirements

To follow the steps in this guide, you'll need:

* A [shared extension model](/modeling/develop/shared-extensions)
* **Connection Admin**, **Modeler**, or **Querier** permissions on the shared extension model

## Enabling isolated branches

Enable the **Use isolated branches** extension setting to enable branches scoped to the extension model. Refer to the [Extension settings guide](/modeling/develop/shared-extensions/settings#use-isolated-branches) for step-by-step instructions.

## Creating branches on extension models

Once isolated branches are enabled, you can create branches on the extension model:

<Steps>
  <Step>
    Navigate to the extension model in the model IDE or open a workbook using the extension.
  </Step>

  <Step>
    Click **Model > New branch** or **Model > Branch > New branch**.
  </Step>

  <Step>
    Enter a name for the branch.
  </Step>

  <Step>
    Use the **Branch from** dropdown to select the starting point:

    * **Shared model (latest)** - Creates a branch from the latest version of the extension model
    * **Existing branch** - Creates a branch from another branch on the extension. Use the dropdown that appears to select the branch.
  </Step>

  <Step>
    Click **Create**.
  </Step>
</Steps>

The branch is now scoped to the extension model. Navigating to the parent shared model will not show this branch.

## Next steps

* Learn more about [Branch Mode](/content/develop/branch-mode) for working with branches in Omni
* Learn how the [`extends`](/modeling/models/extends) parameter works
* Explore [model management](/modeling/develop/model-management) for additional development workflows


# Shared extension models
Source: https://docs.omni.co/modeling/develop/shared-extensions/index

Create an inheritance model for multi-tenant environments with shared extension models.

Shared extension models let you create specialized versions of a parent model that inherit its core logic — joins, topics, metrics — while allowing their own customizations. For example, you could create:

* **Multi-tenant environments** - Dynamically route users to tenant-specific extensions based on [user attribute mapping](/administration/users/attributes), giving each customer a tailored data experience from a single parent model.
* **Departmental models** - Use an extension as the static base model for a workbook, giving teams like Finance or Marketing their own curated view of shared data without affecting other groups.

<iframe />

## When to use shared extensions

Shared extensions may be a good fit when:

* You manage a multi-tenant environment and need to give each customer a tailored data experience
* You have a core set of metrics and joins that should be consistent across all customers
* You want customers to build their own content without affecting other tenants
* You need to programmatically provision and route users to siloed data views at scale

Shared extensions **are not recommended** for:

* Environments where every customer requires a completely different schema or data source with no common logic
* Situations where changes made by one customer should flow back up and be visible to everyone else

## Requirements

To follow the steps in this guide, you'll need:

* **To have shared extension models enabled.** Contact Omni support to have this feature enabled.
* **Organization Admin** or **Connection Admin** permissions for the connection you want to work with in Omni.

## Creating shared extensions

<Steps>
  <Step title="Create the extension model">
    1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
    2. Select the model you want to work with.
    3. In the model IDE, click **Model > New Shared Extension**.
    4. Enter a name for the extension (e.g., `customer_3`).
    5. **Optional**: Select the **Allow exploration** checkbox. Enable this option if you want users to build their own content off the extension rather than viewing existing dashboards. See [Extension settings](/modeling/develop/shared-extensions/settings#allow-exploration) for more on how this setting behaves.
  </Step>

  <Step title="Define model visibility with user attributes">
    Next, you'll use [user attributes](/administration/users/attributes) to control which model extension a user sees when accessing or building content.

    1. Navigate to **Settings > Attributes**.
    2. Click **New Attribute**.
    3. Define a name and a reference (e.g., `customer_attribute`).
    4. Assign the appropriate attribute value to your [users](/administration/users).
  </Step>

  <Step title="Map user attributes in the model">
    To route users to the correct extension, you'll add a mapping to the parent model using the [`dynamic_shared_extensions`](/modeling/models/dynamic-shared-extensions) parameter.

    1. Click **Develop** in the [sidebar](/administration/settings/sidebar).

    2. Navigate to the parent model.

    3. In the model file, create the attribute mappings:

       <Tabs>
         <Tab title="Manual mapping">
           In this approach, you use the `mappings` parameter to create individual mappings to user attributes:

           ```yaml title="Manual mapping" theme={null}
           dynamic_shared_extensions:
             - user_attribute: customer_name         # User attribute reference
               mappings:
                 customer_1_model:                   # Extension model name
                   values_for_model: [customer_1]    # User attribute values            
                 customer_2_model:
                   values_for_model: [customer_2]
           ```
         </Tab>

         <Tab title="Programmatic mapping">
           If your user attributes follow a consistent naming convention, you can use the `map_pattern` parameter to create programmatic mappings:

           ```yaml title="Programmatic mapping" theme={null}
           dynamic_shared_extensions:
             - map_pattern: {{omni_attributes.customer_name}}_model
           ```
         </Tab>
       </Tabs>

       <Note>
         Only one of the `mappings` or `map_pattern` parameters can be used at a time.
       </Note>

    4. Save the changes.
  </Step>

  <Step title="Define default access for users">
    Setting default access levels ensures users only see the data intended for them.

    To start, set your parent connection base access to **No Access**. This prevents users from building off any extensions until you explicitly grant permission.

    1. Click **Settings > Connections**.
    2. In the list of connections, click the **parent connection** of the extension model.
    3. Click the **Permissions** tab.
    4. Set the connection's **Base Access** to **No Access**.
    5. Click **Save changes**.
    6. Choose how to approach permissions:

       <AccordionGroup>
         <Accordion title="Option 1: Shared content access (preferred)" description="Creates an experience that allows shared content">
           Even with **No Access** applied to the specific child extension, Omni will automatically route the user to the proper model when they view or build content. This allows them to see shared dashboards while being restricted to their own data scope.

           **To implement this approach**, grant users access to the **parent** model - for example, as Restricted Queriers - but set all child extensions to **No Access**.
         </Accordion>

         <Accordion title="Option 2: Siloed content access" description="Creates a completely isolated experience without shared content">
           When implemented, users can build off their assigned extension but will not see any shared instances or content from the parent level.

           **To implement this approach**, grant explicit access only to the specific child extension (e.g., `Customer 3`) and set the **parent** model to **No Access**.
         </Accordion>
       </AccordionGroup>
  </Step>

  <Step title="Testing access with user impersonation">
    To verify that your access controls are working as expected, we recommend [impersonating a test user](/administration/users/settings#impersonating-a-user).

    1. Navigate to your user list and select a test user.
    2. Change their user attribute to the extension you wish to test.
    3. Use the **Impersonate** feature to view the **Omni instance** through their eyes.
    4. Verify that the topics, tables, and metrics match the expected siloed or shared configuration.

    <Tip>
      Manage user permissions at scale by using the [Omni API](/api) or [user groups](/administration/users/groups).
    </Tip>
  </Step>
</Steps>

## Applying changes to extended models

Changes to a parent model propagate to all extensions automatically. Changes to a child extension stay within that extension only.

| I want to...                   | Do this                                                                                                                                                   |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Apply global changes           | Modify the parent **model**. Any updates—such as removing a join or adding a shared metric—will automatically propagate to **all** extensions once saved. |
| Apply changes to one extension | Edit the specific child **extension**. Actions like hiding a sensitive table or customizing a metric stay siloed within that extension.                   |

## Troubleshooting

If users are seeing incorrect data or `No Access` errors, check the following:

<AccordionGroup>
  <Accordion title="User sees parent model, not extension">
    * **Potential cause**: Incorrect attribute reference in model file
    * **Solution**: Verify the user attribute **reference** (ex: `my_user_attribute`) matches the exact string in **Settings > Attributes**.
  </Accordion>

  <Accordion title="User sees 'No Access' error">
    * **Potential cause**: Attribute value does not match any mapping
    * **Solution**: Check the user's attribute value against the `mappings` keys in the model YAML file
  </Accordion>

  <Accordion title="Changes not appearing in extension">
    * **Potential cause**: Parent model changes not saved
    * **Solution**: Ensure you have clicked **Save** in the parent model. Changes flow downstream automatically.
  </Accordion>

  <Accordion title="Extension data looks like parent data">
    * **Potential cause**: Extension-specific overrides are missing
    * **Solution**: Edit the extension model directly to apply overrides (like hiding tables) that shouldn't affect the parent
  </Accordion>
</AccordionGroup>

## Next steps

* [Extension settings](/modeling/develop/shared-extensions/settings) - Update settings, including **Allow exploration**, after an extension model is created
* [Extension branches](/modeling/develop/shared-extensions/extension-branches) - Enable isolated branches on extension models so teams can develop and test changes without affecting the parent model


# Managing extension model settings
Source: https://docs.omni.co/modeling/develop/shared-extensions/settings

Update the settings on a shared extension model, including Allow exploration and isolated branches.

After a [shared extension model](/modeling/develop/shared-extensions) is created, you can update its settings from the model IDE.

## Requirements

* A [shared extension model](/modeling/develop/shared-extensions)
* **Connection Admin** or **Modeler** permissions on the shared extension model

## Updating extension settings

<Steps>
  <Step>
    Click **Develop** in the [sidebar](/administration/settings/sidebar) and open the extension model.
  </Step>

  <Step>
    In the model IDE, click **Model > Extension settings**.
  </Step>

  <Step>
    Adjust the [available settings](#available-settings) as needed.
  </Step>

  <Step>
    Click **Update**.
  </Step>
</Steps>

## Available settings

### Allow exploration

Controls whether users can build new analyses off the extension model and query the model with AI.

* **Enabled** - The extension model appears in the list of available models when creating a new analysis. Users can also query the model with AI.
* **Disabled** - The extension model is hidden from the new analysis model selector, the options for creating a new analysis are disabled from within the extension's model IDE, and AI access to the model is disabled.

### Use isolated branches

Scopes branches to the extension model, keeping them separate from the parent shared model's branches. Refer to the [Extension branches guide](/modeling/develop/shared-extensions/extension-branches) for more information on branch workflows.


# Table migration
Source: https://docs.omni.co/modeling/develop/table-migration

Use table migration to update table references in Omni when table names change in your database, without breaking downstream content.

The table migration tool in the model IDE allows you to update table references within your Omni model when table names change on the database end, without breaking workbook queries, dashboards, or other model references that depend on the original table. This is ideal for situations where you are creating new versions of existing tables in your database.

## Requirements

To follow the steps in this guide, you'll need **Modeler** or **Connection Admin** permissions on the model you want to work with.

## Migrating tables

<Steps>
  <Step>
    In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
  </Step>

  <Step>
    If your organization has more than one model, click the model you want to work with. If you have only one model, Omni opens it automatically.
  </Step>

  <Step>
    In the model IDE, click **Model > Branch** to [create a new branch](/content/develop/branch-mode).
  </Step>

  <Step>
    In the model IDE, click **Model > Migrate tables**. The **Table migration** modal will display the tables you can migrate.

    <img alt="The Migrate tables view in the Omni model IDE, showing a list of tables that can be migrated." />
  </Step>

  <Step>
    Locate the table you want to work with and click the **Action** dropdown to display the options.

    * **Swap to a new table** - **Use when you have a replacement table ready to go.** Updates references to this table throughout the model. When selected, a second dropdown will display. Use this field to select the table Omni should use as the replacement:

      <img alt="The table migration modal showing the swap-to-new-table dropdown with available replacement tables." />

      Swapping to a new table adds a `renamed_from` parameter to the table's underlying view file, which helps prevent downstream references from breaking. In a view file, this will look like the following:

      ```yaml title="View file with renamed_from parameter" highlight={2} theme={null}
      table_name: blob_sales
      renamed_from: old_blob_sales
      ```
    * **Delete this view** - **Use when a table is no longer needed.** Soft-deletes the table by adding [`ignored: true`](/modeling/views/parameters/ignored) to the table's underlying view file. If needed, you can recover the table by reverting the change in the **Staged** panel of the model IDE before merging your branch.
  </Step>

  <Step>
    If needed, select actions for more tables in the modal.
  </Step>

  <Step>
    When finished, click **Migrate**. This will apply the changes you made in the **Table migration** modal to your Omni branch.
  </Step>

  <Step>
    Merge the Omni branch to promote the changes to the shared model. If the [git integration](/integrations/git) is enabled for the model, you may need to open a pull request first.
  </Step>
</Steps>

## After migrating

After merging your branch, use the [Content Validator](/modeling/develop/content-validator) to verify that no downstream references were broken by the migration.

<Tip>
  If your database schema has changed more broadly — such as new or removed tables and columns — use a [schema refresh](/modeling/develop/schema-refreshes) instead of or in addition to table migration.
</Tip>


# Dimensions
Source: https://docs.omni.co/modeling/dimensions/index

A dimension is an attribute that describes a row of data.

Dimensions are used as the primary segmentation and grouping when querying. They can be date/time, strings, booleans, or numbers. Omni also has helpers for working with [nested dimensions like JSON](#creating-fields-from-json).

By default, when a model is generated, Omni will use the schema model to create dimensions for every column in the database.

## Ordering fields

Fields in the Omni model do not currently allow free-form ordering but instead operate in the following framework:

| Object                           | Order                 | Re-arrangeable? |
| -------------------------------- | --------------------- | --------------- |
| View columns (schema dimensions) | Database column order | No              |
| Shared model dimensions          | Saved by default      | Yes, on save    |
| Workbook/branch model fields     | Saved by default      | Yes, on save    |
| Measures                         | Saved by default      | Yes, on save    |
| Filters                          | Saved by default      | Yes, on save    |

<Note>
  Interleaving between these groupings is not currently supported.
</Note>

## Naming dimensions

Dimension names must be unique within any given view (no same names). Names may use characters a-z (no capital letters), 0-9, or underscores, and start with a letter.

Additional [parameters](/modeling/dimensions/parameters/index) are nested under the dimension with one tab (two spaces) of indention, for example:

```yaml title="Field naming" highlight={2,6} theme={null}
dimensions:
  first_name:               # the name of the field/dimension
    label: Full Name
    sql: CONCAT(${first_name}, ' ' ${last_name})

  is_from_california:
    sql: ${state} = 'California'
```

## Permissing field values with user attributes

There may be situations where you need to control who sees the values for specific fields. To accomplish this, use [user attributes](/administration/users/attributes) in a dimension's [`sql`](/modeling/dimensions/parameters/sql) definition to mask or hide values as needed:

```yaml title="Hiding field values" theme={null}
name:
  sql: ${users.full_name}

name_hidden:
  sql: |+
    CASE
      WHEN {{omni_attributes.see_names}} = 'true'
      THEN ${users.name}
      ELSE 'No Access'
    END
```

```yaml title="Hashing field values" theme={null}
name:
  sql: ${users.full_name}

name_hashed:
  sql: |+
    CASE
      WHEN {{omni_attributes.see_names}} = 'true'
      THEN ${users.state}
      ELSE MD5(${users.name})
    END
```

## Filter-only fields

Filter-only fields are often used alongside [templated filters](/modeling/templated-filters) to create fields for more specific use cases that only operate as filters, often to dynamically filter fact tables or subqueries.

## Handling schema field adjustments

Raw schema field names may need to be adjusted to work correctly in Omni for analytics. This can happen due to type casing issues, timezone adjustments, or other complex reasons. You can account for this by creating an additional field, for example:

```yaml title="Creating a new adjusted field" theme={null}
string_that_should_be_number: {}

adjusted_field:
  sql: ${string_that_should_be_number}::bigint
```

If you want to keep the raw field name and adjust the field in place, modify the SQL on the base field. Note that the following example doesn't use `${}` syntax:

```yaml title="Adjusting field in place" theme={null}
string_that_should_be_number:
  sql: string_that_should_be_number::bigint

created_at:
  sql: DATETIME(created_at, 'America/Los_Angeles')
```

## Creating fields from JSON

<Note>
  This section only applies to modeled fields. Fields defined in raw SQL are not supported.
</Note>

Fields recognized as JSON - both true JSON and stringified JSON - can be parsed in Omni's UI. In the workbook's **Results** tab, right-click a row in the results table and then **Create fields from JSON**:

<img alt="JSON parsing" />

Omni will parse the JSON and create new fields in the workbook.

<Note>
  When parsing JSON, you may need to manually cast fields to the correct data type after they are created. For example, timestamp fields may be created as strings.
</Note>

## Level of Detail (LoD) Fields

Level of Detail (LoD) fields let you control the exact granularity at which an aggregation is computed, independent of how the rest of the query is grouped. Use the [`level_of_detail`](/modeling/dimensions/parameters/level-of-detail) parameter on a dimension to define it as an LoD field.


# ai_context - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/ai-context

Provides context to the Omni Agent for better understanding of field usage.

Free text that can provide context to the [Omni Agent](/ai/chat). Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

For example, context could include behavioral prompting.

## Syntax

```yaml theme={null}
<dimension_name>:
  ai_context: <context_text>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      Free text providing context to the Omni Agent about when and how to use this field.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Behavioral prompting" theme={null}
product_category:
  ai_context: |
    Use this field when asked to include categorical data about products.
```


# aliases - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/aliases

Create aliases for renamed dimensions to prevent existing Omni content from breaking when field names change in the data model.

Creates an alias for a dimension, allowing you to ensure Omni content that uses the field doesn't break when the field is renamed.

## Syntax

```yaml theme={null}
<field_name>:
  aliases: [OLD_FIELD_NAME]
```

## Properties

<ParamField type="object[]">
  The name of the dimension.

  <Expandable title="dimension_name properties">
    <ParamField type="array">
      An array of old field names that should map to the dimension.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

In this example, the `sale_date` field was renamed to `order_date`. Adding `aliases` to the field allows references to `sale_date` to continue working:

```yaml orders.view theme={null}
order_date:
  aliases: [sale_date]
```


# all_values - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/all-values

Provides the complete list of possible values to the Omni Agent for dimensions with a fixed set of values.

This helps the [Omni Agent](/ai/chat) understand the full range of options available for a field.

Use this parameter for dimensions with a limited, well-defined set of values such as status fields, categories, or types. Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<dimension_name>:
  all_values: [<value_1>, <value_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      A complete list of all possible values for the dimension. Best suited for dimensions with a fixed, enumerated set of values.

      <Note>
        When the dbt integration is enabled, `accepted_values` tests will be ingested as `all_values`.
      </Note>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Priority levels" theme={null}
priority:
  all_values: [low, medium, high, critical]
```

```yaml title="Boolean field" theme={null}
is_active:
  all_values: [true, false]
```


# bin_boundaries - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/bin-boundaries

Specifies bins or tiers for a given numeric field.

Bin text cannot be configured, but you can use a `CASE` statement to explicitly set text.

## Limitations

This parameter can only be used with numeric fields. Use [`groups`](/modeling/dimensions/parameters/groups) for string fields.

## Syntax

```yaml theme={null}
<dimension_name>:
  sql: ${<view_name>.<field_name>}
  bin_boundaries: [<boundary_1>, <boundary_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="array">
      An array of numeric values that define the boundaries for binning.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Bins of '< 21', '>= 21 and < 65', and '65 and above'" theme={null}
age_bin:
  sql: ${users.age}
  bin_boundaries: [21, 65]
  label: Age Bins
```


# colors - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/colors

Defines colors to map to specific dimension values.

This allows you to maintain consistent coloring for dimension values across visualizations, whether they're on the same dashboard or on different dashboards.

<Tip>
  You can also model colors for [measures](/modeling/measures/parameters/colors)!
</Tip>

## Syntax

```yaml theme={null}
<dimension_name>:
  colors:
    conditions:
      - condition:
          is: <value>
        color: <color>
    else: <fallback_color>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="object">
      Contains color configuration for the dimension.

      <Expandable title="colors properties">
        <ParamField type="array">
          A list of condition objects that map specific values to colors.

          <Expandable title="conditions properties">
            <ParamField type="object">
              A condition specified using [filter syntax](/modeling/filters). Currently, only the `is:` syntax is supported. The condition must be a child of the `condition` key.
            </ParamField>

            <ParamField type="string">
              The color to be used in visualizations when the condition is met. Can be specified using any legal [CSS method](https://www.w3schools.com/cssref/css_colors_legal.php).
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          Optional fallback color applied to values that don't meet any condition in the list.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Multiple color conditions" theme={null}
status:
  order_by_field: status_order
  colors:
    conditions:
      - condition:
          is: Complete
        color: green
      - condition:
          is: Processing
        color: rgb(0, 0, 255)
      - condition:
          is: Pending
        color: rgba(0, 0, 255, 0.3)
      - condition:
          is: Shipped
        color: hsl(120, 100%, 50%)
      - condition:
          is: Cancelled
        color: "#000000"
    else: red
```

```yaml title="Simple color mapping" theme={null}
priority:
  colors:
    conditions:
      - condition:
          is: High
        color: red
      - condition:
          is: Low
        color: green
    else: gray
```


# convert_tz - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/convert-tz

Controls whether a field should be converted to the query/user timezone.

When set to `false`, the field will default to the [connection (database) timezone](/connect-data/timezones) with no conversion.

This parameter can only be added to a dimension and will apply to all the parameterizations of the dimension. Date or week fields in the database are good candidates for this parameter, as converting the time segments isn't necessary.

<Note>
  Timezone conversion in a [`sql` parameter](/modeling/dimensions/parameters/sql) is strongly discouraged. This approach can create challenges on SQL generation for complex transformations, such as dimension fill vis-a-vis timezones.
</Note>

## Syntax

```yaml theme={null}
<dimension_name>:
  convert_tz: false
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="boolean">
      When set to `false`, timezone conversion will be disabled for the field, instead defaulting to the [database timezone](/connect-data/timezones) with no conversion. Defaults to `true`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Disable timezone conversion" theme={null}
created_date:
  sql: created_date
  convert_tz: false
```

```yaml title="Date field with timeframes" theme={null}
timestamp_created_pst:
  sql: DATETIME(${marketing_orders_new.timestamp_created}, 'America/Los_Angeles')
  timeframes:
    - DATE
    - HOUR_OF_DAY
    - MONTH_NAME
  convert_tz: false
```


# custom_primary_key_sql_for_quick_aggs - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/custom-primary-key-sql-for-quick-aggs

Defines a custom primary key for aggregate measures where a primary key is applicable.

This is useful for ensuring that [symmetric aggregates](/analyze-explore/sql/symmetric-aggregates) are computed correctly, especially for [nested columns (`structs`)](/analyze-explore/sql/symmetric-aggregates#handling-fan-out-from-unnested-columns) which are common in Google BigQuery.

## Syntax

```yaml theme={null}
<dimension_name>:
  custom_primary_key_sql_for_quick_aggs: ${<field_reference>}
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      A field reference specifying the custom primary key to use for quick aggregate calculations.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Nested column with custom primary key" theme={null}
dimensions:
  order_id:
    primary_key: true
  order_items: {}
  order_item_price:
    parent_field: order_items
    nested_on_field: order_items
    custom_primary_key_sql_for_quick_aggs: ${order_item_id}
    sql: price

measures:
  total_price:
    sql: ${order_item_price}
    aggregate_type: sum_distinct_on
    custom_primary_key_sql: ${order_item_id}
```


# description - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/description

Provides metadata about the dimension, made available in the workbook UI.

## Syntax

```yaml theme={null}
<dimension_name>:
  description: <description_text>
```

## Properties

<ParamField type="object[]">
  The name of the dimension.

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      A text description of the dimension. Use unquoted text.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Simple description" theme={null}
full_name:
  description: Full name based on first_name, last_name in CRM
```

```yaml title="Calculated field description" theme={null}
margin:
  sql: ${order_items.sale_price} - ${products.cost}
  description: Profit margin calculated as sale price minus product cost
```


# display_order - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/display-order

Overrides the sort order for the field picker within a view.

By default, dimensions are sorted alphabetically. Defining a `display_order` will override this default.

For fields inside groups using [`group_label`](/modeling/dimensions/parameters/group-label), the group will be ranked with the `min` of all the fields in the group. For example, if there are 3 fields with `display_order` of `4`, `5` and `{empty}`, the group will have a `display_order` of 4).

## Syntax

```yaml theme={null}
<dimension_name>:
  display_order: <number>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="integer">
      A whole number that determines the field's position in the field picker. Lower numbers appear first.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Ordering fields" theme={null}
first_name:
  display_order: 1

last_name:
  display_order: 2
```


# drill_fields - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/drill-fields

Enables hierarchical drilling inside a row of the result set.

Drill fields allow for hierarchical drilling inside a row of the result set. Dimensional drill retains the table structure, but adds the dimensions as filters and swaps the dimensions for the drill fields.

<img alt="Dimension drill example" />

Setting this parameter with an empty value (`drill_fields: []`) removes the drill from the dimension. You can also remove drilling in workbooks by hovering over a field in the field picker, clicking <Icon icon="ellipsis-vertical" />, and selecting **Edit**.

## Syntax

```yaml theme={null}
<dimension_name>:
  drill_fields: [<field_1>, <field_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="array">
      An array of field names that will be displayed when drilling into this dimension. An empty value (`[]`) removes the drill from the dimension.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Geographic drill-down" theme={null}
country:
  drill_fields: [state]
```

```yaml title="Timeframe drill with metadata" theme={null}
created_at:
  timeframe_metadata:
    year:
      drill_fields: [state]
      group_label: Created At
```

```yaml title="Remove drill capability" theme={null}
category:
  drill_fields: []
```


# duration - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/duration

Calculates the time difference between two timestamp fields in various intervals.

Duration dimensions automatically generate multiple interval variations (such as days, weeks, months, years) to provide flexible time difference analysis.

Duration dimensions behave similarly to timeframe dimensions, automatically creating parameterized versions of the field for different time intervals.

<Tip>
  You can also create duration fields directly from the workbook UI by right-clicking on a timestamp field and selecting **Duration**. Refer to [Creating duration fields from the workbook](/analyze-explore/custom-fields#duration-fields) for more information.
</Tip>

## Syntax

```yaml theme={null}
<dimension_name>:
  duration:
    intervals: [<interval_1>, <interval_2>, ...]
    sql_start: <start_timestamp_field>
    sql_end: <end_timestamp_field>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="object">
      An object that defines the duration calculation.

      <Expandable title="duration properties">
        <ParamField type="string">
          The starting timestamp field for the duration calculation. Use Omni field reference syntax (e.g., `${view.field_name}`).
        </ParamField>

        <ParamField type="string">
          The ending timestamp field for the duration calculation. Use Omni field reference syntax (e.g., `${view.field_name}`).
        </ParamField>

        <ParamField type="string[]">
          An array of interval names to generate for this duration field. The following intervals are supported:

          | Interval   | Description            |
          | ---------- | ---------------------- |
          | `seconds`  | Difference in seconds  |
          | `minutes`  | Difference in minutes  |
          | `hours`    | Difference in hours    |
          | `days`     | Difference in days     |
          | `weeks`    | Difference in weeks    |
          | `months`   | Difference in months   |
          | `quarters` | Difference in quarters |
          | `years`    | Difference in years    |
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Referencing duration dimensions

Duration dimensions can be referenced in the model using parameterized syntax, similar to timeframes:

* `${order_fulfillment_time[days]}`
* `${order_fulfillment_time[hours]}`
* `${order_fulfillment_time[weeks]}`

**Note**: Unparameterized references will always return `null`. For example, a reference like `${order_fulfillment_time}` will be `null`.

## Examples

```yaml title="Order fulfillment duration" theme={null}
order_fulfillment_time:
  duration:
    sql_start: ${orders.created_at}
    sql_end: ${orders.shipped_at}
    intervals: [hours, days, weeks]
```

```yaml title="User account age" theme={null}
account_age:
  duration:
    sql_start: ${users.created_at}
    sql_end: ${users.last_login_at}
    intervals: [days, months, years]
```

```yaml title="Project duration with all intervals" theme={null}
project_length:
  duration:
    sql_start: ${projects.start_date}
    sql_end: ${projects.end_date}
    intervals: [days, weeks, months, quarters, years]
```

## Related parameters

* [`timeframes`](/modeling/dimensions/parameters/timeframes) - For time segmentation of timestamp fields
* [`sql`](/modeling/dimensions/parameters/sql) - For custom field calculations


# dynamic_top_n - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/dynamic-top-n

Generates dimensions that automatically filter to the top N or bottom N values based on a measure.

This parameter is useful for creating pre-defined rankings like "Top 10 States by Sales" or "Bottom 5 Products by Revenue" without requiring manual filters. This allows you to:

* Create dimensions that show only the most relevant values for analysis
* Improve query performance by limiting the number of returned values, or
* Build reports with ranking without maintaining manual lists

When used, Omni generates a query that:

1. Aggregates the specified measure
2. Sorts by that measure
3. Limits to the specified number of values
4. Returns the dimension values that meet the criteria

## Syntax

```yaml theme={null}
<dimension_name>:
  sql: <sql_expression>
  dynamic_top_n:
    n: <number>
    by: <measure_reference>
    desc: <true|false>
    else: <string|null>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      The SQL expression that defines the dimension field.
    </ParamField>

    <ParamField type="object">
      Configuration for dynamic top N or bottom N filtering.

      <Expandable title="dynamic_top_n properties">
        <ParamField type="number">
          The number of values to return (e.g., `10` for top 10).
        </ParamField>

        <ParamField type="string">
          A reference to the measure used for sorting and ranking. Use the format `view_name.measure_name`.
        </ParamField>

        <ParamField type="boolean">
          Sort order for the ranking:

          * `true` (default): Returns the top N values (highest to lowest)
          * `false`: Returns the bottom N values (lowest to highest)
        </ParamField>

        <ParamField type="string | null">
          Controls how values outside the top N or bottom N are handled:

          * String value (e.g., `"Other"`, `"Remaining"`) - Groups all non-top-N values under the specified label
          * `null` - Excludes non-top-N values entirely, showing only the top N values without an aggregated group

          By default, non-top-N values are grouped as `Other`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Query-time parameterization

You can override the default `n` value at query time without modifying the model definition. This allows you to dynamically adjust the number of returned values for analysis.

Use the syntax `field_name[number]` where `number` overrides the model's default `n` value. For example, if you have a dimension named `top_5_states` with `n: 5` in the model, you can use `top_5_states[2]` in your query to limit results to the top 2 states instead.

When you override the `n` value:

* The dimension returns the specified number of top or bottom values based on the query-time parameter
* The `Other` bucket (if configured with the [`else` parameter](#param-else) automatically adjusts to include all remaining values
* If no parameterization is provided, the dimension uses the model-defined default `n` value

Consider the following example:

```yaml title="Model definition" theme={null}
dimensions:
  top_5_states:
    sql: ${users.state}
    dynamic_top_n:
      n: 5
      by: orders.count
```

And in the query, to override the defined `n` value:

* `top_5_states` returns 6 rows: the top 5 states + `Other`
* `top_5_states[2]` returns 3 rows: the top 2 states + `Other`
* `top_5_states[10]` returns 11 rows: the top 10 states + `Other`

## Examples

```yaml title="Top 10 states by order count" theme={null}
dimensions:
  top_10_states_by_orders:
    sql: ${users.state}
    dynamic_top_n:
      n: 10
      by: orders.count
```

```yaml title="Bottom 3 countries by order count" theme={null}
dimensions:
  bottom_3_countries_by_orders:
    sql: ${users.country}
    dynamic_top_n:
      n: 3
      by: orders.count
      desc: false
```

```yaml title="Top 20 products by revenue" theme={null}
dimensions:
  top_products_by_revenue:
    sql: ${products.name}
    dynamic_top_n:
      n: 20
      by: order_items.total_revenue
```

```yaml title="Top 5 sales reps by deal value" theme={null}
dimensions:
  top_sales_reps:
    sql: ${sales_reps.name}
    label: Top 5 Sales Reps
    dynamic_top_n:
      n: 5
      by: deals.total_value
      desc: true
```

```yaml title="Top 10 customers with custom label for remaining values" theme={null}
dimensions:
  top_10_customers:
    sql: ${customers.name}
    dynamic_top_n:
      n: 10
      by: orders.total_sales
      else: "All Other Customers"
```

```yaml title="Top 5 categories without grouping remaining values" theme={null}
dimensions:
  top_5_categories_only:
    sql: ${products.category}
    dynamic_top_n:
      n: 5
      by: order_items.total_revenue
      else: null
```


# extends - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/extends

Inherits configuration from a dimension defined in another view.

This parameter inherits configuration from a dimension defined in another view. Use it to centralize reusable field definitions — such as colors, formatting, or labels — in a template view, then apply them to dimensions in any view that needs them.

When a dimension extends another, attributes are inherited from the source. Attributes defined on the extending dimension override the inherited values.

<Tip>
  Pair this parameter with a [template view](/modeling/views/parameters/template) to keep reusable field configurations in a single, centralized location.
</Tip>

## Syntax

```yaml theme={null}
<dimension_name>:
  extends: [ <view_name>.<dimension_name> ]
```

## Properties

<ParamField type="object">
  The name of the dimension inheriting configuration. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="array">
      A list of one or more fields this field extends, in the format `<view_name>.<dimension_name>`.

      When multiple fields are specified, earlier fields in the array take precedence. This allows inheriting properties from base/template fields while overriding specific values.
    </ParamField>
  </Expandable>
</ParamField>

## Example

The following example defines a reusable `status` dimension in a template view, then applies it to dimensions in other views.

First, create the color configuration. In this example, we're using a template view to centralize our definitions:

```yaml title="color_templates.view" theme={null}
template: true

dimensions:
  status:
    colors:
      conditions:
        - condition:
            is: Complete
          color: rgba(0, 255, 0, 0.3)
        - condition:
            is: Cancelled
          color: rgba(255, 0, 0, 0.3)
```

Then, extend the template dimension in any view that has a `status` dimension:

```yaml title="orders.view" theme={null}
dimensions:
  status:
    extends: [ color_templates.status ]
    sql: status
```

The `status` dimension in `orders` inherits the `colors` configuration from `color_templates.status`, while keeping its own `sql` definition. Updating the template view propagates the change to all dimensions that extend it.


# faceting - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/faceting

Controls how a dimension's filter suggestions are affected by other active filters.

When faceting is enabled, if you select values in one filter, the suggestions shown in other filters automatically update to reflect only the values that exist with your current selections. The `faceting` property lets you customize this behavior per dimension.

You can configure dimensions to have suggestions that are:

* **Independent** of all other filters - Specified using `depends_on: []`
* **Dependent** only on specific fields - Specified using `depends_on: [<fields>]`
* **Filtered** by all fields except specific ones - Specified using `exclude: [<fields>]`

This is particularly useful for improving user experience in scenarios where the default faceting behavior is too restrictive or where certain dimensions should remain independent regardless of other selections.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Limitations

* This parameter can't be used with [`suggest_from_field`](/modeling/dimensions/parameters/suggest-from-field) or [`suggest_from_topic`](/modeling/dimensions/parameters/suggest-from-topic) on the same dimension
* Cross-view references are only allowed in topic-scoped views
* Field references in `depends_on` or `exclude` must resolve to existing dimensions or filter-only fields (not measures)
* Self-references (a dimension depending on or excluding itself) will generate a warning
* `depends_on` and `exclude` can't be used on the same dimension

## Syntax

```yaml theme={null}
<dimension_name>:
  faceting:
    depends_on: [<field_reference>, ...]
```

```yaml theme={null}
<dimension_name>:
  faceting:
    exclude: [<field_reference>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="object">
      Configuration object that controls suggestion filtering behavior.

      <Expandable title="faceting properties">
        <ParamField type="array of strings">
          List of field references that should filter this dimension's suggestions. All other filters are ignored.

          * Use an empty array `[]` to make suggestions completely independent of all filters
          * Field references can point to dimensions or filter-only fields (not measures) to make suggestions dependent on specific fields
          * In topic-scoped views, can reference fields from other views in the topic (e.g., `orders.region`)
          * Cannot be used with `exclude`
        </ParamField>

        <ParamField type="array of strings">
          List of field references that should NOT filter this dimension's suggestions. All other filters are applied.

          * Field references can point to dimensions or filter-only fields (not measures)
          * In topic-scoped views, can reference fields from other views in the topic
          * Cannot be an empty array (has no effect)
          * Cannot be used with `depends_on`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Independent suggestions

Make `gender` suggestions available regardless of other filter selections:

```yaml title="Independent suggestions" theme={null}
views:
  users:
    dimensions:
      gender:
        sql: ${users.gender}
        faceting:
          depends_on: []
```

### Include-list faceting

`city` suggestions should only be filtered by `country` and `state` selections, ignoring all other active filters:

```yaml title="Suggestions dependent on specific fields" theme={null}
views:
  users:
    dimensions:
      city:
        sql: ${users.city}
        faceting:
          depends_on:
            - country
            - state

      country:
        sql: ${users.country}

      state:
        sql: ${users.state}
```

### Exclude-list faceting

`first_name` suggestions should be filtered by all fields except `state`:

```yaml title="Exclude specific fields" theme={null}
views:
  users:
    dimensions:
      first_name:
        sql: ${users.first_name}
        faceting:
          exclude:
            - state
```

### Cross-view faceting in topics

In a topic-scoped view, reference fields from other views in the topic. This example makes `city` suggestions depend on the `region` from the `orders` view:

```yaml title="Cross-view suggestions" theme={null}
topics:
  sales:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on:
                - orders.region

      orders:
        dimensions:
          region:
            sql: ${orders.region}
```

### Per-topic customization

Different topics can configure different faceting behavior for the same base view:

```yaml theme={null}
# Base view definition
views:
  users:
    dimensions:
      city:
        sql: ${TABLE}.city

# Topic 1: city depends on country
topics:
  sales:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on:
                - country

# Topic 2: city has independent suggestions
topics:
  marketing:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on: []
```

## Related parameters

* [`suggest_from_field`](/modeling/dimensions/parameters/suggest-from-field) - Alternative way to control suggestion behavior by pulling from a different field
* [`suggest_from_topic`](/modeling/dimensions/parameters/suggest-from-topic) - Pull suggestions from a field in a different topic
* [`suggestion_list`](/modeling/dimensions/parameters/suggestion-list) - Provide a static list of suggestions


# filter_single_select_only - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/filter-single-select-only

Restricts a dimension to only allow single-value style filters.

## Limitations

This parameter is only compatible with string fields and filters.

## Syntax

```yaml theme={null}
<dimension_name>:
  filter_single_select_only: true
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="boolean">
      When set to `true`, restricts the field to single-value selection in filters. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Single select country filter" theme={null}
country:
  filter_single_select_only: true
```


# format - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/format

Sets default formatting for number and date dimensions—named formats, Excel-style strings, conditional formats, model constants, and Markdown table cells.

The `format` parameter sets the default display format for a 's values. s can use one of Omni's [named formats](/modeling/models/format-values#named-formats), an [Excel-style string](/modeling/models/format-values#excel-style-strings), a [Mustache template](/modeling/models/format-values#mustache-templates), or a [conditional format](/modeling/models/format-values#conditional-formats) that selects a format dynamically.

Formats can also be set on a per-query basis from visualization configuration, using the same format types.

See [Formatting values](/modeling/models/format-values) for more information on format types and examples.

<Note>
  Formats are applied **after** the SQL runs, so they do not impact grouping. To handle grouping with truncation, use `ROUND()` or `FLOOR()`.
</Note>

## Syntax

`format` accepts either a string or a conditional object:

<Tabs>
  <Tab title="String">
    ```yaml theme={null}
    <dimension_or_measure_name>:
      format: <format_string>
    ```
  </Tab>

  <Tab title="Conditional">
    ```yaml theme={null}
    <dimension_or_measure_name>:
      format:
        depends_on:
          field: <field_name>
          conditions:
            - condition:
                <filter_expression>
              value: <format_string>
        else: <fallback_format_string>
    ```
  </Tab>
</Tabs>

## Properties

Use the tabs to view the properties for string values and conditional objects.

<Tabs>
  <Tab title="String">
    <ParamField type="string">
      The format definition. This can be any valid [format type](/modeling/models/format-values#choosing-a-format-type):

      * A named format (e.g., `currency_2`, `percent_1`)
      * An Excel-style string (e.g., `'#,##0.00 "kg"'`)
      * A reference to a model-level [custom format](/modeling/models/custom-formats)

      <Tip>
        See [Formatting values](/modeling/models/format-values) for the full reference on all format types, including named formats, Excel-style strings, conditional formats, model constants, locale settings, and more.
      </Tip>
    </ParamField>
  </Tab>

  <Tab title="Conditional">
    <ParamField type="object">
      Defines the source value to evaluate conditions against. Set exactly one of `field`, `user_attribute`, or `filter`.

      These options resolve as follows:

      | Source           | Resolution timing         | Behavior                                                                                                         |
      | ---------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
      | `field`          | At display time (per row) | Evaluated against each row's value after query results are returned. Each row can resolve to a different format. |
      | `user_attribute` | At query preparation time | The user attribute value is evaluated once. The entire field uses the single resolved format.                    |
      | `filter`         | At query preparation time | The filter value is evaluated once. The entire field uses the single resolved format.                            |

      <Expandable title="depends_on properties">
        <ParamField type="string">
          The name of a field in the same view.
        </ParamField>

        <ParamField type="string">
          The reference of a [user attribute](/administration/users/attributes).
        </ParamField>

        <ParamField type="string">
          The name of a filter applied to the query.
        </ParamField>

        <ParamField type="object[]">
          An ordered list of condition entries. Each entry contains a `condition` using [Omni filter syntax](/modeling/filters) and a `value` specifying the format string to apply when the condition matches.

          <Expandable title="conditions properties">
            <ParamField type="object">
              An Omni filter expression. Supported condition types:

              | Condition                  | Description                    | Example                            |
              | -------------------------- | ------------------------------ | ---------------------------------- |
              | `is`                       | Exact match                    | `is: "USD"`                        |
              | `not`                      | Not equal                      | `not: "USD"`                       |
              | `greater_than`             | Greater than                   | `greater_than: "1000"`             |
              | `greater_than_or_equal_to` | Greater than or equal to       | `greater_than_or_equal_to: "1000"` |
              | `less_than`                | Less than                      | `less_than: "0"`                   |
              | `less_than_or_equal_to`    | Less than or equal to          | `less_than_or_equal_to: "100"`     |
              | `between`                  | Between two values (inclusive) | `between: [10, 100]`               |
              | `not_between`              | Outside a range                | `not_between: [10, 100]`           |
              | `starts_with`              | String starts with             | `starts_with: "US"`                |
              | `ends_with`                | String ends with               | `ends_with: "Corp"`                |
              | `contains`                 | String contains                | `contains: "special"`              |
              | `not_starts_with`          | String does not start with     | `not_starts_with: "US"`            |
              | `not_ends_with`            | String does not end with       | `not_ends_with: "Corp"`            |
              | `not_contains`             | String does not contain        | `not_contains: "special"`          |

              Additional conditions follow the same structure as [filters](/modeling/filters).
            </ParamField>

            <ParamField type="string">
              The format string to apply when the condition matches. Can be a named format or an Excel-style string.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Fallback format string used when no condition matches.
    </ParamField>
  </Tab>
</Tabs>

## Examples

```yaml title="Currency format" theme={null}
sale_price:
  format: currency_2
```

```yaml title="Big number format" theme={null}
revenue:
  format: big_2
```

```yaml title="Time format with timeframe metadata" theme={null}
created_at:
  timeframe_metadata:
    month:
      format: "%Y-%m-%d"
```

```yaml title="Custom Excel-style format with units" theme={null}
weight_kg:
  sql: '"weight"'
  format: '#,##0.00 "kg"'
```

```yaml title="Custom format reference" theme={null}
total_amount:
  sql: '"amount"'
  format: dynamic_currency
```

```yaml title="Conditional format" theme={null}
revenue:
  format:
    depends_on:
      field: orders.currency_code
      conditions:
        - condition:
            equals: USD
          value: usdcurrency_2
        - condition:
            equals: EUR
          value: eurcurrency_2
      else: currency_2
```


# group_label - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/group-label

Group related dimensions together under a label in the workbook field browser for cleaner organization and easier discovery.

## Limitations

**[Dimensions](/modeling/dimensions) and [measures](/modeling/measures) can't be grouped together.** Applying the same group label to a dimension and a measure will result in two groups displaying in the field browser, not one group with both fields.

## Syntax

```yaml theme={null}
<dimension_name>:
  group_label: <label_text>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores
</ParamField>

<ParamField type="string">
  Unquoted text specifying the group under which the field should appear in the field browser. Use the greater-than symbol (`>`) with whitespace on either side to create nested group hierarchies. Refer to the [Organize fields with nested groups guide](/guides/modeling/nested-field-groups) for more information and examples.
</ParamField>

## Date dimensions

When you apply a `group_label` to a date dimension, all timeframe variations (day, week, month, year, etc.) automatically nest under the parent field name within that group. For example:

```yaml title="Parent date field with a group label" theme={null}
created_at:
  group_label: Important Dates
```

In the field browser, this renders as:

```
▾ Important Dates
  ▾ Created At
      Created At Date
      Created At Week
      Created At Month
      Created At Year
      ...
```

This keeps related timeframes organized together while allowing you to categorize date fields into logical groups.

If you want to have specific timeframes as standalone dimensions (not under a group), specify `timeframes: []`.

## Examples

```yaml title="Grouping fields" theme={null}
name:
  group_label: Important Fields
```

```yaml title="Nesting under a timeframe group" theme={null}
created_at: {}

example_new_time:
  sql: "other_time"
  group_label: Created At
  timeframes: [minute]
```

```yaml title="Standalone date dimensions" theme={null}
created_at_date:
  sql: ${created_at[date]}
  label: Created at Date
  timeframes: []

created_at_month:
  sql: ${created_at[month]}
  label: Created at Month
  timeframes: []
```

In this example, note that the `group_label` is `"Created At"` not `"created_at"`, as the group label must match the label, not the field:

```yaml title="Custom timeframe in existing group" theme={null}
created_at_minute_5:
  sql: id+1
  group_label: Created At
```

### Nested groups

**Grouping types of customer data**

<Tabs>
  <Tab title="YAML">
    ```yaml theme={null}
    views:
      customers:
        dimensions:
          first_name:
            group_label: Contact Info > Name
          last_name:
            group_label: Contact Info > Name
          email:
            group_label: Contact Info
          phone:
            group_label: Contact Info
          street:
            group_label: Location > Address
          city:
            group_label: Location > Address
          state:
            group_label: Location > Address
          country:
            group_label: Location
    ```
  </Tab>

  <Tab title="Field browser result">
    ```markdown theme={null}
    ▾ Contact Info
      ▾ Name
          first_name
          last_name
        email
        phone
    ▾ Location
      ▾ Address
          street
          city
          state
        country
    ```
  </Tab>
</Tabs>

**Grouping date fields by category**

<Tabs>
  <Tab title="YAML">
    ```yaml theme={null}
    views:
      orders:
        dimensions:
          created_at:
            group_label: Key Dates
          shipped_at:
            group_label: Key Dates
          internal_timestamp:
            group_label: System > Timestamps
    ```
  </Tab>

  <Tab title="Field browser result">
    ```markdown theme={null}
    ▾ Key Dates
      ▾ Created At
          Created At Date
          Created At Week
          ...
      ▾ Shipped At
          Shipped At Date
          Shipped At Week
          ...
    ▾ System
      ▾ Timestamps
        ▾ Internal Timestamp
            Internal Timestamp Date
            ...
    ```
  </Tab>
</Tabs>


# groups - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/groups

Buckets results with CASE-like logic by filtering field values into labeled groups.

This parameter generates `CASE WHEN...` SQL statements in the background.

## Limitations

This parameter is only compatible with string fields. Use [`bin_boundaries`](/modeling/dimensions/parameters/bin-boundaries) for numeric fields.

## Syntax

```yaml theme={null}
<dimension_name>:
  sql: ${<view_name>.<field_name>}
  groups:
    - filter:
        is: [<value_1>, <value_2>, ...]
      name: <group_name>
  else: <fallback_group_name>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="array">
      An array of group definitions that map field values to group names.

      <Expandable title="groups properties">
        <ParamField type="object">
          A filter condition using the `is:` syntax to match values.
        </ParamField>

        <ParamField type="string">
          The name to assign to values matching the filter condition.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      The fallback group name for values that don't match any filter condition.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Status grouping" theme={null}
status_groups:
  sql: ${order_items.status}
  groups:
    - filter:
        is: [Cancelled, Returned]
      name: Test
    - filter:
        is: [Processing, Shipped]
      name: going
  else: Other
  label: Status Groups
```


# hidden - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/hidden

Hide a dimension from the workbook field browser while keeping it available for model references, joins, and calculations.

The field will still be referenceable in the model but hidden in the workbook UI.

## Syntax

```yaml theme={null}
<dimension_name>:
  hidden: true
```

## Properties

<ParamField type="object[]">
  The name of the dimension.

  <Expandable title="dimension_name properties">
    <ParamField type="boolean">
      If `true`, the dimension will be hidden.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Hide a field" theme={null}
id:
  hidden: true
```

```yaml title="Hidden compound primary key" theme={null}
compound_primary_key_field:
  sql: concat(${field_1},'-',${field_2})
  primary_key: true
  hidden: true
```


# ignore_from_extended - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/ignore-from-extended

Controls whether a field should be omitted during explicit extensions of a view.

When `true`, the field is excluded only during explicit extension. Unlike [`ignored`](/modeling/dimensions/parameters/ignored), this parameter affects only explicit extensions. The field still appears in combined modes (e.g., YAML or Git representations).

## Syntax

```yaml theme={null}
<dimension_name>:
  ignore_from_extended: true
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="boolean">
      When set to `true`, excludes the field during explicit view extensions. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Exclude from extended views" theme={null}
created_at:
  ignore_from_extended: true
```


# ignored - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/ignored

Removes a field from the UI and prevents references to it.

<Note>
  Ignored fields will still be accessible through SQL.
</Note>

This parameter can be used to 'remove' fields from the raw database schema.

## Syntax

```yaml theme={null}
<dimension_name>:
  ignored: true
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="boolean">
      When set to `true`, removes the field from the UI and prevents references. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Ignore Fivetran metadata field" theme={null}
_fivetran_deleted:
  sql: '"_FIVETRAN_DELETED"'
  ignored: true
```


# All dimension parameters
Source: https://docs.omni.co/modeling/dimensions/parameters/index

Dimensions are attributes that describe a row of data.

| Parameter                                                                                                            | Description                                                                                              |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [ai\_context](/modeling/dimensions/parameters/ai-context)                                                            | Provides context to Omni Agent for better understanding of field usage.                                  |
| [all\_values](/modeling/dimensions/parameters/all-values)                                                            | Provides the complete list of possible values to Omni Agent for dimensions with a fixed set of values.   |
| [aliases](/modeling/dimensions/parameters/aliases)                                                                   | Maps old field names to updated field names to preserve content.                                         |
| [bin\_boundaries](/modeling/dimensions/parameters/bin-boundaries)                                                    | Specifies bins or tiers for a given numeric field.                                                       |
| [colors](/modeling/dimensions/parameters/colors)                                                                     | Defines colors to map to specific dimension values.                                                      |
| [convert\_tz](/modeling/dimensions/parameters/convert-tz)                                                            | Controls whether a field should be converted to the query/user timezone.                                 |
| [custom\_primary\_key\_sql\_for\_quick\_aggs](/modeling/dimensions/parameters/custom-primary-key-sql-for-quick-aggs) | Defines a custom primary key for aggregate measures where a primary key is applicable.                   |
| [description](/modeling/dimensions/parameters/description)                                                           | Provides metadata about the dimension, made available in the workbook UI.                                |
| [display\_order](/modeling/dimensions/parameters/display-order)                                                      | Overrides the sort order for the field picker within a view.                                             |
| [drill\_fields](/modeling/dimensions/parameters/drill-fields)                                                        | Enables hierarchical drilling inside a row of the result set.                                            |
| [duration](/modeling/dimensions/parameters/duration)                                                                 | Calculates the time difference between two timestamp fields in various intervals.                        |
| [dynamic\_top\_n](/modeling/dimensions/parameters/dynamic-top-n)                                                     | Generates dimensions that automatically filter to the top N or bottom N values based on a measure.       |
| [extends](/modeling/dimensions/parameters/extends)                                                                   | Inherits configuration from a dimension defined in another view.                                         |
| [faceting](/modeling/dimensions/parameters/faceting)                                                                 | Controls filtering of suggestions by other filters when faceting is enabled                              |
| [filter\_single\_select\_only](/modeling/dimensions/parameters/filter-single-select-only)                            | Restricts a dimension to only allow single-value style filters.                                          |
| [format](/modeling/dimensions/parameters/format)                                                                     | Sets default or conditional formatting for number and date dimensions.                                   |
| [group\_label](/modeling/dimensions/parameters/group-label)                                                          | Nests a group of fields in the field picker for curated organization.                                    |
| [groups](/modeling/dimensions/parameters/groups)                                                                     | Buckets results with CASE-like logic by filtering field values into labeled groups.                      |
| [hidden](/modeling/dimensions/parameters/hidden)                                                                     | Removes the field from the UI while keeping it referenceable in the model.                               |
| [ignore\_from\_extended](/modeling/dimensions/parameters/ignore-from-extended)                                       | Controls whether a field should be omitted during explicit extensions of a view.                         |
| [ignored](/modeling/dimensions/parameters/ignored)                                                                   | Removes a field from the UI and prevents references to it.                                               |
| [label](/modeling/dimensions/parameters/label)                                                                       | Overrides the field name for all UI appearances.                                                         |
| [level\_of\_detail](/modeling/dimensions/parameters/level-of-detail)                                                 | Creates a Level of Detail field, which controls the granularity at which an aggregation is computed.     |
| [links](/modeling/dimensions/parameters/links)                                                                       | Adds external links to templated URLs in the drill menu.                                                 |
| [markdown](/modeling/dimensions/parameters/markdown)                                                                 | Mustache template rendered as Markdown in data table columns.                                            |
| [order\_by\_field](/modeling/dimensions/parameters/order-by-field)                                                   | Sets a field to be sorted by another field's values.                                                     |
| [parent\_field](/modeling/dimensions/parameters/parent-field)                                                        | Declares a dimension as a child of another dimension for nested field display.                           |
| [primary\_key](/modeling/dimensions/parameters/primary-key)                                                          | Sets the primary key on a view for preventing fan outs in calculations.                                  |
| [required\_access\_grants](/modeling/dimensions/parameters/required-access-grants)                                   | Defines a list of access grants for the dimension, which are used to control access.                     |
| [sample\_values](/modeling/dimensions/parameters/sample-values)                                                      | Provides sample values to Omni Agent to better understand field content and usage.                       |
| [skip\_parent\_label](/modeling/dimensions/parameters/skip-parent-label)                                             | Controls whether child dimension labels are prepended with the parent field label in grouped dimensions. |
| [sql](/modeling/dimensions/parameters/sql)                                                                           | The core declaration of the field definition using SQL.                                                  |
| [suggest\_from\_field](/modeling/dimensions/parameters/suggest-from-field)                                           | Specifies an alternative field to use for filter suggestions.                                            |
| [suggest\_from\_topic](/modeling/dimensions/parameters/suggest-from-topic)                                           | Explicitly sets the topic to use for filter suggestions.                                                 |
| [suggestion\_list](/modeling/dimensions/parameters/suggestion-list)                                                  | Explicitly sets the list of filter options, bypassing default behavior.                                  |
| [synonyms](/modeling/dimensions/parameters/synonyms)                                                                 | Alternative names that help the Omni Agent match user queries to the correct field.                      |
| [tags](/modeling/dimensions/parameters/tags)                                                                         | Metadata used for field search in workbooks, curating fields, and curating drill fields.                 |
| [timeframes](/modeling/dimensions/parameters/timeframes)                                                             | Sets the default time segments available for date/time fields in workbooks.                              |
| [view\_label](/modeling/dimensions/parameters/view-label)                                                            | Nests a field under a different view than its default parent view.                                       |
| [week\_start\_day](/modeling/dimensions/parameters/week-start-day)                                                   | Overrides the model- and topic-level week start day for this dimension.                                  |


# label - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/label

Overrides the field name for all UI appearances.

## Syntax

```yaml theme={null}
<dimension_name>:
  label: <display_label>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      Unquoted text that will be displayed in the UI instead of the field name.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Custom label" theme={null}
full_user_name:
  label: Full Name
```

```yaml title="Calculated field with label" theme={null}
full_name:
  sql: CONCAT(INITCAP(${users.first_name}), ' ', INITCAP(${users.last_name}))
  label: Full Name
```


# level_of_detail - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/level-of-detail

Creates a Level of Detail field, which controls the granularity at which an aggregation is computed.

Level of Detail (LoD) fields control the granularity at which an aggregation is computed. When used as a dimension, an LoD produces a categorical value — one row per level of detail — which lets you perform an additional layer of aggregation (e.g., average customer lifetime spend).

<Tip>
  You can also create LoD fields in the workbook! See [Creating level of detail fields](/analyze-explore/custom-fields/level-of-detail) for more information.
</Tip>

## How it works

The easiest way to understand an LoD dimension is to read it as SQL. For example, this `max_age_in_country` LoD finds the maximum user age within each country and attaches it to every user row:

<CodeGroup>
  ```yaml Model theme={null}
  max_age_in_country:
    sql: ${users.age}
    level_of_detail:
      aggregate_type: max
      fixed: [country]
  ```

  ```sql SQL equivalent theme={null}
  SELECT
    users.country AS "country",
    users.id AS "id",
    lod.max_age AS "max_age_in_country"
  FROM users
  INNER JOIN (
      SELECT country,
             MAX(age) AS max_age
        FROM users
    GROUP BY country
  ) lod ON users.country = lod.country
  ```
</CodeGroup>

The `fixed: [country]` clause corresponds to the `GROUP BY country` in the inner query — one row per country, the level of detail. The join then carries that country-level value back to each user row, which is why the LoD behaves like a categorical dimension: every user in the same country shares the same `max_age_in_country` value.

## Syntax

```yaml theme={null}
<dimension_name>:
  level_of_detail:
    aggregate_type: <aggregation>
    <grouping_strategy>: [<field_name>]
    custom_primary_key_sql: <field_reference>
    cancel_query_filters: <true_false>
    filters:
      <field>:
        <filter_operator>: <value>
        cancel_query_filter: <true_false>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="object">
      Configures the level of detail calculation for this dimension.

      <Expandable title="level_of_detail properties">
        <ParamField type="string">
          The type of aggregation to apply. Supports standard aggregations like `sum`, `average`, `count`, `min`, `max`, and distinct-on aggregations.

          **When the following aggregations are used**, the `custom_primary_key_sql` parameter is required:

          * `sum_distinct_on`
          * `average_distinct_on`
          * `median_distinct_on`
          * `percentile_distinct_on`
        </ParamField>

        <ParamField type="string">
          The grouping strategy and the field to use to apply it, specified as `grouping_strategy: [ field_name ]`. Refer to the [Examples](#examples) section to see an example with complete syntax.

          The grouping strategy must be one of the following:

          * `always_include` - Adds specified dimensions to the query's grouping, forcing a finer level of detail
          * `always_exclude` - Removes specified dimensions from the grouping, producing a coarser aggregation
          * `fixed` - Defines an absolute level of detail, replacing all query groupings
        </ParamField>

        <ParamField type="string">
          A field reference that defines the key to use for deduplication when using `*_distinct_on` aggregate types, specified using `${}` syntax. This allows you to aggregate over a different level than the view's primary key, such as summing amounts by order ID when your view is at the order items level.

          **This parameter is required** when the following `aggregate_type`s are used:

          * `sum_distinct_on`
          * `average_distinct_on`
          * `median_distinct_on`
          * `percentile_distinct_on`
        </ParamField>

        <ParamField type="boolean">
          When `true`, ignores any row filters applied in the outer query when computing the LoD metric. Defaults to `false`.

          To selectively ignore specific filters while keeping others, use the `filters` parameter with [`cancel_query_filter`](/modeling/filters/operators/cancel-query-filter) instead.
        </ParamField>

        <ParamField type="object">
          Applies filters to the level of detail calculation. See the [Filters documentation](/modeling/filters) for more information on Omni filter syntax.

          You can use [`cancel_query_filter: true`](/modeling/filters/operators/cancel-query-filter) within a filter to selectively ignore specific global filters for this level of detail only, while keeping other global filters active. This provides granular control compared to [`cancel_query_filters`](#param-cancel-query-filters), which ignores all global filters.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Customer lifetime spend" theme={null}
customer_lifetime_spend:
  sql: ${sale_price}
  label: Customer Lifetime Spend
  level_of_detail:
    aggregate_type: sum
    always_include: [user_id]
    cancel_query_filters: true
```

```yaml title="Fixed level of detail" theme={null}
category_total:
  sql: ${revenue}
  level_of_detail:
    aggregate_type: sum
    fixed: [category]
```

```yaml title="Exclude dimensions from grouping" theme={null}
overall_average:
  sql: ${score}
  level_of_detail:
    aggregate_type: average
    always_exclude: [region]
```

```yaml title="Sum distinct on with custom primary key" theme={null}
sum_by_order:
  sql: ${order_items.amount}
  level_of_detail:
    aggregate_type: sum_distinct_on
    custom_primary_key_sql: ${order_items.order_id}
    fixed: []
```

```yaml title="Selectively ignore a specific global filter" theme={null}
arr_balance_by_logo:
  sql: ${test_query_view.arr_cumulative}
  level_of_detail:
    aggregate_type: max
    fixed: [logo, date]
    filters:
      date:
        is: ""
        cancel_query_filter: true  # Ignores global date filter for this level of detail only
```

```yaml title="Replace a cancelled filter with a different value" theme={null}
compare_to_california:
  sql: ${revenue}
  level_of_detail:
    aggregate_type: sum
    fixed: [state]
    filters:
      state:
        is: California  # Replaces any global state filter with California
        cancel_query_filter: true
```

```yaml title="Compare with cancel_query_filters (all-or-nothing)" theme={null}
customer_lifetime_spend:
  sql: ${sale_price}
  level_of_detail:
    aggregate_type: sum
    always_include: [user_id]
    cancel_query_filters: true  # Ignores all global filters
```


# links - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/links

Add templated URL links to dimension drill menus, enabling cross-linking to external tools and dashboards from query results.

Fields referenced in links are implicitly added to the query, but not shown in the result data unless explicitly included.

**Note**: Avoid referencing a dimension with more than one value for a given value of the dimension on which the link is defined, as it can impact aggregations and seemingly create duplicate rows.

## Syntax

```yaml theme={null}
<dimension_name>:
  links:
    - url: <url_template>
      label: <link_label>
      icon_url: <optional_icon_url>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="object[]">
      An array of link objects, each containing `url`, `label`, and optionally `icon_url`.

      <Expandable title="links properties">
        <ParamField type="string">
          The URL template, with field references using `${}` syntax.
        </ParamField>

        <ParamField type="string">
          The display text for the link.
        </ParamField>

        <ParamField type="string">
          Optional URL to an image, which will display as an icon with the link.
        </ParamField>

        <ParamField type="string">
          Controls whether the link opens in the same tab or a new tab. Accepts `self` (same tab) or `blank` (new tab). Useful for tabbed dashboards where you want navigation to stay within the current tab.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Search engine links" theme={null}
country:
  links:
    - url: https://www.google.com/search?q=${users.country}
      label: Google
      icon_url: https://cdn4.iconfinder.com/data/icons/new-google-logo-2015/400/new-google-favicon-1024.png
    - url: https://www.bing.com/search?q=${users.country}
      label: Bing
```

<Tip>
  To inject the corresponding field into the filter URL structure, navigate to a filtered dashboard in your browser and then swap in the parameterized (dynamic) URL.
</Tip>

```yaml title="Dashboard crosslink with string filter" theme={null}
id:
  sql: '"ID"'
  format: ID
  links:
    - url: https://sandbox.omniapp.co/dashboards/KWsNP1WK?f--omni_dbt_ecomm__order_items.user_id={"values":["${omni_dbt_ecomm__users.id}"]}
      label: User Lookup Dashboard
      icon_url: https://avatars.githubusercontent.com/u/100505341?s=200&v=4
```

```yaml title="Dashboard crosslink with encoded URL" theme={null}
# For all types of filters, use the encoded URL
id:
  links:
    - url: https://sandbox.omniapp.co/dashboards/YX-irW2S/user+lookup?f--ecomm__users.id=%7B"values"%3A%5B"${ecomm__users.id}"%5D%7D
      label: User Lookup Dashboard
      icon_url: https://avatars.githubusercontent.com/u/100505341?s=200&v=4
```

```yaml title="Tabbed dashboard with target" theme={null}
# Link opens in same tab, useful for drill-down patterns
match_name:
  links:
    - url: /dashboards/match_deep_dive?filter=${match_id}
      label: Match deep dive
      target: self
    - url: https://www.example.com/${match_id}
      label: External
      target: blank
```


# markdown - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/markdown

Mustache template that renders dimension values as Markdown in data table columns.

Renders dimension values as Markdown in data table columns using Mustache.

The `markdown` parameter is not a [`format`](/modeling/dimensions/parameters/format) value. Use it when you want a \[table visualization]\[table-vis] to render a column as Markdown (for example bold text, links, or images) using a [Mustache](/visualize-present/mustache-reference) template filled with each row's values.

* **`format`** controls standard number, currency, and date display for the field.
* **`markdown`** renders a Mustache template as formatted text (bold, links, images) in **table** cells.

## Syntax

```yaml theme={null}
<dimension_name>:
  markdown: "<mustache_template>"
```

## Properties

<ParamField type="object">
  The name of the dimension.

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      A Mustache template string. The rendered output displays as Markdown in data table columns.
    </ParamField>
  </Expandable>
</ParamField>

## Behavior

* When you add a  with `markdown` to a query and use a table chart, Omni merges the template into the column's display settings so cells render as Markdown by default. In the table visualization's **Display** tab, you can customize the Markdown template and CSS, then use the **Promote** button to save those changes to the workbook model.
* Mustache can reference `.value`, `.raw`, and `.value_url_encoded` values for the current field and other fields in the row. Must be specified with `<view_name>.<field_name>` syntax, e.g., `{{view_name.field_name.property}}`.
* Referenced fields are included in the query automatically when needed.

For how `format` and `markdown` interact, see the [Formatting values guide](/modeling/models/format-values#formats-with-markdown).

<Note>
  Dashboard text tiles and standalone Markdown chart types are separate from field `markdown`, which applies to workbook data tables for modeled fields.
</Note>

## Examples

### Bold value and search link

```yaml title="customers.view" theme={null}
dimensions:
  state:
    sql: '"state"'
    markdown: "**{{customers.state.value}}** — [Search](https://example.com/search?q={{customers.state.value_url_encoded}})"
```

### Combine with another field

```yaml title="products.view" theme={null}
dimensions:
  name:
    sql: '"name"'
    markdown: "**{{products.name.value}}** bought by ({{users.email.value}})"
```


# mask_unless_access_grants - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/mask-unless-access-grants

Masks dimension values with MD5 hash when users don't meet specified access grants.

Defines a list of [access grants](/modeling/models/access-grants) for the dimension that determine whether values should be masked. When a user doesn't satisfy the specified access grants, dimension values are replaced with an MD5 hash. Unlike [`required_access_grants`](/modeling/dimensions/parameters/required-access-grants), which blocks access to the field entirely, this parameter allows users to see masked values.

This parameter is useful when you want to:

* Allow users to perform aggregations and analysis on sensitive data without exposing the actual values
* Enable joins and grouping on sensitive fields while protecting personally identifiable information (PII)
* Maintain data structure and relationships in queries while masking sensitive information

## Syntax

```yaml theme={null}
<dimension_name>:
  mask_unless_access_grants: [<grants_and_conditions>]
```

## Properties

<ParamField type="object[]">
  The name of the dimension.

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      An array of access grant names that control data masking for the dimension. Each value must match an [access grant](/modeling/models/access-grants) defined in the model file. When the user doesn't satisfy the access grants, values are replaced with an MD5 hash.

      Use `|` for `OR` conditions and `&` for `AND` conditions within the same array element.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Mask data unless user has marketing access" theme={null}
customer_email:
  mask_unless_access_grants: [marketing]
```

```yaml title="Mask data unless user has marketing OR sales access" theme={null}
customer_email:
  mask_unless_access_grants: [marketing|sales]
```

```yaml title="Mask data unless user has marketing OR (sales AND product) access" theme={null}
customer_email:
  mask_unless_access_grants: [marketing|sales&product]
```


# order_by_field - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/order-by-field

Sets a field to be sorted by another field's values.

The order by field will be implicitly added to the query, but not shown in the result data unless explicitly included.

This parameter is often used when the main field is used to label buckets that put them in non-alphabetical order. For example, handling of `day_of_week` (orders by `day_of_week_number`) or `month` (orders by `month_of_year`).

This can be effective for sorting dynamically-grouped fields, such as `duration`.

Avoid specifying an `order_by_field` with more than one value for a given value of the dimension on which the `order_by_field` is defined. This can impact aggregations and seemingly create duplicate rows.

## Syntax

```yaml theme={null}
<dimension_name>:
  order_by_field: <field_reference>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      An unquoted field reference specifying which field to use for sorting.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Custom sort order for bins" theme={null}
bin:
  order_by_field: bin_order
  sql: |
    CASE
      WHEN price > 100 THEN 'High'
      WHEN price > 20 THEN 'Medium'
      ELSE 'Low'
    END

bin_order:
  sql: |
    CASE
      WHEN price > 100 THEN 3
      WHEN price > 20 THEN 2
      ELSE 1
    END
```


# parent_field - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/parent-field

Declares a dimension as a child of another dimension for nested field display.

This parameter defines a parent-child relationship between dimensions, which is used to represent nested fields such as those produced by denesting JSON or `STRUCT` columns from your database schema.

Children of a parent dimension display below the parent in the field browser, similar to fields grouped with [`group_label`](/modeling/dimensions/parameters/group-label). By default, a child's label is prefixed with its parent's label — see [`skip_parent_label`](/modeling/dimensions/parameters/skip-parent-label) to change this behavior.

Omni automatically generates `parent_field` when you:

* Use the **Create fields from JSON** functionality in the model IDE, or
* Add fields from `STRUCT` columns in your database schema.

## Syntax

```yaml theme={null}
<dimension_name>:
  parent_field: <parent_dimension_name>
```

## Properties

<ParamField type="object">
  The name of the child dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      The name of the parent dimension in the same view. The child dimension will display nested beneath this field in the field picker.
    </ParamField>
  </Expandable>
</ParamField>

## Example

Consider a nested JSON `order_info` field that contains `status`, `email`, and `state` attributes:

```yaml theme={null}
dimensions:
  order_info:
    sql: ${TABLE}.order_info

  order_info_status:
    sql: ${order_info}:status::STRING
    parent_field: order_info

  order_info_email:
    sql: ${order_info}:email::STRING
    parent_field: order_info

  order_info_state:
    sql: ${order_info}:state::STRING
    parent_field: order_info
```

In the field browser, `order_info_status`, `order_info_email`, and `order_info_state` display nested under `order_info`. By default, their labels are prefixed with `Order Info` — for example, `Order Info Status`.


# primary_key - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/primary-key

Sets the primary key on a view for preventing fan outs in calculations.

<Note>
  By default, Omni will assign fields labeled like `id` or `table_id` as primary keys when generating a model. For example, the `users_id` on a `users` table. Primary keys can also be automatically set using dbt constraints.
</Note>

Primary keys are used to prevent fan outs when calculating metrics with more than one table, in conjunction with the join relationship.

They can be defined using this parameter or in the workbook by hovering over a field and clicking <Icon icon="ellipsis-vertical" /> **> Modeling > Primary key**.

For situations where a database column is not available for `primary_key` declaration - for example, compound keys like `CONCAT(id, '-', user_id)` - Omni recommends creating a new field and setting that field as the primary key. Alternatively, for compound primary keys, you can set [`custom_compound_primary_key_sql`](/modeling/views/parameters/custom-compound-primary-key-sql) at the view level to define an array of fields that make up the view's primary key.

## Syntax

```yaml theme={null}
<dimension_name>:
  primary_key: true
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="boolean">
      When set to `true`, designates this field as the primary key for the view.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Simple primary key" theme={null}
id:
  primary_key: true
```

```yaml title="Compound primary key" theme={null}
compound_primary_key_field:
  sql: concat(${field_1},'-',${field_2})
  primary_key: true
  hidden: true
```


# required_access_grants - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/required-access-grants

Defines a list of access grants for the dimension, which are used to control access.

Defines a list of access grants for the dimension, which are used to control access. The values of this parameter must match the name of an access grant in the model file's [`access_grants`](/modeling/models/access-grants) parameter.

Refer to the [Controlling data access guide](/modeling/develop/data-access-control) for more information and examples.

You can also conditionally allow access by using pipes (`|`) and ampersands (`&`) to create `OR` and `AND` conditions.

## Syntax

```yaml theme={null}
<dimension_name>:
  required_access_grants: [<grants_and_conditions>]
```

## Properties

<ParamField type="object[]">
  The name of the dimension.

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      An array of access grant names that control access to the dimension. Each value must match an access grant defined in the model file. Use `|` for `OR` conditions and `&` for `AND` conditions within the same array element.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Define one required access grant" theme={null}
full_name:
  required_access_grants: [marketing]
```

```yaml title="Grant access if conditions are met for either access grant" theme={null}
full_name:
  required_access_grants: [marketing|sales]
```

```yaml title="Grant access if conditions are met for marketing OR sales AND product" theme={null}
full_name:
  required_access_grants: [marketing|sales&product]
```


# sample_values - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/sample-values

Provides sample values to the Omni Agent to better understand field content and usage.

Sample values that help the [Omni Agent](/ai/chat) understand the type of data contained in this dimension. These values are used by the AI to make better field selection decisions and provide more accurate query results.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<dimension_name>:
  sample_values: [<value_1>, <value_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      A list of representative values from the dimension. The list doesn't need to be exhaustive. These values help the AI understand the content and context of the field.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Product category samples" theme={null}
product_category:
  sample_values: [Electronics, Clothing, Home & Garden, Sports, Books]
```

```yaml title="Status field samples" theme={null}
order_status:
  sample_values: [pending, processing, shipped, delivered, cancelled]
```


# skip_parent_label - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/skip-parent-label

Controls whether child dimension labels are prepended with the parent field label in grouped dimensions.

This parameter controls how child dimension labels display within a group of dimensions, such as fields created from denesting JSON.

## Syntax

```yaml theme={null}
<dimension_name>:
  skip_parent_label: <always | never | explicit_child_label>
```

## Properties

<ParamField type="object">
  The name of the parent dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      Controls whether child dimensions prepend their label with the parent field label. Options:

      * `always` - Parent label is never prepended to child dimensions
      * `never` - Parent label is always prepended to child dimensions (default when unset)
      * `explicit_child_label` - Child dimensions with an explicit label set will not have the parent label prepended, but those without explicit labels will
    </ParamField>
  </Expandable>
</ParamField>

## Examples

Consider this example of a nested JSON field:

```yaml theme={null}
order_info:
  sql: "PARSE_JSON(CONCAT('{\"status\":\"', ${ecomm__order_items.status} ::
    STRING, '\", \"email\":\"', ${ecomm__users.email}, '\", \"state\":\"',
    ${ecomm__users.state}, '\"}'))"
```

If you were to denest the parent `order_info` field, it would create three child fields: `status`, `email`, and `state`. The following examples will use this field to demonstrate how the `skip_parent_label` parameter would work.

### Always skip parent label

```yaml title="All child dimensions without parent label prefix" theme={null}
order_info:
  skip_parent_label: always
```

With this setting, child dimensions appear as:

* `status` (not `Order info Status`)
* `email` (not `Order info Email`)
* `state` (not `Order info State`)

### Never skip parent label

```yaml title="All child dimensions with parent label prefix" theme={null}
order_info:
  skip_parent_label: never
```

With this setting, all child dimensions include the parent label:

* `Order Info Status`
* `Order Info Email`
* `Order Info State`

### Skip parent label for explicit child labels

```yaml title="Selective label prepending based on explicit labels" theme={null}
order_info:
  skip_parent_label: explicit_child_label

order_info_custom:
  sql: ${order_info}
  label: Custom Order Info
  group_label: Order info
```

With this setting:

* `order_info_custom` displays as `Custom Order Info` because it has an explicit label
* Child dimensions have `Order Info` prepended as they don't have explicit labels. For example, `Order Info State`

## Related parameters

* [`group_label`](/modeling/dimensions/parameters/group-label) - Nests fields in the field browser
* [`label`](/modeling/dimensions/parameters/label) - Sets a custom display label for a field


# sql - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/sql

The core declaration of the field definition using SQL.

The core declaration of the field definition. Best practice dictates using field references over raw database columns when calling other fields/dimensions. Note that dimensions can only be derived from other dimensions, unlike measures.

## Syntax

```yaml theme={null}
<dimension_name>:
  sql: <sql_expression>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      A SQL expression that defines the dimension. If the SQL includes protected words (e.g., `group`), include them with the following syntax: ``"`group`"``

      Field type is implicit in Omni, and defined based upon the underlying field's database type. To change the type, `CAST` the field (for example, `sql: ${zip_code}::string`).

      <Tip>
        When referencing other fields, use Omni field references (`${view.name}`) instead of the raw database name. For example, `${orders.id}`
      </Tip>
    </ParamField>
  </Expandable>
</ParamField>

## DO NOT PARSE (special argument)

`DO NOT PARSE` is a special argument used to stop Omni's parser from interpreting and validating the SQL. This should be used in the rare circumstance that Omni is not saving valid SQL in the model, which can happen when obscure, dialect-specific SQL is used.

```yaml DO NOT PARSE usage theme={null}
<dimension_name>:
  sql: |-
    -- DO NOT PARSE
    <sql_expression>
crazy_sql:
  sql: |-
    -- DO NOT PARSE
    function_that_is_weird(${field})
```

## Examples

```yaml Concatenated fields theme={null}
full_name:
  sql: CONCAT(${users.first_name}, ' ', ${users.last_name})
```

```yaml Calculated margin theme={null}
margin:
  sql: ${order_items.sale_price} - ${products.cost}
```

```yaml Case statement theme={null}
is_special_date:
  sql: |-
    CASE
      WHEN ${orders.created_at[date]} >= '2022-04-14' AND ${orders.created_at[date]} <= '2022-05-09'
      THEN 'Mothers Day 2022'
      WHEN ${orders.created_at[date]} >= '2022-05-26' AND ${orders.created_at[date]} <= '2022-06-20'
      THEN 'Fathers Day 2022'
      ELSE 'Other'
    END
```

```yaml DO NOT PARSE usage theme={null}
state_sentiment:
  sql: |-
    -- DO NOT PARSE
    SNOWFLAKE.CORTEX.SENTIMENT(${states.state})::float
```

```yaml Type casting theme={null}
zip_code_string:
  sql: ${zip_code}::string
```


# suggest_from_field - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/suggest-from-field

Specifies an alternative field to use for filter suggestions.

Specifies an alternative field to use for filter suggestions. By default, filters run a `SELECT DISTINCT(${field})` to populate filter suggestions. In scenarios where that query may be less performant, or in places where developers may want to curate the suggestion list, this parameter can be used to suggest via an alternative field's distinct values.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Limitations

This parameter can't be used with [`faceting`](/modeling/dimensions/parameters/faceting) on the same dimension.

## Syntax

```yaml theme={null}
<dimension_name>:
  suggest_from_field: <view_name>.<field_name>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      The field to use for filter suggestions, specified as `view_name.field_name`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Filter-only field with suggestions" theme={null}
filters:
  status:
    type: string
    suggest_from_field: order_items.status
```

```yaml title="Dimension with alternative suggestions" theme={null}
status_from_an_obscure_subquery:
  sql: status_from_an_obscure_subquery
  suggest_from_field: order_items.status
```


# suggest_from_topic - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/suggest-from-topic

Explicitly sets the topic to use for filter suggestions.

Explicitly sets the topic to use for filter suggestions. By default, suggestions come from the current topic. In cases where performance may need to be optimized, the query can be sent to a topic that's either more performant or reduces load by applying filters.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Limitations

This parameter can't be used with [`faceting`](/modeling/dimensions/parameters/faceting) on the same dimension.

## Syntax

```yaml theme={null}
<dimension_name>:
  suggest_from_topic: <topic_name>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      The name of the topic to use for filter suggestions. For example, if the topic's file name is `User Orders` in the model IDE, this value would be `user_orders`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml Populate suggestions from the order_items_small topic theme={null}
status:
  suggest_from_field: order_items.status
  suggest_from_topic: order_items_small
```

```yaml Populate suggestions from filtered topic theme={null}
country:
  suggest_from_field: country
  suggest_from_topic: topic_always_where_sql_to_usa
```


# suggestion_list - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/suggestion-list

Explicitly sets the list of filter options, bypassing default behavior.

Explicitly sets the list of filter options, bypassing default behavior. By default, filters run a `SELECT DISTINCT(${field})` to populate filter suggestions. Using this parameter will bypass the default behavior and explicitly set the list of filter options.

Values can be displayed using a label or as they appear in the dataset. Using a label can increase comprehensiveness in cases where the underlying value may not be intuitive to users.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Syntax

```yaml theme={null}
<dimension_name>:
  suggestion_list:
    - value: <value>
      label: <optional_label>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="object[]">
      An array of suggestion objects.

      <Expandable title="suggestion_list properties">
        <ParamField type="string">
          The actual value that will be used in the filter.
        </ParamField>

        <ParamField type="string">
          Optional display label for the value. If not provided, the `value` is displayed.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Complete and Pending will display in the list" theme={null}
status:
  suggestion_list:
    - value: Complete
    - value: Pending
```

```yaml title="Monthly and Weekly will display in the list" theme={null}
filter_suggest:
  type: string
  suggestion_list:
    - value: "week"
      label: Weekly
    - value: "month"
      label: Monthly
```


# synonyms - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/synonyms

Alternative names and terms for a dimension that help the Omni Agent match user queries to the correct field.

When users ask questions using different terminology, synonyms help the AI understand which field they mean.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<dimension_name>:
  synonyms: [<synonym_1>, <synonym_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      A list of alternative names and terms that refer to this dimension. Include common variations, abbreviations, and domain-specific terminology.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Customer field synonyms" theme={null}
customer_name:
  synonyms: [client, account, buyer, purchaser]
```

```yaml title="Revenue field synonyms" theme={null}
total_revenue:
  synonyms: [sales, income, earnings, gross revenue, top line]
```

```yaml title="Date field synonyms" theme={null}
order_date:
  synonyms: [purchase date, transaction date, order timestamp]
```


# tags - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/tags

Apply tags to dimensions for searchable metadata in workbooks and use tag syntax to curate topic fields and drill field lists.

Tags can be referenced or searched in the workbook's field browser within `fields` or `drill_fields` with the syntax `tag:tag_name`.

## Syntax

```yaml theme={null}
<dimension_name>:
  tags: [<tag_1>, <tag_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      An unquoted list using `[]` and a comma-delimited list of tag values.

      If using [Databricks Unity Catalog](/connect-data/databricks-unity-catalog-integration), schema refreshes automatically populate this parameter from the column's Unity Catalog `COLUMN_TAGS`. A tag with a value renders as `name: value`, and a tag without a value renders as a bare `name`. This doesn't apply to legacy `hive_metastore` catalogs, which don't have Unity Catalog tag data. If you edit `tags` in the shared model, your changes are preserved on later refreshes.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="PII tags" theme={null}
full_name:
  sql: CONCAT(${first_name}, ' ' ${last_name})
  tags: [pii, secure]
```

```yaml title="Finance tags" theme={null}
profit:
  sql: ${sales} - ${cost}
  tags: [finance, secure]
```

```yaml Databricks Unity Catalog tag with a value theme={null}
full_name:
  tags: [ "pii: A"]
```

```yaml Databricks Unity Catalog tag without a value theme={null}
full_name:
  tags: [ pii ]
```


# timeframes - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/timeframes

Sets the default time segments available for date/time fields in workbooks.

If absent, Omni uses default timeframes: `raw`, `date`, `week`, `month`, `quarter`, `year`.

Timezone handling is possible using the [`convert_tz`](/modeling/dimensions/parameters/convert-tz) argument, done in concert with connection-level [timezone settings](/connect-data/timezones).

Date or time fields can reference parameterized timeframes in the model as follows:

* `timestamp_created_at` (the 'raw' reference)
* `timestamp_created_at[date]`
* `timestamp_created_at[year]`
* `timestamp_created_at[day_of_week_name]`
* `timestamp_created_at[month_name]`

## Syntax

```yaml theme={null}
<dimension_name>:
  timeframes: [<timeframe_1>, <timeframe_2>, ...]
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string[]">
      An array of timeframe names to make available for this date/time field. The following timeframes are supported:

      | Name               | Notes                                                                  |
      | ------------------ | ---------------------------------------------------------------------- |
      | `date`             |                                                                        |
      | `day_of_month`     |                                                                        |
      | `day_of_quarter`   | Behaves as fiscal day of quarter when fiscal offset is applied         |
      | `day_of_week_name` | Sorts by `day_of_week_num`                                             |
      | `day_of_week_num`  |                                                                        |
      | `day_of_year`      |                                                                        |
      | `fiscal_quarter`   | Requires [`fiscal_month_offset`](/modeling/models/fiscal-month-offset) |
      | `fiscal_year`      | Requires [`fiscal_month_offset`](/modeling/models/fiscal-month-offset) |
      | `hour`             |                                                                        |
      | `hour_of_day`      |                                                                        |
      | `millisecond`      |                                                                        |
      | `minute`           |                                                                        |
      | `month`            |                                                                        |
      | `month_name`       | Sorts by `month_num`                                                   |
      | `month_num`        |                                                                        |
      | `quarter`          |                                                                        |
      | `quarter_of_year`  |                                                                        |
      | `raw`              |                                                                        |
      | `second`           |                                                                        |
      | `week`             |                                                                        |
      | `year`             |                                                                        |
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Custom timeframes" theme={null}
created_at:
  sql: created_at
  timeframes: [date, week, day_of_week_name]
  convert_tz: false
```

```yaml title="Timezone-specific field" theme={null}
timestamp_created_pst:
  sql: DATETIME(${marketing_orders_new.timestamp_created}, 'America/Los_Angeles')
  timeframes:
    - DATE
    - HOUR_OF_DAY
    - MONTH_NAME
```

Custom timeframes can be included using [`group_label`](/modeling/dimensions/parameters/group-label). The `group_label` should match the label rather than the underlying field:

```yaml title="Custom timeframe in existing group" theme={null}
created_at_minute_5:
  sql: id+1
  group_label: Created At
```


# view_label - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/view-label

Move a dimension under a different view in the field browser for better organization, such as grouping user_facts under users.

For example, grouping `user_facts` fields under the `users` view for better organization and discovery.

## Syntax

```yaml theme={null}
<dimension_name>:
  view_label: <view_name>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      The name of the view to nest the field under.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Group under different view" theme={null}
lifetime_orders:
  sql: user_facts.lifetime_orders
  view_label: users
```


# week_start_day - Dimensions
Source: https://docs.omni.co/modeling/dimensions/parameters/week-start-day

Defines the day that weeks start on for a specific dimension.

Defines the day that weeks start on for a specific dimension. This parameter can only be added to a dimension and should only be used on date, time, or timestamp dimensions.

<Note>
  `week_start_day` can also be set at the [model](/modeling/models/week-start-day) and [topic levels](/modeling/topics/parameters/week-start-day). When set at more than one level, the most specific setting is applied: dimension overrides topic, and topic overrides model.
</Note>

## Syntax

```yaml theme={null}
<dimension_name>:
  week_start_day: <day_of_week>
```

## Properties

<ParamField type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties">
    <ParamField type="string">
      The day of the week that weeks start on for this dimension. Valid values are: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`.

      Unlike the model-level and topic-level settings, this value must be a plain day name. User attributes aren't supported for this parameter.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Set week start day on a dimension" theme={null}
shipped_at:
  sql: shipped_at
  week_start_day: Thursday
```


# Filter examples
Source: https://docs.omni.co/modeling/filters/examples



## Time filters

<AccordionGroup>
  <Accordion title="In the past 7 days">
    In use: [`time_for_duration`](/modeling/filters/operators/time-for-duration)

    ```yaml theme={null}
    users.created_at:
      time_for_duration: [ 7 days ago, 7 days ]
    ```
  </Accordion>

  <Accordion title="In the past 7 complete days">
    In use: [`time_for_duration`](/modeling/filters/operators/time-for-duration)

    ```yaml theme={null}
    users.created_at:
      time_for_duration: [ 7 complete days ago, 7 days ]
    ```
  </Accordion>

  <Accordion title="Is in a date range">
    **Note**: End dates are *inclusive*, so this will include data from `2023-04-30`.

    In use: [`between_dates`](/modeling/filters/operators/between-dates)

    ```yaml theme={null}
    users.created_at:
      between_dates: [ 2023-04-01, 2023-04-30 ]
    ```
  </Accordion>

  <Accordion title="Before fixed date">
    In use: [`before`](/modeling/filters/operators/before)

    ```yaml theme={null}
    users.created_at:
      before: 2023-04-01
    ```
  </Accordion>

  <Accordion title="On or after specific date">
    In use: [`on_or_after`](/modeling/filters/operators/on-or-after)

    ```yaml theme={null}
    users.created_at:
      on_or_after: 2023-04-01
    ```
  </Accordion>

  <Accordion title="Is on a specific day">
    In use: [`is`](/modeling/filters/operators/is)

    ```yaml theme={null}
    users.created_at:
      is: 2023-04-01
    ```
  </Accordion>

  <Accordion title="Is between 1 - 1:59 AM on a day">
    In use: [`hour_of_day`](/modeling/filters/operators/hour-of-day)

    ```yaml theme={null}
    users.created_at:
      hour_of_day: "1"
    ```
  </Accordion>

  <Accordion title="Is on Wednesdays">
    In use: [`day_of_week`](/modeling/filters/operators/day-of-week)

    ```yaml theme={null}
    users.created_at:
      day_of_week: Wednesday
    ```
  </Accordion>

  <Accordion title="First 3 months of 2023">
    In use: [`time_for_duration`](/modeling/filters/operators/time-for-duration)

    ```yaml theme={null}
    users.created_at:
      time_for_duration: [ 2023-01-01, 3 months ]
    ```
  </Accordion>
</AccordionGroup>


# Filter syntax
Source: https://docs.omni.co/modeling/filters/index

Write and structure filter definitions in your Omni model YAML using operators, negation, and compound filter expressions.

<Tip>
  **Build your filters faster by starting in the workbook!** Add a filter to a query, save it as a query view, and open the query view editor to check out the underlying YAML. This can help you get the right structure and ensure the results are correct.
</Tip>

Omni's filter syntax is built to mirror how filtering works in the Omni app, whether you're in a workbook or a dashboard. Use the following tabs to see how filters are defined in Omni YAML:

<Tabs>
  <Tab title="Topics" icon="book">
    Use [`always_where_filters`](/modeling/topics/parameters/always-where-filters) and [`default_filters`](/modeling/topics/parameters/default-filters) to add filters to topics. For example:

    ```yaml title="Topic default_filters" theme={null}
    default_filters:
      users.status:
        is: active
    ```
  </Tab>

  <Tab title="Query views" icon="question">
    Query views, which are built from workbook queries, contain a `query` property. The `query.filters` property lists the filters applied to the view's underlying query:

    ```yaml title="Query view filters" highlight={6-12} theme={null}
    query:
      fields:
        users.id: id
        order_items.sale_price_sum: sales
      base_view: order_items
      filters:
        users.age_bin:
          is: []
        users.created_at:
          is: "2021"
        order_items.created_at:
          time_for_duration: [ 30 complete days ago, 30 days ]
    ```
  </Tab>

  <Tab title="Measures" icon="ruler">
    Add filters directly to measures with the [`filters`](/modeling/measures/parameters/filters) property:

    ```yaml title="Filtered measure" highlight={4-6} theme={null}
    measures:
      aggregate_type: count
      count:
        filters:
          status:
            is: active
    ```
  </Tab>
</Tabs>

## Operators

Operators allow you to specify the type of filter you want to apply. Operators consist of a string, appended with a colon (`:`): `<operator>:`. [Filter values](#filter-values) should follow the colon.

For example:

```yaml theme={null}
day_of_week: <filter_value>
less_than: <filter_value>
contains: <filter_value>
```

### Types

Omni supports several types of operators, such as conditional, time, numeric, and text. Refer to the [Filter operators reference](/modeling/filters/operators) for a complete list of operators.

### Negation

Prefix a filter operator with `not_` to create a negation. For example, `day_of_week` would become `not_day_of_week`.

<Warning>
  The `not_` prefix isn't compatible with the following operators:

  * [`is`](/modeling/filters/operators/is) - Use the [`not`](/modeling/filters/operators/not) operator instead
  * [`and`](/modeling/filters/operators/and)
  * [`or`](/modeling/filters/operators/or)
</Warning>

## Filter values

Include filter values after the operator and the colon. Values should be unquoted; quotes will be removed upon saving.

```yaml title="Filter values should be unquoted" theme={null}
starts_with: Blob
```

### Strings and dates

Provide strings and dates as unquoted values:

```yaml title="String value" theme={null}
contains: Blob
```

```yaml title="Date value" theme={null}
before: 2025-01-01
```

### Booleans

Omni supports both two-state (`true` / `false`) and three-state (`true` / `false` / `null`) boolean logic. The special boolean argument `falsey` represents both `false` and `null` and can be used in filters like any other field value.

```yaml title="Counts if error = false or null" theme={null}
non_error_count:
  aggregate_type: count
  filters:
    is_error:
      is: falsey
```

```yaml title="Count if error = false" theme={null}
non_error_count:
  aggregate_type: count
  filters:
    is_error:
      is: false
```

### Arrays / lists

Arrays are constructed using square brackets (`[]`). Add the filter values inside the brackets, for example:

```yaml title="Array of numbers" theme={null}
[ 1, 2, 3 ]
```

```yaml title="Array of strings" theme={null}
[ California, Oregon, Washington ]
```


# and - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/and

Creates a filter where multiple criteria must be met.

Filters based on multiple conditions. Returns rows that meet all specified criteria.

## Syntax

```yaml theme={null}
<field_name>:
  and:
    - <filter_operator>: <value>
    - <filter_operator>: <value>
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="string">
  The `and` operator. Contains a list of conditions that must be met to be included in the filter results:

  <Expandable title="conditions">
    <ParamField type="string">
      A filter operator such as [`before`](/modeling/filters/operators/before), [`greater_than`](/modeling/filters/operators/greater-than), etc. and its corresponding value.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Matches dates in Q1 on the 15th of the month (January, February, March 15)" theme={null}
users.created_date:
  and:
    - quarter_of_year: 1
    - day_of_month: 15
```


# before - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/before

Filters time fields for dates before a specified date.

Filters time fields for dates before a specified date. Returns rows where the date is less than the specified date.

## Syntax

```yaml theme={null}
<time_field>:
  before: <date>
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string | date">
  The date threshold. Returns rows where the field value is less than this date. Can be:

  * **Fixed date** - Specified in `YYYY-MM-DD` format. For example, `2024-01-01`.
  * **Relative date** - For example, `today`, `7 days ago`
</ParamField>

## Examples

```yaml title="Date is before January 1, 2024" theme={null}
users.created_at:
  before: 2024-01-01
```

```yaml title="Date is before today's date" theme={null}
orders.order_date:
  before: today
```


# between - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/between

Filters numeric fields for values within a specified range.

Filters numeric fields for values within a specified range. Returns rows where the field value falls between the minimum and maximum values.

<Tip>
  This filter is **inclusive** of the minimum and maximum values.
</Tip>

## Syntax

```yaml theme={null}
<numeric_field>:
  between: [<min_value>, <max_value>]
```

## Properties

<ParamField type="string">
  The numeric field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number[]">
  An array with two numeric values. Decimals are supported.

  * `min_value` - The minimum value. Rows with this value will be included in the results.
  * `max_value` - The maximum value. Rows with this value will be included in the results.
</ParamField>

## Examples

```yaml title="Total price is between 10 and 100" theme={null}
orders.total_price:
  between: [10.00, 100.00]
```

```yaml title="Age is not between 18 and 30" theme={null}
users.age:
  between: [18, 30]
```


# between_dates - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/between-dates

Filters time fields for dates falling within a specified range.

Filters time fields for dates falling within a specified range. Returns rows where the date is between the start and end dates (inclusive).

<Tip>
  This filter is **inclusive** of the start date and end date.
</Tip>

## Syntax

```yaml theme={null}
<time_field>:
  between_dates: [<start_date>, <end_date>]
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="date[]">
  An array with two date values: `[start_date, end_date]`. Dates can be:

  * **Fixed date** - Specified in `YYYY-MM-DD` format. For example, `2024-01-01`.
  * **Relative date** - For example, `today`, `7 days ago`
</ParamField>

## Examples

```yaml title="Between two fixed dates" theme={null}
users.created_at:
  between_dates: [2024-01-01, 2024-12-31]
```

```yaml title="Between two relative dates" theme={null}
events.event_date:
  between_dates: [7 days ago, today]
```


# cancel_query_filter - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/cancel-query-filter

Creates a measure that ignores the value of a filter in the user query in favor of the filter on the measure itself.

Creates a measure that ignores the value of a filter in the user query in favor of the filter on the measure itself. This creates measures that maintain their specific filter criteria regardless of what filters the user applies in the query.

<Note>
  This is an advanced filter property that can be added as an argument to any other filter on a measure. It's commonly used with [`date_offset_from_query`](/modeling/filters/operators/date-offset-from-query) for period-over-period comparisons, but can be used with any filter.
</Note>

## Syntax

```yaml theme={null}
measures:
  <measure_name>:
    aggregate_type: <type>
    filters:
      <field>:
        <filter_operator>: <value>
        cancel_query_filter: true
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="varies">
  Any standard filter operator (e.g., [`is`](/modeling/filters/operators/is), [`not`](/modeling/filters/operators/not), [`greater_than`](/modeling/filters/operators/greater-than), [`date_offset_from_query`](/modeling/filters/operators/date-offset-from-query), etc.) with its corresponding value.
</ParamField>

<ParamField type="boolean">
  If `true`, the measure will ignore a query's filter value. Instead, the measure will use the filter defined on the measure itself.
</ParamField>

## Examples

For this example, you're querying a dataset that has a `state: New York` filter applied. Using the following `compare_to_users_in_california` measure in your query would allow you to see the count of users for `California` without changing the filter in your query.

If `cancel_query_filter` were not applied, you would receive zero results - this is because the measure would filter for users in `California` within a query filtered for `New York`.

```yaml title="Ignore filters on state" theme={null}
measures:
  compare_to_users_in_california:
    aggregate_type: count
    filters:
      state:
        is: California
        cancel_query_filter: true
```

### Ignore filters on specified fields

The following example demonstrates how to create a measure that ignores any query filters on two specified fields. Setting the filter to `is: ""` for both `created_at` and `state` tells the measure to ignore any filter on these fields, allowing comparison to all-time totals regardless of any filters applied to the query.

```yaml title="Ignore all filters on created_at and state" theme={null}
measures:
  users_in_all_states_all_time:
    aggregate_type: count
    filters:
      created_at:
        is: ""
        cancel_query_filter: true
      state:
        is: ""
        cancel_query_filter: true
```

```yaml theme={null}
signups_two_years_ago:
  aggregate_type: count
  filters:
    created_at:
      date_offset_from_query: 2 years
      cancel_query_filter: true
```

### Ignore specific filters in a level of detail field

You can use `cancel_query_filter` within the `filters` parameter of a `level_of_detail` calculation to selectively ignore specific global filters for that LoD only. This allows you to keep some global filters while dropping others, rather than using `cancel_query_filters: true` which ignores all global filters.

```yaml title="Dimension with selective filter cancellation" theme={null}
arr_balance_by_logo:
  sql: ${accounts.arr_cumulative}
  level_of_detail:
    aggregate_type: max
    fixed: [logo, date]
    filters:
      date:
        is: ""
        cancel_query_filter: true  # Drops global date filter, keeps other filters
```

```yaml title="Measure with selective filter cancellation" theme={null}
measures:
  california_revenue:
    aggregate_type: sum
    sql: ${revenue}
    level_of_detail:
      aggregate_type: sum
      fixed: [state]
      filters:
        state:
          is: California  # Replaces global state filter with California
          cancel_query_filter: true
```

This feature works on both [dimension `level_of_detail`](/modeling/dimensions/parameters/level-of-detail) and [measure `level_of_detail`](/modeling/measures/parameters/level-of-detail).


# case_insensitive - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/case-insensitive

Modifies string filter operators to perform case-insensitive matching.

Modifies string filter operators to perform case-insensitive matching. When set to `true`, string comparisons ignore differences in letter casing. Defaults to `false` unless explicitly set to `true`.

<Note>
  This is a modifier property used in conjunction with other string filters like [`starts_with`](/modeling/filters/operators/starts-with), [`ends_with`](/modeling/filters/operators/ends-with), [`contains`](/modeling/filters/operators/contains), or [`is`](/modeling/filters/operators/is).
</Note>

## Syntax

```yaml theme={null}
<string_field>:
  <string_operator>: <value>
  case_insensitive: true
```

## Properties

<ParamField type="string">
  The string field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The string filter operator to modify. Can be:

  * [`starts_with`](/modeling/filters/operators/starts-with)
  * [`ends_with`](/modeling/filters/operators/ends-with)
  * [`contains`](/modeling/filters/operators/contains)
  * [`is`](/modeling/filters/operators/is)
</ParamField>

<ParamField type="boolean">
  If `true`, string comparisons will be case-insensitive. Omit or set to `false` for case-sensitive matching.
</ParamField>

## Examples

```yaml title="Matches any of: admin, Admin, ADMIN" theme={null}
users.email:
  starts_with: admin
  case_insensitive: true
```

```yaml title="Matches any of: Premium, PREMIUM, premium" theme={null}
products.name:
  contains: premium
  case_insensitive: true
```

```yaml title="Matches: active (case-sensitive)" theme={null}
customers.status:
  is: active
  case_insensitive: false
```


# contains - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/contains

Filters string fields for values that contain a specified substring.

Filters string fields for values that contain a specified substring. Returns rows where the field value includes the specified substring.

Can be used with [`case_insensitive`](/modeling/filters/operators/case-insensitive) to perform case-insensitive matching.

## Syntax

```yaml theme={null}
<string_field>:
  contains: <substring>
```

## Properties

<ParamField type="string">
  The string field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The substring to search for. Returns rows where the field value includes this substring.
</ParamField>

<ParamField type="boolean">
  When set to `true`, performs case-insensitive matching. Defaults to `false` (case-sensitive) if omitted.
</ParamField>

## Examples

```yaml title="Matches: Blob premium, For premium blobs, etc." theme={null}
products.description:
  contains: premium
```

```yaml title="Matches: Blobby Blobbington, The Great Blobby, etc." theme={null}
users.name:
  contains: Blobby
```

```yaml title="Matches: error, ERROR, Error, etc." theme={null}
messages.content:
  contains: error
  case_insensitive: true
```


# date_offset_from_query - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/date-offset-from-query

Specifies a filter dynamically relative to the date filter applied to a workbook query.

Specifies a filter dynamically relative to the date filter applied to a workbook query. This is an advanced filter primarily used in filtered measures for period-over-period comparisons.

**Using the period-over-period (PoP) workbook functionality will create this measure type for you.** After enabling PoP in the workbook, flatten the pivot and then add the fields produced by the flattening to the workbook.

## Requirements

**Must be used with `cancel_query_filter: true`.** Without [`cancel_query_filter`](/modeling/filters/operators/cancel-query-filter) the measure will filter for both the query date **and** the offset date, which will typically return zero results.

## Syntax

```yaml theme={null}
measures:
  <measure_name>:
    aggregate_type: <type>
    filters:
      <time_field>:
        date_offset_from_query: <time_offset>
        cancel_query_filter: true
```

## Properties

<ParamField type="string">
  The time or date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The time offset to apply relative to the query's date filter. For example, `2 years`, `30 days`, etc.
</ParamField>

<ParamField type="boolean">
  Must be set to `true` when using `date_offset_from_query`. This prevents the filter from applying both the query date and the offset date and yielding unexpected (typically zero) results.
</ParamField>

## Examples

For this example, assume the current month is `November 2024`. If you apply a filter of `last month` and add the following measure to your query, the results will show the count from `October 2022`.

```yaml theme={null}
measures:
  count_signups_same_time_two_years_previously:
    aggregate_type: count
    filters:
      created_at:
        date_offset_from_query: 2 years
        cancel_query_filter: true
```


# day_of_month - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/day-of-month

Filters time fields by the day of the month.

Filters time fields by the day of the month. Returns rows where the date falls on the specified day of the month.

## Syntax

```yaml theme={null}
<time_field>:
  day_of_month: <day_number>
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The day of the month to filter for. Value must be a number between `1` and `31`.
</ParamField>

## Examples

```yaml title="First day of month" theme={null}
users.created_at:
  day_of_month: "1"
```

```yaml title="Not the first day of month" theme={null}
users.created_at:
  not_day_of_month: "1"
```


# day_of_quarter - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/day-of-quarter

Filters time fields by the day of the quarter.

Filters time fields by the day of the quarter. Returns rows where the date falls on the specified day of the quarter.

## Syntax

```yaml theme={null}
<time_field>:
  day_of_quarter: <day_number>
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The day(s) of the quarter to filter for. Value must be a number between `1` and `92`.
</ParamField>

## Examples

```yaml title="First day of quarter" theme={null}
users.created_at:
  day_of_quarter: "1"
```

```yaml title="Not the last day of quarter" theme={null}
users.created_at:
  day_of_quarter: "92"
```


# day_of_week - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/day-of-week

Filters time fields by the day of the week.

Filters time fields by the day of the week. Returns rows where the date falls on the specified day of the week.

## Syntax

```yaml theme={null}
<time_field>:
  day_of_week: "<day>"
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The day of the week to filter for. The value can be either the full name of the day or a number:

  * `0` - `Sunday`
  * `1` - `Monday`
  * `2` - `Tuesday`
  * `3` - `Wednesday`
  * `4` - `Thursday`
  * `5` - `Friday`
  * `6` - `Saturday`
</ParamField>

## Examples

```yaml title="Day of week is Monday" theme={null}
users.created_at:
  day_of_week: "Monday"
```

```yaml title="Day of week is not Sunday" theme={null}
users.created_at:
  not_day_of_week: "0"
```


# day_of_year - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/day-of-year

Filters time fields by the day of the year.

Filters time fields by the day of the year. Returns rows where the date falls on the specified day of the year.

## Syntax

```yaml theme={null}
<time_field>:
  day_of_year: <day_number>
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The day of the year to filter for. Must be a number between `1` and `365`, or `366` for leap years.
</ParamField>

## Examples

```yaml title="Date is January 1" theme={null}
users.created_at:
  day_of_year: 1
```


# ends_with - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/ends-with

Filters string fields for values that end with a specified substring.

Filters string fields for values that end with a specified substring. Returns rows where the field value ends with the specified suffix.

Can be used with [`case_insensitive`](/modeling/filters/operators/case-insensitive) to perform case-insensitive matching.

## Syntax

```yaml theme={null}
<string_field>:
  ends_with: <suffix>
```

## Properties

<ParamField type="string">
  The string field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The suffix string to match. Returns rows where the field value ends with this substring.
</ParamField>

<ParamField type="boolean">
  When set to `true`, performs case-insensitive matching. Defaults to `false` (case-sensitive) if omitted.
</ParamField>

## Examples

```yaml title="Matches: blobby@blobsrus.com, blob.ross@blobsrus.com, etc." theme={null}
users.email:
  ends_with: @blobsrus.com
```

```yaml title="Matches: Everything but @gmail.com emails" theme={null}
users.email:
  not_ends_with: @gmail.com
```

```yaml title="Matches: blobsrus.com, BlobRoss.com, etc." theme={null}
domains.url:
  ends_with: .com
  case_insensitive: true
```


# field_name_in_query - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/field-name-in-query

Include only rows whose values appear in the results of another query.

Filters a query using the results of another query. Returns only the rows that are included in the other query's results.

In SQL, this generates a `WHERE` clause that looks like `WHERE IN (SELECT...` where the `SELECT` clause is the filtering query.

<Tip>
  To exclude data using the results of another query, use [`field_name_not_in_query`](/modeling/filters/operators/field-name-not-in-query).
</Tip>

## Requirements

**Only supported for use in [query views](/modeling/query-views).** Refer to the [Examples](#examples) section for the complete syntax.

## Syntax

```yaml theme={null}
<field_name>:
  field_name_in_query: <filtering_field_name>
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="string">
  The name of the field in the filtering query, specified in the format `view_name.field_name`. This field must contain the same data and be the same data type as the `field_name`.

  For example, if you filter on a `customers.country` field, the value of `filtering_field_name` should contain a field with country data.
</ParamField>

## Examples

<Tip>
  Click the **SQL** tab in a code block to view the query's underlying SQL definition.
</Tip>

The **first query** in this example - shown below - lists the top 5 countries with the highest number of customer sign ups:

<CodeGroup>
  ```markdown Results theme={null}
  | customers.country | customers.count |
  |-------------------|-----------------|
  | United States	    | 71              |
  | Mexico            | 23              |
  | Singapore         | 15              |
  | Italy	            | 14              |
  | Portugal          | 9               |
  ```

  ```sql SQL theme={null}
    SELECT "country" AS "customers.country",
           COUNT(*) AS "customers.count"
      FROM "blobs_r_us"."main"."customers" AS "customers"
  GROUP BY 1
  ORDER BY 2 DESC
     LIMIT 5
  ```
</CodeGroup>

The **second query** applies a filter that uses the results of **Query 1**. This means that the results should only include the countries that are present in the results of the first query.

<CodeGroup>
  ```markdown Results theme={null}
  | customers.country | orders.count |
  |-------------------|--------------|
  | United States	    | 138          |
  | Italy	            | 15           |
  | Portugal          | 12           |
  | Singapore	        | 11           |
  | Mexico            | 6            |
  ```

  ```sql SQL theme={null}
     SELECT "customers"."country" AS "customers.country",
             COUNT(*) AS "orders.count"
       FROM "blobs_r_us"."main"."orders" AS "orders"
  LEFT JOIN "blobs_r_us"."main"."customers" AS "customers"
         ON "orders"."customer_id" = "customers"."id"
      WHERE "customers"."country" IN (
               SELECT "country" AS "customers.country"
                 FROM "blobs_r_us"."main"."customers" AS "customers"
             GROUP BY "country"
             ORDER BY COUNT(*) DESC
                LIMIT 5
             )
   GROUP BY 1
   ORDER BY 1 DESC
  ```
</CodeGroup>

The underlying YAML for a query view created from **Query 2** would look like the following:

```yaml title="Query view filtered using the results of another query" lines highlight={8-18} theme={null}
label: Total orders for countries with highest sign ups

query:
  fields:
    customers.country: country
    orders.count: dim_count
  base_view: orders
  filters:
    customers.country:
      field_name_in_query: customers.country
      query_structure:
        fields: [ customers.country, customers.count ]
        base_view: customers
        limit: 5
        sorts:
          - field: customers.count
            desc: true
        offset: 0
  sorts:
    - field: orders.count
      desc: true

dimensions:
  dim_count: {}

  country:
    primary_key: true

measures:
  count:
    aggregate_type: count
```


# field_name_not_in_query - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/field-name-not-in-query

Exclude rows whose values appear in the results of another query.

Filters a query using the results of another query. Returns the rows that are **not** included in the other query's results.

In SQL, this generates a `WHERE` clause that looks like `WHERE NOT IN (SELECT...` where the `SELECT` clause is the filtering query.

<Tip>
  To include data using the results of another query, use [`field_name_in_query`](/modeling/filters/operators/field-name-in-query).
</Tip>

## Requirements

**Only supported for use in [query views](/modeling/query-views).** Refer to the [Examples](#examples) section for the complete syntax.

## Syntax

```yaml theme={null}
<field_name>:
  field_name_not_in_query: <filtering_field_name>
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="string">
  The name of the field in the filtering query, specified in the format `view_name.field_name`. This field must contain the same data and be the same data type as the `field_name`.

  For example, if you filter on a `customers.country` field, `filtering_field_name` should contain a field with country data.
</ParamField>

## Examples

<Tip>
  Click the **SQL** tab in a code block to view the query's underlying SQL definition.
</Tip>

The **first query** in this example - shown below - lists the top 5 countries with the highest number of customer sign ups:

<CodeGroup>
  ```markdown Query 1 - Results theme={null}
  | customers.country | customers.count |
  |-------------------|-----------------|
  | United States	    | 71              |
  | Mexico            | 23              |
  | Singapore         | 15              |
  | Italy	            | 14              |
  | Portugal          | 9               |
  ```

  ```sql Query 1 - SQL theme={null}
    SELECT "country" AS "customers.country",
           COUNT(*) AS "customers.count"
      FROM "blobs_r_us"."main"."customers" AS "customers"
  GROUP BY 1
  ORDER BY 2 DESC
     LIMIT 5
  ```
</CodeGroup>

The **second query** applies a filter that uses the results of **Query 1**. Because the `field_name_not_in_query` **excludes** data, the results should not include `United States`, `Mexico`, `Singapore`, `Italy`, and `Portugal`:

<CodeGroup>
  ```markdown Query 2 - Results theme={null}
  | customers.country | orders.count |
  |-------------------|--------------|
  | Netherlands       | 12           |
  | Denmark           | 11           |
  | Japan             | 11           |
  | South Africa	    | 9            |
  | Finland           | 6            |
  ```

  ```sql Query 2 - SQL theme={null}
     SELECT "customers"."country" AS "customers.country",
             COUNT(*) AS "orders.count"
       FROM "blobs_r_us"."main"."orders" AS "orders"
  LEFT JOIN "blobs_r_us"."main"."customers" AS "customers"
         ON "orders"."customer_id" = "customers"."id"
      WHERE "customers"."country"
     NOT IN (
                SELECT "country" AS "customers.country"
                  FROM "blobs_r_us"."main"."customers" AS "customers"
              GROUP BY "country"
              ORDER BY COUNT(*) DESC
                LIMIT 5
             )
   GROUP BY 1
   ORDER BY 1 DESC
   LIMIT 5
  ```
</CodeGroup>

The underlying YAML for a query view created from **Query 2** would look like the following:

```yaml title="Query view filtered using the results of another query" lines highlight={8-18} theme={null}
label: Total orders - Excluding most popular countries

query:
  fields:
    customers.country: country
    orders.count: dim_count
  base_view: orders
  filters:
    customers.country:
      field_name_not_in_query: customers.country
      query_structure:
        fields: [ customers.country, customers.count ]
        base_view: customers
        limit: 5
        sorts:
          - field: customers.count
            desc: true
        offset: 0
  sorts:
    - field: customers.country
      desc: true

dimensions:
  dim_count: {}

  country:
    primary_key: true

measures:
  count:
    aggregate_type: count
```


# greater_than - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/greater-than

Filters numeric fields for values greater than a specified number.

Filters numeric fields for values greater than a specified number. Returns rows where the field value is > the specified value.

## Syntax

```yaml theme={null}
<numeric_field>:
  greater_than: <number>
```

## Properties

<ParamField type="string">
  The numeric field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The minimum value (exclusive). Returns rows where the field value is > this number. Decimals are supported.
</ParamField>

## Examples

```yaml title="Total price is 100.01 or more" theme={null}
orders.total_price:
  greater_than: 100.00
```

```yaml title="Age is 20 or less" theme={null}
users.age:
  not_greater_than: 21
```


# greater_than_or_equal_to - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/greater-than-or-equal-to

Filters numeric fields for values greater than or equal to a specified number.

Filters numeric fields for values greater than or equal to a specified number. Returns rows where the field value is ≥ the specified value.

## Syntax

```yaml theme={null}
<numeric_field>:
  greater_than_or_equal_to: <number>
```

## Properties

<ParamField type="string">
  The numeric field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The minimum value (inclusive). Returns rows where the field value is ≥ this number. Decimals are supported.
</ParamField>

## Examples

```yaml title="Total price is 100.00 or more" theme={null}
orders.total_price:
  greater_than_or_equal_to: 100.00
```

```yaml title="Age is 18 or less" theme={null}
users.age:
  not_greater_than_or_equal_to: 18
```


# hour_of_day - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/hour-of-day

Filters time fields by the hour of the day.

Filters time fields by the hour of the day. Returns rows where the timestamp falls within the specified hour.

## Syntax

```yaml theme={null}
<time_field>:
  hour_of_day: <hour_number>
```

## Properties

<ParamField type="string">
  The time/timestamp field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The hour of the day to filter for. Must be a number between `0` (midnight) and `23` (11 PM).
</ParamField>

## Examples

```yaml title="Time falls between 9-9:59 AM" theme={null}
users.created_at:
  hour_of_day: 9
```

```yaml title="Time falls between 12-1 AM" theme={null}
events.event_time:
  hour_of_day: 0
```


# Filter operators
Source: https://docs.omni.co/modeling/filters/operators/index

Reference for all Omni model filter operators, including conditional, date, number, text, and advanced cross-query operators.

## Conditional

| Name                                     | Description                                                    |
| ---------------------------------------- | -------------------------------------------------------------- |
| [`and`](/modeling/filters/operators/and) | Returns rows that meet all specified conditions.               |
| [`or`](/modeling/filters/operators/or)   | Returns rows that meet at least one of the specified criteria. |
| [`is`](/modeling/filters/operators/is)   | Returns rows that exactly match the specified value.           |
| [`not`](/modeling/filters/operators/not) | Returns rows that do not match the specified value.            |

## Advanced

| Name                                                                             | Description                                                                                                          |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [`cancel_query_filter`](/modeling/filters/operators/cancel-query-filter)         | Creates a measure that ignores the value of a filter in the user query in favor of the filter on the measure itself. |
| [`field_name_in_query`](/modeling/filters/operators/field-name-in-query)         | Filters a query using the results of another query, including only the rows present in the filtering query.          |
| [`field_name_not_in_query`](/modeling/filters/operators/field-name-not-in-query) | Filters a query using the results of another query, including only the rows **not** present in the filtering query.  |

## Date and time

| Name                                                                           | Description                                                                             |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| [`before`](/modeling/filters/operators/before)                                 | Filters time fields for dates before a specified date.                                  |
| [`between_dates`](/modeling/filters/operators/between-dates)                   | Filters time fields for dates falling within a specified range.                         |
| [`date_offset_from_query`](/modeling/filters/operators/date-offset-from-query) | Specifies a filter dynamically relative to the date filter applied to a workbook query. |
| [`day_of_month`](/modeling/filters/operators/day-of-month)                     | Filters time fields by the day of the month.                                            |
| [`day_of_quarter`](/modeling/filters/operators/day-of-quarter)                 | Filters time fields by the day of the quarter.                                          |
| [`day_of_week`](/modeling/filters/operators/day-of-week)                       | Filters time fields by the day of the week.                                             |
| [`day_of_year`](/modeling/filters/operators/day-of-year)                       | Filters time fields by the day of the year.                                             |
| [`hour_of_day`](/modeling/filters/operators/hour-of-day)                       | Filters time fields by the hour of the day.                                             |
| [`month_of_year`](/modeling/filters/operators/month-of-year)                   | Filters time fields by the month of the year.                                           |
| [`on_or_after`](/modeling/filters/operators/on-or-after)                       | Filters time fields for dates on or after a specified date.                             |
| [`quarter_of_year`](/modeling/filters/operators/quarter-of-year)               | Filters time fields by the quarter of the year.                                         |
| [`time_for_duration`](/modeling/filters/operators/time-for-duration)           | Filters time fields for a specific duration starting from a given point in time.        |

## Numeric

| Name                                                                               | Description                                                                    |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`between`](/modeling/filters/operators/between)                                   | Filters numeric fields for values within a specified range.                    |
| [`greater_than`](/modeling/filters/operators/greater-than)                         | Filters numeric fields for values greater than a specified number.             |
| [`greater_than_or_equal_to`](/modeling/filters/operators/greater-than-or-equal-to) | Filters numeric fields for values greater than or equal to a specified number. |
| [`less_than`](/modeling/filters/operators/less-than)                               | Filters numeric fields for values strictly less than a specified number.       |
| [`less_than_or_equal_to`](/modeling/filters/operators/less-than-or-equal-to)       | Filters numeric fields for values less than or equal to a specified number.    |

## String

| Name                                                               | Description                                                             |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| [`case_insensitive`](/modeling/filters/operators/case-insensitive) | Modifies string filter operators to perform case-insensitive matching.  |
| [`contains`](/modeling/filters/operators/contains)                 | Filters string fields for values that contain a specified substring.    |
| [`ends_with`](/modeling/filters/operators/ends-with)               | Filters string fields for values that end with a specified substring.   |
| [`starts_with`](/modeling/filters/operators/starts-with)           | Filters string fields for values that start with a specified substring. |
| [`sql_like`](/modeling/filters/operators/sql-like)                 | Filters string fields using `SQL LIKE` pattern matching with wildcards. |


# is - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/is

Filters for exact equality.

Filters for exact equality. This operator applies to all filter types (time, numeric, and string fields) and matches rows where the field value exactly equals the specified value.

<Tip>
  Use [`not`](/modeling/filters/operators/not) to create a negative filter.
</Tip>

## Syntax

```yaml theme={null}
<field_name>:
  is: <value>
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="string | number | date">
  The exact value to match. Type should correspond to the field type (string, number, or date).
</ParamField>

## Examples

```yaml title="Match active users" theme={null}
users.status:
  is: active
```

```yaml title="Match products with a price of 77.00" theme={null}
products.price:
  is: 77.00
```

```yaml title="Match users created on January 1, 2024" theme={null}
users.created_at:
  is: 2024-01-01
```


# less_than - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/less-than

Filters numeric fields for values strictly less than a specified number.

Filters numeric fields for values strictly less than a specified number. Returns rows where the field value is \< the specified value.

## Syntax

```yaml theme={null}
<numeric_field>:
  less_than: <number>
```

## Properties

<ParamField type="string">
  The numeric field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The maximum value (exclusive). Returns rows where the field value is \< this number. Decimals are supported.
</ParamField>

## Examples

```yaml title="Total price is 99.99 or less" theme={null}
orders.total_price:
  less_than: 100.00
```

```yaml title="Age is 19 or more" theme={null}
users.age:
  not_less_than: 18
```


# less_than_or_equal_to - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/less-than-or-equal-to

Filters numeric fields for values less than or equal to a specified number.

Filters numeric fields for values less than or equal to a specified number. Returns rows where the field value is ≤ the specified value.

## Syntax

```yaml theme={null}
<numeric_field>:
  less_than_or_equal_to: <number>
```

## Properties

<ParamField type="string">
  The numeric field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The maximum value (inclusive). Returns rows where the field value is ≤ this number. Decimals are supported.
</ParamField>

## Examples

```yaml title="Total price is 100.00 or less" theme={null}
orders.total_price:
  less_than_or_equal_to: 100.00
```

```yaml title="Age is 66 or more" theme={null}
users.age:
  not_less_than_or_equal_to: 65
```


# month_of_year - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/month-of-year

Filters time fields by the month of the year.

Filters time fields by the month of the year. Returns rows where the date falls in the specified month.

## Syntax

```yaml theme={null}
<time_field>:
  month_of_year: "<month_name_or_number>"
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The month to filter for. The value can be either the full name of the month or a number:

  * `1` - `January`
  * `2` - `February`
  * `3` -  `March`
  * `4` -  `April`
  * `5` -  `May`
  * `6` -  `June`
  * `7` -  `July`
  * `8` -  `August`
  * `9` -  `September`
  * `10` -  `October`
  * `11` -  `November`
  * `12` -  `December`
</ParamField>

## Examples

```yaml title="Date is in January" theme={null}
users.created_at:
  month_of_year: "January"
```

```yaml title="Date is not in June" theme={null}
users.created_at:
  not_month_of_year: "6"
```


# not - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/not

Filters for inequality.

Filters for inequality. This operator applies to all filter types and matches rows where the field value does not equal the specified value. This is the negated form of [`is:`](/modeling/filters/operators/is).

## Syntax

```yaml theme={null}
<field_name>:
  not: <value>
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="string | number | date">
  The value to exclude. Type should correspond to the field type (string, number, or date).
</ParamField>

## Examples

```yaml title="Doesn't match inactive" theme={null}
users.status:
  not: inactive
```

```yaml title="Doesn't match 0" theme={null}
orders.quantity:
  not: 0
```

```yaml title="Doesn't match January 1, 2024" theme={null}
created_at:
  not: 2024-01-01
```


# on_or_after - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/on-or-after

Filters time fields for dates on or after a specified date.

Filters time fields for dates on or after a specified date. Returns rows where the date is greater than or equal to the specified date.

## Syntax

```yaml theme={null}
<time_field>:
  on_or_after: <date>
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string | date">
  The date threshold. Returns rows where the field value is greater than or equal to this date. Can be:

  * **Fixed date** - A fixed date in `YYYY-MM-DD` format. For example, `2024-01-01`
  * **Relative date** - A date relative to the current date. For example, `30 days ago`, `today`
</ParamField>

## Examples

```yaml title="Date is on or after January 1, 2024" theme={null}
users.created_at:
  on_or_after: 2024-01-01
```

```yaml title="Date is 30 days ago or less" theme={null}
orders.order_date:
  on_or_after: 30 days ago
```


# or - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/or

Creates a filter where at least one condition must be met.

Filters based on multiple conditions. Returns rows that meet at least one of the specified criteria.

<Tip>
  Want to create `or` conditions between multiple columns? Refer to the [Filtered measures guide](/modeling/measures) for an example.
</Tip>

## Syntax

```yaml theme={null}
<field_name>:
  or:
    - <filter_operator>: <value>
    - <filter_operator>: <value>
```

## Properties

<ParamField type="string">
  The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.
</ParamField>

<ParamField type="string">
  The `or` operator. Contains a list of conditions, of which at least one must be met to be included in results:

  <Expandable title="conditions">
    <ParamField type="string">
      A filter operator such as [`before`](/modeling/filters/operators/before), [`greater_than`](/modeling/filters/operators/greater-than), etc. and its corresponding value.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Matches dates between January 1-7 and February 1-7, 2025" theme={null}
users.created_at:
  or:
    - between_dates: [ 2025-01-01, 2025-01-07 ]
    - between_dates: [ 2025-02-01, 2025-02-07 ]
```

```yaml title="Matches California, empty, or null values" theme={null}
users.state:
  or:
    - is: California
    - is: ""              ## "is empty" in the UI
    - is: null            ## "is null" in the UI
```


# quarter_of_year - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/quarter-of-year

Filters time fields by the quarter of the year.

Filters time fields by the quarter of the year. Returns rows where the date falls within the specified quarter.

## Syntax

```yaml theme={null}
<time_field>:
  quarter_of_year: "<quarter_number>"
```

## Properties

<ParamField type="string">
  The time/date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="number">
  The quarter to filter for:

  * `1` for Q1
  * `2` for Q2
  * `3` for Q3
  * `4` for Q4
</ParamField>

## Examples

```yaml title="Date is in Q1" theme={null}
users.created_at:
  quarter_of_year: "1"
```

```yaml title="Date is not in Q2" theme={null}
revenue.booking_date:
  not_quarter_of_year: "2"
```


# sql_like - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/sql-like

Filters string fields using SQL LIKE pattern matching with wildcards.

Filters string fields using `SQL LIKE` pattern matching with wildcards. Returns rows where the field value matches the specified pattern using SQL LIKE syntax.

Can be used with [`case_insensitive`](/modeling/filters/operators/case-insensitive) to perform case-insensitive matching.

<Note>
  To create this filter in a workbook, use the **is like** operator.
</Note>

## Syntax

```yaml theme={null}
<string_field>:
  sql_like: <pattern>
```

## Properties

<ParamField type="object[]">
  The string field to filter on, specified in the format `view_name.field_name`.

  <Expandable title="string_field properties">
    <ParamField type="string">
      The pattern to match using SQL LIKE syntax. Use `%` to match any sequence of characters and `_` to match a single character.
    </ParamField>

    <ParamField type="boolean">
      When set to `true`, performs case-insensitive matching. Defaults to `false` (case-sensitive) if omitted.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Matches names containing both 'Adel' and 'Vargas' in that order" theme={null}
users.name:
  sql_like: '%Adel%Vargas%'
```

```yaml title="Matches products starting with 'prod' and ending with any 3 characters" theme={null}
products.sku:
  sql_like: 'prod___'
```

```yaml title="Matches email addresses from gmail.com (case-insensitive)" theme={null}
users.email:
  sql_like: '%@gmail.com'
  case_insensitive: true
```


# starts_with - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/starts-with

Filters string fields for values that start with a specified substring.

Filters string fields for values that start with a specified substring. Returns rows where the field value begins with the specified prefix.

Can be used with [`case_insensitive`](/modeling/filters/operators/case-insensitive) to perform case-insensitive matching.

## Syntax

```yaml theme={null}
<string_field>:
  starts_with: <prefix>
```

## Properties

<ParamField type="string">
  The string field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string">
  The prefix string to match. Returns rows where the field value begins with this substring.
</ParamField>

<ParamField type="boolean">
  When set to `true`, performs case-insensitive matching. Defaults to `false` (case-sensitive) if omitted.
</ParamField>

## Examples

```yaml title="Matches: blobby@blobsrus.com, blob.ross@blobross.com" theme={null}
users.email:
  starts_with: blob
```

```yaml title="Matches: BLOB-CAKE, BLOB-cookie, etc." theme={null}
products.name:
  starts_with: BLOB-
```

```yaml title="Matches: Blobby, blobinator, etc." theme={null}
customers.name:
  starts_with: Blob
  case_insensitive: true
```


# time_for_duration - Filter operators
Source: https://docs.omni.co/modeling/filters/operators/time-for-duration

Filters time fields for a specific duration starting from a given point in time.

Filters time fields for a specific duration starting from a given point in time. This filter is useful for filtering over various time periods using either relative time (e.g., `"28 days ago"`) or fixed dates (e.g., `"2024-06-01"`).

## Syntax

```yaml theme={null}
<time_field>:
  time_for_duration: [ <start_time>, <duration> ]
```

## Properties

<ParamField type="string">
  The time or date field to filter on, specified in the format `view_name.field_name`.
</ParamField>

<ParamField type="string[]">
  An array with two elements: `[starting_time, unit_of_time_length]`.

  * `start_time` - The starting time for the duration. Can be:

    * **Relative time:** `28 days ago`, `7 complete weeks ago`
    * **Fixed date:** `2024-06-01`

  * `duration` - The length of time after the starting point. For example, `30 days`, `1 year`, `7 days`
</ParamField>

## Examples

```yaml title="From June 1 - 30, 2024" theme={null}
orders.created_date:
  time_for_duration: [ 2024-06-01, 30 days ]
```

```yaml title="Any time in 2024 except June 1 - 30" theme={null}
orders.created_date:
  not_time_for_duration: [ 2024-06-01, 30 days ]
```


# Modeling in Omni
Source: https://docs.omni.co/modeling/index

Understand Omni's three-layer modeling approach: schema model, shared data model, and workbook model for governed analytics.

1. A schema model that mirrors the database
2. A shared, virtualized data model for global business metrics and definitions
3. A workbook model for ad hoc analysis that extends the core data models

As metrics are refined, they can be promoted from a workbook into your organization's shared model, and, eventually into the database schema beneath Omni.

## Core philosophies

The Omni data model is composed of layers. The schema model reflects the raw database, with subsequent layers above. The shared model represents the universal, governed data model that each new workbook is based on. Finally the workbook model extends the schema model and shared model. This is a simple way to think about modeling in Omni:

<img alt="" />

Even **branches** in Omni act as another layer on the model, right between the **shared** and **workbook** models, created when you enter branch mode.

When developing a data model in Omni, it's often best to start by modeling in the workbook or in a branch. Joins and fields can then be promoted to the shared model for consumption by all workbooks.

## Model structure

See docs on [schema model](/modeling/develop/model-generation) and [shared model](/modeling/develop/model-generation#model-extension). If the schema looks out of sync with the database, simply refresh the schema in the UI.

## Validation

Omni models have strong validation. Errors in YAML syntax or property names are rejected without being saved. This will be softened over time and the UX will be improved, but be aware that invalid code may be rejected on save in the data model.

Field typing is implicit in Omni based upon the dialect and functions applied. To change types, simply cast fields in SQL.

When the schema model is updated, breakage can occur in layers above. The model IDE will provide pointers to broken field references to resolve any issues, for example when columns are deleted beneath Omni.

<img alt="" />


# Measures
Source: https://docs.omni.co/modeling/measures/index

Define measures in your Omni model to compute sums, counts, averages, and custom aggregations across rows of data in queries.

While [dimensions](/modeling/dimensions) represent attributes of individual rows, measures compute values across rows — sums, counts, averages, and other aggregations. Measures can aggregate dimensions directly (like `sum of revenue`) or transform other measures (like `sum of profit / count of users`).

## Naming measures

Measure names must be unique within a view. Names may use characters a-z (no capital letters), 0-9, or underscores, and must start with a letter.

Additional [parameters](/modeling/measures/parameters) are nested under the measure with one tab (two spaces) of indentation:

```yaml highlight={2} theme={null}
measures:
  total_revenue:                   # the name of the field/measure
    sql: ${orders.sale_price}
    aggregate_type: sum
    format: usdcurrency
```

## Defining measures

You can define measures in two ways: using the [`aggregate_type`](/modeling/measures/parameters/aggregate-type) parameter for standard aggregations, or writing a raw SQL aggregate in the [`sql`](/modeling/measures/parameters/sql) parameter.

```yaml title="Using aggregate_type" theme={null}
total_revenue:
  sql: ${orders.sale_price}
  aggregate_type: sum
```

```yaml title="Using raw SQL" theme={null}
average_revenue:
  sql: AVG(${orders.sale_price})
```

Using `aggregate_type` is recommended when a standard aggregation fits your use case, as Omni can apply additional optimizations like [symmetric aggregation](/analyze-explore/sql/symmetric-aggregates) to protect against join fanout.

Refer to the [`aggregate_type`](/modeling/measures/parameters/aggregate-type) parameter documentation for a list of supported aggregates.

<Tip>
  **Don't see an aggregate you need?** Use the [`sql`](/modeling/measures/parameters/sql) parameter to define the aggregate directly.
</Tip>

## Filtered measures

You can apply [filters](/modeling/measures/parameters/filters) to a measure to create conditional aggregations. Filtered measures aggregate only the rows that match the specified filter conditions:

```yaml theme={null}
count_california_seniors:
  aggregate_type: count
  filters:
    age:
      greater_than_or_equal_to: 65
    state:
      is: California
```

## Measures referencing other measures

Measures can reference other measures to create compound metrics. When a measure references another measure, the referenced measure is computed first, and the result is used in the outer calculation:

```yaml theme={null}
total_revenue:
  sql: ${orders.sale_price}
  aggregate_type: sum

order_count:
  aggregate_type: count

revenue_per_order:
  sql: ${total_revenue} / NULLIF(${order_count}, 0)
```

## Semi-additive measures with omni\_dimensionalize

Semi-additive measures are aggregations that can be summed across some dimensions but not all.

Consider an end-of-day bank account balance. Summing this value across all days would produce an inaccurate number, since the balance represents a running total rather than an incremental change. To handle this, you need a way to pick the correct balance (for example, the most recent one) within each grouping, and then aggregate across other dimensions like account type.

In Omni, you can build semi-additive measures using the `omni_dimensionalize` function. This function converts a measure into a dimension within the query's grouping context, which you can then use for filtering:

```yaml theme={null}
dimensions:
  last_date:
    hidden: true
    sql: omni_dimensionalize(max(${created_at}))
  is_last_date:
    hidden: true
    sql: ${created_at[date]}=${last_date[date]}

measures:
  semi_additive_sum:
    sql: ${sale_price}
    aggregate_type: sum
    filters:
      is_last_date:
        is: true
```

From this, you can build a filtered measure that includes the boolean field as a filter.


# aggregate_type - Measures
Source: https://docs.omni.co/modeling/measures/parameters/aggregate-type

Defines the aggregation method for an underlying dimension.

<Tip>
  **Don't see an aggregate you want**? Use [SQL](/modeling/measures/parameters/sql) to define the aggregate instead, for example: `sql: MEDIAN(${orders.price})`
</Tip>

## Syntax

```yaml theme={null}
<measure_name>:
  sql: ${<view_name>.<field_name>}
  aggregate_type: <aggregation_method>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      The SQL used to create the measure. Specify fields as `view_name.field_name`.
    </ParamField>

    <ParamField type="string">
      The aggregation method to apply to the measure. Must be one of:

      | Aggregate type           | Description                                                                                                                                      |
      | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
      | `sum`                    | Sum of values                                                                                                                                    |
      | `count`                  | Count of rows                                                                                                                                    |
      | `count_distinct`         | Count of distinct values                                                                                                                         |
      | `average`                | Average of values                                                                                                                                |
      | `min`                    | Minimum value                                                                                                                                    |
      | `max`                    | Maximum value                                                                                                                                    |
      | `median`                 | Median value                                                                                                                                     |
      | `list`                   | Concatenated list of values                                                                                                                      |
      | `percentile`             | Percentile calculation. Requires an additional `percentile` parameter on the measure. Refer to the [Examples](#examples) section for an example. |
      | `sum_distinct_on`        | Sum with deduplication on a custom key. Requires [`custom_primary_key_sql`](/modeling/measures/parameters/custom-primary-key-sql).               |
      | `average_distinct_on`    | Average with deduplication on a custom key                                                                                                       |
      | `median_distinct_on`     | Median with deduplication on a custom key                                                                                                        |
      | `percentile_distinct_on` | Percentile with deduplication on a custom key                                                                                                    |
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Sum aggregation" theme={null}
total_revenue:
  sql: ${orders.sales_price}
  aggregate_type: sum
```

```yaml title="Measure with division" theme={null}
revenue_per_order:
  sql: ${orders.total_revenue} / ${orders.count}
```

```yaml title="Percentile aggregation" theme={null}
perc_75_age:
  sql: ${users.age}
  aggregate_type: percentile
  percentile: 75
```

```yaml title="Sum distinct on" theme={null}
sum_distinct_example:
  sql: price
  aggregate_type: sum_distinct_on
  custom_primary_key_sql: ${id}
```


# ai_context - Measures
Source: https://docs.omni.co/modeling/measures/parameters/ai-context

Free text that can provide context about a measure to the Omni Agent.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<measure_name>:
  ai_context: "<context_text>"
```

Or for multiline context:

```yaml theme={null}
<measure_name>:
  ai_context: |
    <multiline_context_text>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      Free text that provides context to the Omni Agent. Can include behavioral prompting, use case descriptions, or other contextual information to improve AI query results.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
product_cost:
  ai_context: |
    Include this field when asked about product prices.
```


# aliases - Measures
Source: https://docs.omni.co/modeling/measures/parameters/aliases

Create aliases for renamed measures to prevent existing Omni content from breaking when field names change in the data model.

Creates an alias for a measure, allowing you to ensure Omni content that uses the field doesn't break when the field is renamed.

## Syntax

```yaml theme={null}
<field_name>:
  aliases: [OLD_FIELD_NAME]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="array">
      An array of old field names that should map to the measure.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

In this example, the `sale_price` field was renamed to `order_price`. Adding `aliases` to the field allows references to `sale_price` to continue working:

```yaml theme={null}
order_price:
  aliases: [sale_price]
```


# all_values - Measures
Source: https://docs.omni.co/modeling/measures/parameters/all-values

Provides the complete list of possible values to the Omni Agent for measures with a fixed set of values.

This helps the [Omni Agent](/ai/chat) understand the full range of options available for a field.

Use this parameter for measures with a limited, well-defined set of values such as rating scores or categorical aggregations.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<measure_name>:
  all_values: [<value_1>, <value_2>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string[]">
      A complete list of all possible values for the measure. Best suited for measures with a fixed, enumerated set of values.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Rating scale" theme={null}
rating_score:
  all_values: [1, 2, 3, 4, 5]
```

```yaml title="Satisfaction levels" theme={null}
satisfaction_level:
  all_values: [very_dissatisfied, dissatisfied, neutral, satisfied, very_satisfied]
```


# colors - Measures
Source: https://docs.omni.co/modeling/measures/parameters/colors

Maps a color to the measure when used as a series in a visualization.

This allows you to maintain consistent coloring for the measure across visualizations.

<Tip>
  You can also model colors for [dimensions](/modeling/dimensions/parameters/colors)!
</Tip>

## Syntax

```yaml theme={null}
<measure_name>:
  colors:
    series: <color>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="object">
      Contains color configuration for the measure.

      <Expandable title="measure_name properties">
        <ParamField type="string">
          The color to be used in visualizations when the measure is used as a series. Can be specified using any legal [CSS method](https://www.w3schools.com/cssref/css_colors_legal.php).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Named color" theme={null}
first_order_date:
  colors:
    series: green
```

```yaml title="RGB color" theme={null}
first_order_date:
  colors:
    series: rgb(0, 0, 255)
```

```yaml title="RGBA with opacity" theme={null}
first_order_date:
  colors:
    series: rgba(0, 0, 255, 0.3)
```

```yaml title="HSL color" theme={null}
first_order_date:
  colors:
    series: hsl(120, 100%, 50%)
```

```yaml title="Hex color (must be quoted)" theme={null}
first_order_date:
  colors:
    series: "#000000"
```


# custom_primary_key_sql - Measures
Source: https://docs.omni.co/modeling/measures/parameters/custom-primary-key-sql

Defines a custom aggregation level for deduplication.

This is used to dedupe over a different aggregation level than the default behavior. For example, aggregation over an intermediate table or another key. This can be used for similar use cases to [level-of-detail calculation](/modeling/dimensions/parameters/level-of-detail).

## Syntax

```yaml theme={null}
<measure_name>:
  sql: <field>
  aggregate_type: sum_distinct_on
  custom_primary_key_sql: ${<view_name>.<field_name>}
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      The type of aggregation to apply. Must be one of:

      * `sum_distinct_on`
      * `average_distinct_on`
      * `percentile_distinct_on`
      * `median_distinct_on`

      Refer to the [`aggregate_type` reference](/modeling/measures/parameters/aggregate-type) for more information about this parameter.
    </ParamField>

    <ParamField type="string">
      A field reference that defines the key to use for deduplication, specified using `${}` syntax.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
distinct_price:
  sql: price
  aggregate_type: sum_distinct_on
  custom_primary_key_sql: ${id_from_other_table}
```

<Tip>
  The combination of a **Custom Primary Key** and these specific aggregate types is best used in scenarios where you are aggregating a field based off of the primary key in another table.
</Tip>


# description - Measures
Source: https://docs.omni.co/modeling/measures/parameters/description

Provides metadata about the measure, made available in the workbook UI.

## Syntax

```yaml theme={null}
<measure_name>:
  description: <description_text>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      A text description of the measure. Use unquoted text.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
net_orders:
  description: Net orders placed, calculated as total_orders - returned_orders
```


# display_order - Measures
Source: https://docs.omni.co/modeling/measures/parameters/display-order

Overrides the sort order for the field picker within the field's grouping.

By default, measures are sorted alphabetically. Defining a `display_order` will override this default.

For fields inside groups using [`group_label`](/modeling/measures/parameters/group-label), the group will be ranked with the `min` of all the fields in the group. For example, if there are 3 fields with `display_order` of `4`, `5` and `{empty}`, the group will have a `display_order` of 4).

This parameter does not move measures above dimensions in the field picker.

## Syntax

```yaml theme={null}
<measure_name>:
  display_order: <number>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="number">
      A whole number that determines the measure's position in the field picker within its view.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
count:
  aggregate_type: count
  display_order: 1
```


# drill_fields - Measures
Source: https://docs.omni.co/modeling/measures/parameters/drill-fields

Curates the drilling behavior for a measure.

Drill fields allow for curation of the drilling behavior for a given measure, using an array of fields for the subsequent query. Fields can be specified using individual field names, tags, or [field sets](/modeling/models/sets).

Setting this parameter with an empty value (`drill_fields: []`) removes the drill from the measure. You can also remove drilling in workbooks by hovering over a field in the field picker, clicking <Icon icon="ellipsis-vertical" />, and selecting **Edit**.

When you drill into a measure, Omni removes any measure-based filters from the dashboard or workbook. Drill queries return underlying rows, so the aggregated value you filtered on (for example, `“revenue > 10K”`) often becomes much smaller at the row level — which can make the drill table look empty or incorrect.

To avoid this, Omni automatically converts measure filters into query-level filters during a drill. This preserves the logic of the filter, but applies it to the detailed data rather than the aggregated measure.

## Syntax

```yaml theme={null}
<measure_name>:
  drill_fields: [<view>.<field>, <view>.<field>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="array">
      An array of field names, tags (using `tag:tag_name`), or [field sets](/modeling/models/sets) (using `set:set_name`). Date fields must be quoted.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Drill with specific fields" theme={null}
count:
  drill_fields:
    [
      users.id,
      users.full_name,
      users.email,
      users.age,
      users.state,
      users.country,
      "users.created_at[date]"
    ]
  aggregate_type: count
```

```yaml title="Drill with tag" theme={null}
other_count:
  drill_fields: [tag:my_tag]
  aggregate_type: count
```

```yaml title="Drill with field set" theme={null}
count_that_uses_field_sets:
  aggregate_type: count
  drill_fields: [ set:revenue ]
```

```yaml title="Remove drill" theme={null}
count:
  drill_fields: []
  aggregate_type: count
```


# drill_queries - Measures
Source: https://docs.omni.co/modeling/measures/parameters/drill-queries

Defines multiple drill query options, with full control over the underlying query.

<Note>
  If a measure has `drill_queries` and `drill_fields` defined, `drill_queries` will override `drill_fields`.
</Note>

Drill queries appear as options when you click to drill on a measure in a document. Providing drill queries is more flexible than a [`drill_fields`](/modeling/measures/parameters/drill-fields) set, as they allow you to specify the underlying query to drill. This includes changes such as limits, sorts, filters, and base views.

Filters specified in a drill query are additive, meaning they will be applied in addition to any filters from the main query and the associated dimension values of the cell being drilled.

If you want to reference fields from multiple views, ensure that a relationship exists between your base view and the other referenced views so that your drill down will render as expected. To get the structure + syntax of a query, build a query in a workbook and open up the [inspector](/analyze-explore/workbook-inspector) and scroll down to the "Query Structure" settings.

## Syntax

```yaml theme={null}
<measure_name>:
  drill_queries:
    <Drill Query Label>:
      fields: [<field1>, <field2>, ...]
      base_view: <view_name>
      filters: {...}
      sorts: [...]
      limit: <number>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="object">
      An object containing one or more drill query definitions, each with a human-readable label as the key.

      <Expandable title="drill_queries properties">
        <ParamField type="object[]">
          An object containing a drill query definition. Underscores are not required for drill query labels.

          <Expandable title="Drill Query Label properties">
            <ParamField type="string[]">
              An array of field names to include in the drill query.
            </ParamField>

            <ParamField type="string">
              The table that will act as the `FROM` clause of the query.
            </ParamField>

            <ParamField type="object">
              Optional filters to apply to the drill query using [filter syntax](/modeling/filters).
            </ParamField>

            <ParamField type="string[]">
              Optional sort specifications. **Note**: Full scoping for fields is required.
            </ParamField>

            <ParamField type="number">
              Optional row limit for the drill query.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Multiple drill options" theme={null}
my_fun_measure:
  sql: ${field_we_aggregate}
  aggregate_type: sum
  drill_queries:
    First Drill for Top 10:
      fields:
        [
        field_1,
        field_2
        ]
      base_view: view_name_1
      filters:
        is_top_10:
          is: true
      sorts:
        - field: view_name_1.field_1
        - field: view_name_1.field_2
          desc: true
    Customer Details:
      fields:
        [
        customer_name,
        customer_email,
        registration_date
        ]
      base_view: customers
      limit: 20
      sorts:
        - field: customers.registration_date
          desc: true
```


# filters - Measures
Source: https://docs.omni.co/modeling/measures/parameters/filters

Applies filters to a measure for filtered aggregations.

Filtered measures can be built using aggregation alongside a dimension filter. When building measures in the UI, filters may only be available for standard measures and quick-aggregates. For measures built with custom SQL logic, best practice is to define filters in the YAML definition.

See full page on filter syntax [here](/modeling/filters).

## Syntax

```yaml theme={null}
<measure_name>:
  aggregate_type: <type>
  filters:
    <field_name>:
      <filter_condition>: <value>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="object">
      A mapping of field names to their filter conditions using [filter syntax](/modeling/filters). Multiple filters can be added, and multiple values for a given filter can be added using array syntax.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Count with multiple filters" theme={null}
count_california_seniors:
  aggregate_type: count
  filters:
    age:
      greater_than_or_equal_to: 65
    state:
      is: California
```

```yaml title="Filter with array values" theme={null}
count_ny_or_nj:
  aggregate_type: count
  filters:
    state:
      is: [New York, New Jersey]
```

```yaml title="Filter using modeled boolean field" theme={null}
### note filtered measures can point to raw columns or modeled fields
dimensions:
  is_big:
    sql: ${employee_count} > 100000
measures:
  count_large:
    aggregate_type: count
    filters:
      is_big:
        is: true
```

```yaml title="Complex logic with boolean dimension" theme={null}
complex_dimension_example:
  sql: ${state} = 'California' OR ${age} > 65
count_complex_logic:
  aggregate_type: count
  filters:
    complex_dimension_example:
      is: true
```

```yaml title="Filter by query (top 10 users)" theme={null}
count_top_10_users:
  format: NUMBER
  aggregate_type: count
  filters:
    id:
      field_name_in_query: order_items.user_id
      query_structure:
        fields: [ order_items.user_id, order_items.sale_price_sum ]
        base_view: order_items
        limit: 10
        sorts:
          - field: order_items.sale_price_sum
            desc: true
        topic: order_items
```


# format - Measures
Source: https://docs.omni.co/modeling/measures/parameters/format

Sets default formatting for measures—named formats, Excel-style strings, conditional formats, model constants, and Markdown table cells.

The `format` parameter sets the default display format for a 's values. s can use one of Omni's [named formats](/modeling/models/format-values#named-formats), an [Excel-style string](/modeling/models/format-values#excel-style-strings), a [Mustache template](/modeling/models/format-values#mustache-templates), or a [conditional format](/modeling/models/format-values#conditional-formats) that selects a format dynamically.

Formats can also be set on a per-query basis from visualization configuration, using the same format types.

See [Formatting values](/modeling/models/format-values) for more information on format types and examples.

<Note>
  Formats are applied **after** the SQL runs, so they do not impact grouping. To handle grouping with truncation, use `ROUND()` or `FLOOR()`.
</Note>

## Syntax

`format` accepts either a string or a conditional object:

<Tabs>
  <Tab title="String">
    ```yaml theme={null}
    <dimension_or_measure_name>:
      format: <format_string>
    ```
  </Tab>

  <Tab title="Conditional">
    ```yaml theme={null}
    <dimension_or_measure_name>:
      format:
        depends_on:
          field: <field_name>
          conditions:
            - condition:
                <filter_expression>
              value: <format_string>
        else: <fallback_format_string>
    ```
  </Tab>
</Tabs>

## Properties

Use the tabs to view the properties for string values and conditional objects.

<Tabs>
  <Tab title="String">
    <ParamField type="string">
      The format definition. This can be any valid [format type](/modeling/models/format-values#choosing-a-format-type):

      * A named format (e.g., `currency_2`, `percent_1`)
      * An Excel-style string (e.g., `'#,##0.00 "kg"'`)
      * A reference to a model-level [custom format](/modeling/models/custom-formats)

      See [Formatting values](/modeling/models/format-values) for the full reference on all format types, including named formats, Excel-style strings, conditional formats, model constants, locale settings, and more.
    </ParamField>
  </Tab>

  <Tab title="Conditional">
    <ParamField type="object">
      Defines the source value to evaluate conditions against. Set exactly one of `field`, `user_attribute`, or `filter`.

      These options resolve as follows:

      | Source           | Resolution timing         | Behavior                                                                                                         |
      | ---------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
      | `field`          | At display time (per row) | Evaluated against each row's value after query results are returned. Each row can resolve to a different format. |
      | `user_attribute` | At query preparation time | The user attribute value is evaluated once. The entire field uses the single resolved format.                    |
      | `filter`         | At query preparation time | The filter value is evaluated once. The entire field uses the single resolved format.                            |

      <Expandable title="depends_on properties">
        <ParamField type="string">
          The name of a field in the same view.
        </ParamField>

        <ParamField type="string">
          The reference of a [user attribute](/administration/users/attributes).
        </ParamField>

        <ParamField type="string">
          The name of a filter applied to the query.
        </ParamField>

        <ParamField type="object[]">
          An ordered list of condition entries. Each entry contains a `condition` using [Omni filter syntax](/modeling/filters) and a `value` specifying the format string to apply when the condition matches.

          <Expandable title="conditions properties">
            <ParamField type="object">
              An Omni filter expression. Supported condition types:

              | Condition                  | Description                    | Example                            |
              | -------------------------- | ------------------------------ | ---------------------------------- |
              | `is`                       | Exact match                    | `is: "USD"`                        |
              | `not`                      | Not equal                      | `not: "USD"`                       |
              | `greater_than`             | Greater than                   | `greater_than: "1000"`             |
              | `greater_than_or_equal_to` | Greater than or equal to       | `greater_than_or_equal_to: "1000"` |
              | `less_than`                | Less than                      | `less_than: "0"`                   |
              | `less_than_or_equal_to`    | Less than or equal to          | `less_than_or_equal_to: "100"`     |
              | `between`                  | Between two values (inclusive) | `between: [10, 100]`               |
              | `not_between`              | Outside a range                | `not_between: [10, 100]`           |
              | `starts_with`              | String starts with             | `starts_with: "US"`                |
              | `ends_with`                | String ends with               | `ends_with: "Corp"`                |
              | `contains`                 | String contains                | `contains: "special"`              |
              | `not_starts_with`          | String does not start with     | `not_starts_with: "US"`            |
              | `not_ends_with`            | String does not end with       | `not_ends_with: "Corp"`            |
              | `not_contains`             | String does not contain        | `not_contains: "special"`          |

              Additional conditions follow the same structure as [filters](/modeling/filters).
            </ParamField>

            <ParamField type="string">
              The format string to apply when the condition matches. Can be a named format or an Excel-style string.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Fallback format string used when no condition matches.
    </ParamField>
  </Tab>
</Tabs>

## Examples

```yaml title="Currency format" theme={null}
sale_price:
  format: currency_2
```

```yaml title="Big number format" theme={null}
revenue:
  format: big_2
```

```yaml title="Custom Excel-style format with units" theme={null}
avg_weight:
  sql: '"weight"'
  aggregate_type: avg
  format: '#,##0.00 "kg"'
```

```yaml title="Custom format reference" theme={null}
avg_margin:
  sql: '"margin"'
  aggregate_type: avg
  format: margin_bps
```

```yaml title="Conditional format" theme={null}
revenue:
  format:
    depends_on:
      field: orders.currency_code
      conditions:
        - condition:
            equals: USD
          value: usdcurrency_2
        - condition:
            equals: EUR
          value: eurcurrency_2
      else: currency_2
```


# group_label - Measures
Source: https://docs.omni.co/modeling/measures/parameters/group-label

Group related measures together under a label in the workbook field browser for cleaner organization and easier discovery.

## Limitations

**[Dimensions](/modeling/dimensions) and [measures](/modeling/measures) can't be grouped together.** Applying the same group label to a dimension and a measure will result in two groups displaying in the field browser, not one group with both fields.

## Syntax

```yaml theme={null}
<measure_name>:
  group_label: <group_name>
```

## Properties

<ParamField type="object[]">
  The name of the measure. Measure names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores
</ParamField>

<ParamField type="string">
  Unquoted text specifying the group under which the field should appear in the field browser. Use the greater-than symbol (`>`) with whitespace on either side to create nested group hierarchies. Refer to the [Organize fields with nested groups guide](/guides/modeling/nested-field-groups) for more information and examples.
</ParamField>

## Examples

```yaml title="Group order_count under Important Fields" theme={null}
order_count:
  group_label: Important Fields
```

**Group measures in a `support_tickets` view**

<Tabs>
  <Tab title="YAML">
    ```yaml theme={null}
    first_response_breach_by_day:
      group_label: SLA breaches > First response

    first_response_breach_by_month:
      group_label: SLA breaches > First response

    breach_resolution_by_day:
      group_label: SLA breaches > Resolution

    breach_resolution_by_month:
      group_label: SLA breaches > Resolution
    ```
  </Tab>

  <Tab title="Field browser result">
    ```markdown theme={null}
    ▾ SLA breaches
      ▾ First response
          first_response_breach_by_day
          first_response_breach_by_month
      ▾ Resolution
          breach_resolution_by_day
          breach_resolution_by_month
    ```
  </Tab>
</Tabs>


# hidden - Measures
Source: https://docs.omni.co/modeling/measures/parameters/hidden

Hide a measure from the workbook field browser while keeping it available for model references and derived calculations.

The field will still be referenceable in the model but hidden in the workbook UI.

## Syntax

```yaml theme={null}
<measure_name>:
  hidden: true
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="boolean">
      If `true`, the measure will be hidden.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
sum_excluded_revenue:
  hidden: true
```


# ignored - Measures
Source: https://docs.omni.co/modeling/measures/parameters/ignored

Removes the field from the UI and prevents references to the field.

<Note>
  Ignored fields will still be accessible through SQL.
</Note>

This parameter can be used to 'remove' fields from the raw database schema.

## Syntax

```yaml theme={null}
<measure_name>:
  ignored: true
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="boolean">
      When set to `true`, removes the field from the UI and prevents references. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
total_users:
  ignored: true
```


# Measure parameters
Source: https://docs.omni.co/modeling/measures/parameters/index

Reference for all measure YAML parameters in Omni, including aggregate type, SQL, format, filters, drill fields, and visibility.

| Parameter                                                                         | Description                                                                                              |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [aggregate\_type](/modeling/measures/parameters/aggregate-type)                   | Defines the aggregation method for an underlying dimension.                                              |
| [ai\_context](/modeling/measures/parameters/ai-context)                           | Free text that can provide context about a measure to the Omni Agent.                                    |
| [all\_values](/modeling/measures/parameters/all-values)                           | Provides the complete list of possible values to the Omni Agent for measures with a fixed set of values. |
| [aliases](/modeling/measures/parameters/aliases)                                  | Maps old field names to updated field names to preserve content.                                         |
| [colors](/modeling/measures/parameters/colors)                                    | Maps a color to the measure when it's used as a series in a visualization.                               |
| [custom\_primary\_key\_sql](/modeling/measures/parameters/custom-primary-key-sql) | Defines a custom aggregation level for deduplication.                                                    |
| [description](/modeling/measures/parameters/description)                          | Provides metadata about the measure, made available in the workbook UI.                                  |
| [display\_order](/modeling/measures/parameters/display-order)                     | Overrides the sort order for the field picker within the field's grouping.                               |
| [drill\_fields](/modeling/measures/parameters/drill-fields)                       | Curates the drilling behavior for a measure using an array of fields for the subsequent query.           |
| [drill\_queries](/modeling/measures/parameters/drill-queries)                     | Defines multiple drill query options with full control over the underlying query.                        |
| [filters](/modeling/measures/parameters/filters)                                  | Applies filters to a measure for filtered aggregations.                                                  |
| [format](/modeling/measures/parameters/format)                                    | Sets default or conditional formatting for numbers in Omni.                                              |
| [group\_label](/modeling/measures/parameters/group-label)                         | Nests a group of fields in the field picker for curated organization.                                    |
| [hidden](/modeling/measures/parameters/hidden)                                    | Removes the field from the UI while keeping it referenceable in the model.                               |
| [ignored](/modeling/measures/parameters/ignored)                                  | Removes the field from the UI and prevents references to the field.                                      |
| [label](/modeling/measures/parameters/label)                                      | Overrides the field name for all UI appearances of the field.                                            |
| [level\_of\_detail](/modeling/measures/parameters/level-of-detail)                | Creates a Level of Detail aggregation, controlling the granularity at which a measure is computed.       |
| [links](/modeling/measures/parameters/links)                                      | Adds external links to templated URLs in the drill menu.                                                 |
| [markdown](/modeling/measures/parameters/markdown)                                | Mustache template rendered as Markdown in data table columns.                                            |
| [required\_access\_grants](/modeling/measures/parameters/required-access-grants)  | Limits a user's ability to query a field based on assigned user attributes.                              |
| [required\_fields](/modeling/measures/parameters/required-fields)                 | Allows a measure to be used only when specified fields are included in the query.                        |
| [sample\_values](/modeling/measures/parameters/sample-values)                     | Provides sample values to the Omni Agent to better understand measure magnitude and usage.               |
| [sql](/modeling/measures/parameters/sql)                                          | The core declaration of the field definition.                                                            |
| [suggest\_from\_field](/modeling/measures/parameters/suggest-from-field)          | Suggests filter values from an alternative field's distinct values.                                      |
| [suggestion\_list](/modeling/measures/parameters/suggestion-list)                 | Explicitly sets the list of filter options, bypassing the default behavior.                              |
| [synonyms](/modeling/measures/parameters/synonyms)                                | Alternative names that help the Omni Agent match user queries to the correct field.                      |
| [tags](/modeling/measures/parameters/tags)                                        | Tags for field picker search and field curation.                                                         |
| [view\_label](/modeling/measures/parameters/view-label)                           | Nests a field under a different view than its default parent view.                                       |


# label - Measures
Source: https://docs.omni.co/modeling/measures/parameters/label

Overrides the field name for all UI appearances of the field.

## Syntax

```yaml theme={null}
<measure_name>:
  label: <display_name>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      Unquoted text that will be displayed in the UI instead of the field name.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
full_name:
  label: Full Name
```


# level_of_detail - Measures
Source: https://docs.omni.co/modeling/measures/parameters/level-of-detail

Creates a Level of Detail aggregation, controlling the granularity at which a measure is computed.

Level of Detail (LoD) fields control the granularity at which an aggregation is computed. When used as a measure, an LoD produces an aggregation of an aggregation, such as an average of averages or a percent of total.

<Tip>
  You can also create LoD fields in the workbook! See [Creating level of detail fields](/analyze-explore/custom-fields/level-of-detail) for more information.
</Tip>

## How it works

The easiest way to understand an LoD measure is to read it as SQL. For example, this `avg_customer_lifetime_spend` LoD first sums each customer's order amounts, then averages those per-customer totals at whatever grain the query is run. In this example, that's by `country`:

<CodeGroup>
  ```yaml Model theme={null}
  avg_customer_lifetime_spend:  
    sql: ${orders.amount}  
    aggregate_type: average  
    level_of_detail:  
      aggregate_type: sum  
      fixed: [customers.id]
  ```

  ```sql SQL equivalent theme={null}
  SELECT customers.country AS "country",  
         AVG(lod.customer_total) AS "avg_customer_lifetime_spend"
  FROM customers
  INNER JOIN (  
      SELECT customer_id,
             SUM(amount) AS customer_total  
        FROM orders  
    GROUP BY customer_id  
  ) lod ON customers.id = lod.customer_id  
  GROUP BY customers.country  
  ```
</CodeGroup>

The `level_of_detail` block defines the inner query: `fixed: [customers.id]` with `aggregate_type: sum` produces one summed row per customer — that's the first aggregation. The measure's `aggregate_type: average` then takes those per-customer totals and averages them at the query's grain. That's the "aggregation of an aggregation" shape: a per-customer `SUM` feeding into a per-country `AVG`.

Note that the outer `GROUP BY customers.country` clause comes from the dimensions selected in the query, not the LoD definition itself.

## Syntax

```yaml theme={null}
<measure_name>:
  aggregate_type: <aggregation>
  level_of_detail:
    aggregate_type: <aggregation>
    <grouping_strategy>: [<field_name>]
    custom_primary_key_sql: <field_reference>
    cancel_query_filters: <true_false>
    filters:
      <field>:
        <filter_operator>: <value>
        cancel_query_filter: <true_false>
```

## Properties

<ParamField type="object">
  The name of the measure. Measure names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="measure_name properties">
    <ParamField type="object">
      Configures the level of detail calculation for this measure.

      <Expandable title="level_of_detail properties">
        <ParamField type="string">
          The type of aggregation to apply. Supports standard aggregations like `sum`, `average`, `count`, `min`, `max`, and distinct-on aggregations.

          **When the following aggregations are used**, the `custom_primary_key_sql` parameter is required:

          * `sum_distinct_on`
          * `average_distinct_on`
          * `median_distinct_on`
          * `percentile_distinct_on`
        </ParamField>

        <ParamField type="string">
          The grouping strategy and the field to use to apply it, specified as `grouping_strategy: [ field_name ]`. Refer to the [Examples](#examples) section to see an example with complete syntax.

          The grouping strategy must be one of the following:

          * `always_include` - Adds specified dimensions to the query's grouping, forcing a finer level of detail
          * `always_exclude` - Removes specified dimensions from the grouping, producing a coarser aggregation
          * `fixed` - Defines an absolute level of detail, replacing all query groupings
        </ParamField>

        <ParamField type="string">
          A field reference that defines the key to use for deduplication when using `*_distinct_on` aggregate types, specified using `${}` syntax. This allows you to aggregate over a different level than the view's primary key, such as summing amounts by order ID when your view is at the order items level.

          **This parameter is required** when the following `aggregate_type`s are used:

          * `sum_distinct_on`
          * `average_distinct_on`
          * `median_distinct_on`
          * `percentile_distinct_on`
        </ParamField>

        <ParamField type="boolean">
          When `true`, ignores any row filters applied in the outer query when computing the level of detail metric. Defaults to `false`.

          To selectively ignore specific filters while keeping others, use the `filters` parameter with [`cancel_query_filter`](/modeling/filters/operators/cancel-query-filter) instead.
        </ParamField>

        <ParamField type="object">
          Applies filters to the level of detail calculation. See the [Filters documentation](/modeling/filters) for more information on Omni filter syntax.

          You can use [`cancel_query_filter: true`](/modeling/filters/operators/cancel-query-filter) within a filter to selectively ignore specific global filters for this level of detail only, while keeping other global filters active. This provides granular control compared to [`cancel_query_filters`](#param-cancel-query-filters), which ignores all global filters.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Customer lifetime revenue" theme={null}
measures:
  customer_lifetime_revenue:
    aggregate_type: sum
    sql: ${order_items.sale_price}
    level_of_detail:
      aggregate_type: sum
      always_include: [users.user_id]
      cancel_query_filters: true
```

```yaml title="Fixed level of detail" theme={null}
measures:
  category_total_revenue:
    aggregate_type: sum
    sql: ${order_items.revenue}
    level_of_detail:
      aggregate_type: sum
      fixed: [products.category]
```

```yaml title="Exclude dimensions from grouping" theme={null}
measures:
  overall_average_score:
    aggregate_type: average
    sql: ${reviews.score}
    level_of_detail:
      aggregate_type: average
      always_exclude: [stores.region]
```

```yaml title="Sum distinct on with custom primary key" theme={null}
measures:
  total_by_order:
    aggregate_type: sum
    sql: ${order_items.amount}
    level_of_detail:
      aggregate_type: sum_distinct_on
      custom_primary_key_sql: ${order_items.order_id}
      fixed: []
```

```yaml title="Selectively ignore a specific global filter" theme={null}
measures:
  arr_balance:
    aggregate_type: sum
    sql: ${accounts.arr_cumulative}
    level_of_detail:
      aggregate_type: max
      fixed: [accounts.logo, orders.date]
      filters:
        orders.date:
          is: ""
          cancel_query_filter: true  # Ignores global date filter for this level of detail only
```

```yaml title="Replace a cancelled filter with a different value" theme={null}
measures:
  california_revenue:
    aggregate_type: sum
    sql: ${order_items.revenue}
    level_of_detail:
      aggregate_type: sum
      fixed: [stores.state]
      filters:
        stores.state:
          is: California  # Replaces any global state filter with California
          cancel_query_filter: true
```

```yaml title="Compare with cancel_query_filters (all-or-nothing)" theme={null}
measures:
  total_lifetime_value:
    aggregate_type: sum
    sql: ${order_items.sale_price}
    level_of_detail:
      aggregate_type: sum
      always_include: [users.user_id]
      cancel_query_filters: true  # Ignores all global filters
```


# links - Measures
Source: https://docs.omni.co/modeling/measures/parameters/links

Add templated URL links to measure drill menus, enabling cross-linking to external tools and dashboards from aggregated results.

Fields referenced in links are implicitly added to the query, but not shown in the result data unless explicitly included.

**Note**: Avoid referencing a dimension with more than one value for a given value of the dimension on which the link is defined, as it can impact aggregations and seemingly create duplicate rows.

## Syntax

```yaml theme={null}
<measure_name>:
  links:
    - url: <url_template>
      label: <link_label>
      icon_url: <optional_icon_url>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="object[]">
      An array of link objects, each containing `url`, `label`, and optionally `icon_url`.

      <Expandable title="links properties">
        <ParamField type="string">
          The URL template, with field references using `${}` syntax.
        </ParamField>

        <ParamField type="string">
          The display text for the link.
        </ParamField>

        <ParamField type="string">
          Optional URL to an image, which will display as an icon with the link.
        </ParamField>

        <ParamField type="string">
          Controls whether the link opens in the same tab or a new tab. Accepts `self` (same tab) or `blank` (new tab). Useful for tabbed dashboards where you want navigation to stay within the current tab.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Google search link" theme={null}
country:
  links:
    - url: https://www.google.com/search?q=${users.country}
      label: Google
```

<Tip>
  To inject the corresponding field into the filter URL structure, navigate to a filtered dashboard in your browser and then swap in the parameterized (dynamic) URL.
</Tip>

```yaml title="Dashboard crosslink with icon" theme={null}
id:
  sql: '"ID"'
  format: ID
  links:
    # Works just for string filters
    - url: https://sandbox.omniapp.co/dashboards/KWsNP1WK?f--omni_dbt_ecomm__order_items.user_id={"values":["${omni_dbt_ecomm__users.id}"]}
      label: User Lookup Dashboard
      icon_url: https://avatars.githubusercontent.com/u/100505341?s=200&v=4
    # For all types of filters use the encoded URL
    - url: https://sandbox.omniapp.co/dashboards/YX-irW2S/user+lookup?f--ecomm__users.id=%7B"values"%3A%5B"${ecomm__users.id}"%5D%7D
      label: User Lookup Dashboard
      icon_url: https://avatars.githubusercontent.com/u/100505341?s=200&v=4
```

```yaml title="Tabbed dashboard with target" theme={null}
# Link opens in same tab, useful for drill-down patterns
match_name:
  links:
    - url: /dashboards/match_deep_dive?filter=${match_id}
      label: Match deep dive
      target: self
    - url: https://www.example.com/${match_id}
      label: External
      target: blank
```


# markdown - Measures
Source: https://docs.omni.co/modeling/measures/parameters/markdown

Mustache template that renders measure values as Markdown in data table columns.

Renders measure values as Markdown in data table columns using Mustache.

The `markdown` parameter is not a [`format`](/modeling/measures/parameters/format) value. Use it when you want a [table visualization][table-vis] to render a column as Markdown (for example bold text, links, or images) using a [Mustache](/visualize-present/mustache-reference) template filled with each row's values.

* **`format`** controls standard number, currency, and percentage display for the measure.
* **`markdown`** renders a Mustache template as formatted text (bold, links, images) in **table** cells.

## Syntax

```yaml theme={null}
<measure_name>:
  markdown: "<mustache_template>"
```

## Properties

<ParamField type="object">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      A Mustache template string. The rendered output displays as Markdown in table visualization columns.
    </ParamField>
  </Expandable>
</ParamField>

## Behavior

* When you add a  with `markdown` to a query and use a table chart, Omni merges the template into the column's display settings so cells render as Markdown by default. In the table visualization's **Display** tab, you can customize the Markdown template and CSS, then use the **Promote** button to save those changes to the workbook model.
* Mustache can reference `.value`, `.raw`, and `.value_url_encoded` values for the current field and other fields in the row. Must be specified with `<view_name>.<field_name>` syntax, e.g., `{{view_name.field_name.property}}`.
* Referenced fields are included in the query automatically when needed.

For how `format` and `markdown` interact, see the [Formatting values guide](/modeling/models/format-values#formats-with-markdown).

<Note>
  Dashboard text tiles and standalone Markdown chart types are separate from field `markdown`, which applies to workbook data tables for modeled fields.
</Note>

## Examples

### Label the aggregated value

```yaml title="ecomm__orders.view" theme={null}
measures:
  order_count:
    sql: '"order_id"'
    aggregate_type: count_distinct
    markdown: "**{{ecomm__orders.order_count}}** orders"
```

### Link with encoded query parameter

```yaml title="orders.view" theme={null}
measures:
  sale_price:
    sql: '"price"'
    aggregate_type: sum
    markdown: "[{{orders.sale_price.value}}](https://example.com/explain?q={{orders.price.value_url_encoded}})"
```

[table-vis]: /visualize-present/visualizations/types/table


# required_access_grants - Measures
Source: https://docs.omni.co/modeling/measures/parameters/required-access-grants

Defines a list of access grants for the measure, which are used to control access.

Defines a list of access grants for the measure, which are used to control access. The values of this parameter must match the name of an access grant in the model file's [`access_grants`](/modeling/models/access-grants) parameter.

Refer to the [Controlling data access guide](/modeling/develop/data-access-control) for more information and examples.

You can also conditionally allow access by using pipes (`|`) and ampersands (`&`) to create `OR` and `AND` conditions.

## Syntax

```yaml theme={null}
<measure_name>:
  required_access_grants: [<grants_and_conditions>]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string[]">
      An array of access grant names that control access to the measure. Each value must match an access grant defined in the model file. Use `|` for `OR` conditions and `&` for `AND` conditions within the same array element.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Define one required access grant" theme={null}
total_budget:
  required_access_grants: [marketing]
```

```yaml title="Grant access if conditions are met for either access grant" theme={null}
total_budget:
  required_access_grants: [marketing|sales]
```

```yaml title="Grant access if conditions are met for marketing OR sales AND product" theme={null}
total_budget:
  required_access_grants: [marketing|sales&product]
```


# required_fields - Measures
Source: https://docs.omni.co/modeling/measures/parameters/required-fields

Specifies fields that must be present whenever the measure is used in a query.

Specifies fields that must be present whenever the measure is used in a query. Useful for measures that should never aggregate across a dimension (e.g. an amount that must be grouped or filtered by currency).

When a measure with `required_fields` is added to a query, the required fields will be automatically added to the query. Required fields must be selected, pivoted, or filtered to a single value with exact equality filter or the query will error. See [Filter requirements](#filter-requirements) for more information.

If any required fields are missing, the query will error.

## Syntax

```yaml theme={null}
<measure_name>:
  required_fields: [<view>.<field>, <view>.<field>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="array">
      An array of individual field references, specified as `<view>.<field>`.

      <Warning>
        Tags and field sets are not supported for this parameter.
      </Warning>
    </ParamField>
  </Expandable>
</ParamField>

## Filter requirements

Only exact single-value equality filters satisfy the required field constraint. The filter must pin the field to one specific value — this is treated as equivalent to grouping by that field.

Only string and numeric equality filters are supported (e.g., `currency = 'USD'` or `level = 5`).

Filters that do **not** satisfy the requirement:

* Multi-value filters (e.g., `currency IN ('USD', 'EUR')`)
* Negated filters (e.g., `currency != 'USD'`)
* Range filters (e.g., `amount > 100`)

<Note>
  Drill queries satisfy required field constraints because drills carry equality filters on the drilled dimensions.
</Note>

## Examples

```yaml title="Foreign exchange amount requiring currency" theme={null}
fx_amount:
  aggregate_type: sum
  required_fields: [transactions.currency]
  sql: ${transactions.amount}
```


# sample_values - Measures
Source: https://docs.omni.co/modeling/measures/parameters/sample-values

Provides sample values to the Omni Agent to better understand measure magnitude and usage.

Sample values that help the [Omni Agent](/ai/chat) understand the typical range and magnitude of data in this measure. These values are used by the AI to make better field selection decisions and provide more accurate query results.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<measure_name>:
  sample_values: [<value_1>, <value_2>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string[]">
      A list of representative values from the measure. This list doesn't have to be exhaustive. These values help the AI understand the typical range, scale, and context of the metric.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Revenue samples" theme={null}
total_revenue:
  sample_values: [1250.50, 5430.75, 890.25, 12500.00]
```

```yaml title="Count samples" theme={null}
order_count:
  sample_values: [5, 12, 3, 45, 2]
```


# sql - Measures
Source: https://docs.omni.co/modeling/measures/parameters/sql

The core declaration of the field definition.

## Syntax

```yaml theme={null}
<measure_name>:
  sql: ${<view_name>.<field_name>}
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      A SQL expression that defines the measure. Can include field references using `${}` syntax, raw SQL functions, or arithmetic operations.

      Field type is implicit in Omni, and defined based upon the underlying field's database type. To change the type, `CAST` the field (for example, `sql: ${zip_code}::string`).

      <Tip>
        When referencing other fields, use Omni field references (`${view.name}`) instead of the raw database name. For example, `${orders.id}`
      </Tip>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Sum of a field" theme={null}
total_revenue:
  sql: ${orders.sales_price}
  aggregate_type: sum
```

```yaml title="Measure with division" theme={null}
revenue_per_order:
  sql: ${orders.total_revenue} / ${orders.count}
```

```yaml title="Custom SQL function" theme={null}
average_revenue:
  sql: AVG(${orders.sales_price})
```


# suggest_from_field - Measures
Source: https://docs.omni.co/modeling/measures/parameters/suggest-from-field

Suggests filter values from an alternative field's distinct values.

By default, filters run a `SELECT DISTINCT(${field})` to populate filter suggestions. In scenarios where that query may be less performant, or in places where developers may want to curate the suggestion list, this parameter can be used to suggest via an alternative field's distinct values.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Syntax

```yaml theme={null}
<measure_name>:
  suggest_from_field: <view_name>.<field_name>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      The field to use for filter suggestions, specified as `view_name.field_name`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
status_list:
  aggregate: list
  sql: ${status}
  suggest_from_field: order_items.status
```


# suggestion_list - Measures
Source: https://docs.omni.co/modeling/measures/parameters/suggestion-list

Explicitly sets the list of filter options, bypassing the default behavior.

By default, filters run a `SELECT DISTINCT(${field})` to populate filter suggestions. Using this parameter will bypass the default behavior and explicitly set the list of filter options.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Syntax

```yaml theme={null}
<measure_name>:
  suggestion_list: [<value1>, <value2>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="array">
      An unquoted, comma-delimited list of values to use as filter suggestions.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
status_list:
  aggregate: list
  sql: ${status}
  suggestion_list: [complete, pending]
```


# synonyms - Measures
Source: https://docs.omni.co/modeling/measures/parameters/synonyms

Alternative names and terms for a measure that help the Omni Agent understand user intent.

Alternative names and terms for a measure that help the [Omni Agent](/ai/chat) match user queries to the correct field. When users ask questions using different terminology, synonyms help the AI understand which measure they mean.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
<measure_name>:
  synonyms: [<synonym_1>, <synonym_2>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string[]">
      A list of alternative names and terms that refer to this measure. Include common variations, abbreviations, and domain-specific terminology.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Revenue synonyms" theme={null}
total_revenue:
  synonyms: [sales, income, earnings, gross revenue, top line]
```

```yaml title="Customer count synonyms" theme={null}
customer_count:
  synonyms: [number of customers, customer total, client count, user count]
```

```yaml title="Average order value synonyms" theme={null}
avg_order_value:
  synonyms: [AOV, average basket size, average transaction value, mean order value]
```


# tags - Measures
Source: https://docs.omni.co/modeling/measures/parameters/tags

Apply tags to measures for searchable metadata in workbooks and use tag syntax to curate topic fields and drill field lists.

Tags can be referenced or searched in the workbook's field browser within `fields` or `drill_fields` with the syntax `tag:tag_name`.

## Syntax

```yaml theme={null}
<measure_name>:
  tags: [<tag1>, <tag2>, ...]
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string[]">
      An unquoted, comma-delimited list of tag names.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
total_profit:
  aggregate: sum
  sql: ${profit}
  tags: [finance, secure]
```


# view_label - Measures
Source: https://docs.omni.co/modeling/measures/parameters/view-label

Move a measure under a different view in the field browser for better organization, such as grouping aggregates with their source.

For example, grouping `user_facts` fields under the `users` view for better organization and discovery.

## Syntax

```yaml theme={null}
<measure_name>:
  view_label: <view_name>
```

## Properties

<ParamField type="object[]">
  The name of the measure.

  <Expandable title="measure_name properties">
    <ParamField type="string">
      The name of the view to nest the field under.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
sum_lifetime_orders:
  aggregate: sum
  sql: ${user_facts.lifetime_orders}
  view_label: users
```


# access_grants - Model files
Source: https://docs.omni.co/modeling/models/access-grants

Limits user access to a particular field (dimension or measure) through user attributes.

Each grant targets a [user attribute](/administration/users/attributes). Users will be granted access if their corresponding user attribute has any of the values specified in the grant.

Access grants are only applied to direct access and queries, meaning they don't impact references within the model. For example, if a user can't see field `a` but can see field `b`, and `b` references `a`, the user can still access and query using field `b`.

Once defined, access grants can be set for topics and fields with the [`required_access_grants`](/modeling/topics/parameters/required-access-grants) parameter.

## Syntax

```yaml theme={null}
access_grants:
  <access_grant_name>:
    user_attribute: "<user_attribute_reference>"
    allowed_values: ["<value_one>", "<value_two>", ...]
    access_boostable: true/false
```

## Properties

<ParamField type="object">
  A map of access grant objects where each key is the name of a grant. Grant names must be unique.

  <Expandable title="access_grants properties">
    <ParamField type="string">
      A name that uniquely identifies the grant.

      <Expandable title="access_grant_name properties">
        <ParamField type="string">
          The reference of the user attribute that the grant targets.
        </ParamField>

        <ParamField type="string[]">
          A list of values the user attribute must have to be granted access.
        </ParamField>

        <ParamField type="boolean">
          If `true`, users with AccessBoost for a given document will bypass the access grant check for that specific document. Defaults to `false`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Grant access for California and Pennsylvania regions" theme={null}
access_grants:
  region_access:
    user_attribute: "region"
    allowed_values: ["California", "Pennsylvania"]
    access_boostable: false
```

```yaml title="Grant access for user group" theme={null}
access_grants:
  blob_sales_access:
    user_attribute: "omni_user_groups"
    allowed_values: ["Blob Sales"]
    access_boostable: false
```


# ai_chat_topics - Model files
Source: https://docs.omni.co/modeling/models/ai-chat-topics

Controls the topics that are available to the Omni Agent, Chat with Content, MCP, and embedded chat instances.

For the [Omni Agent](/ai/chat) and [embedded chat instances](/embed/customization/ai-chat), topics added to this parameter will display in the topic picker.

* **Limit access to specified topics** - Add the topic names in a list (`[ sales, orders ]`)
* **Exclude the entire model** - Specify an empty list (`[]`)
* **Include all topics in the model** - Leave this parameter unset

**Note**: This parameter doesn't apply to the [Workbook Agent](/ai/queries#generating-queries).

<Warning>
  This parameter changes what the AI is aware of, not what it has access to. All queries are run with the same permissions as the user and it's possible for the AI to make assumptions about schemas given enough context.
</Warning>

## Syntax

```yaml theme={null}
ai_chat_topics: [topic_one, topic_two, ...]
```

## Properties

<ParamField type="string[]">
  An array of topic names that determine which topics are available in the Omni Agent. Supports the following operators:

  | Operator      | Description                            | Order of operations |
  | ------------- | -------------------------------------- | ------------------- |
  | `all_topics`  | Includes all topics in the model       | 1                   |
  | `tag:<value>` | Includes topics with the specified tag | 2                   |
  | `topic_name`  | Includes a specific topic by name      | 3                   |

  Omni evaluates the operators according to the **Order of operations** value in the above table. This allows you to include all topics and then exclude specific ones, or build up your topic list selectively.

  <Tip>
    To exclude a topic or tag, prefix the clause with a `-`. For example: `-personal_stuff` or `-tag:internal`
  </Tip>
</ParamField>

## Examples

```yaml title="Limit access to specified topics" theme={null}
ai_chat_topics: [ sales, orders ]
```

```yaml title="Exclude entire model" theme={null}
ai_chat_topics: []
```

```yaml title="Include all topics, exclude specific ones" theme={null}
ai_chat_topics: [all_topics, -personal_stuff]
```

```yaml title="Filter by tag" theme={null}
ai_chat_topics: [tag:customer_facing]
```

```yaml title="Include all topics except those with a specific tag" theme={null}
ai_chat_topics: [all_topics, -tag:internal]
```


# ai_context - Model files
Source: https://docs.omni.co/modeling/models/ai-context

Sets context for the Omni Agent that is applicable for the entire model.

Free text that provides context to the [Omni Agent](/ai/chat) for all topics in the model.

When a branch or workbook layer extends a model with `ai_context`, Omni uses patch-based merging to preserve parent context while allowing layer-specific modifications. This prevents child layers from overwriting parent context when making edits.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml title="Value is on one line" theme={null}
ai_context: "<value>"
```

```yaml title="Value can contain linebreaks" theme={null}
ai_context: |
  <value>
```

## Properties

<ParamField type="string">
  Free text that provides context to the Omni Agent. Can include behavioral prompting, instructions for tone, or other guidance to .

  The following references are supported for this field:

  * [**User attributes**](/administration/users/attributes), referenced with `{{omni_attributes.<attribute_name>}}`. This allows you to personalize the context for each user.
  * **Model [`constants`](/modeling/models/constants)**, referenced using `@{constant_name}` syntax. This allows you to maintain reusable instruction blocks such as tone, privacy guidance, and domain context instead of duplicating them.
  * **`omni_llm` namespace,** which allows you to tailor context to specific AI model tiers:

    * `{{ omni_llm.model }}` — Substitutes the active model's family name, which will be one of: `smartest`, `standard`, or `fastest`
    * `{{# omni_llm.<family> }}...{{/ omni_llm.<family> }}` — Conditional sections for specific model tiers. `<family>` must be one of `smartest`, `standard`, or `fastest`
    * `{{^ omni_llm.<family> }}...{{/ omni_llm.<family> }}` — Inverse sections, which apply when the specified tier is **not** used. `<family>` must be one of `smartest`, `standard`, or `fastest`

    See the [Examples section](#model-specific) for more information.
  * **`omni_agent` namespace,** which allows you to scope context to specific AI agents:

    * `{{ omni_agent.name }}` — Substitutes the active agent's name, which will be one of: `analyze`, `build`, or `simple_summarize`
    * `{{# omni_agent.<agent> }}...{{/ omni_agent.<agent> }}` — Conditional sections for specific agents. `<agent>` must be one of `analyze`, `build`, or `simple_summarize`
    * `{{^ omni_agent.<agent> }}...{{/ omni_agent.<agent> }}` — Inverse sections, which apply when the specified agent is **not** used. `<agent>` must be one of `analyze`, `build`, or `simple_summarize`

    See the [Examples section](#agent-specific) for more information.
</ParamField>

<ParamField type="object">
  **Server-managed field** that stores how a branch or workbook layer modifies its parent's `ai_context`. Omni automatically generates patches when you edit `ai_context` in a non-base layer.

  You can delete a patch by omitting the `ai_context_patch:` field from your YAML in **Model** mode, but you cannot manually create or edit patch contents. Omni automatically chooses the appropriate patch type.

  The literal `ai_context` is always persisted alongside the patch as the source of truth and fallback.
</ParamField>

## Layer behavior

<Note>
  The patch-based merging described in this section only applies to model-level `ai_context`.
</Note>

When you edit the model-level `ai_context` in a branch or workbook layer in:

<Steps>
  <Step title="Combined mode">
    Omni compares your edited context to the resolved parent context and automatically generates an `ai_context_patch`. Both the literal `ai_context` and the patch are stored.
  </Step>

  <Step title="Model mode">
    You see only the patch content (your layer's contribution) when a patch exists. The literal `ai_context` is hidden but still persisted in the background.
  </Step>
</Steps>

When Omni resolves a model across layers (**Shared > Branch > Workbook**):

1. If a layer has an `ai_context_patch`, Omni attempts to apply it against the resolved parent context
2. If the patch applies successfully, the result becomes the resolved context for that layer
3. If a diff patch cannot apply cleanly, such as due to parent changes, Omni falls back to the layer's literal `ai_context`
4. Append patches always apply successfully, making them ideal for layers that only add context

## Examples

### Behavioral prompting

```yaml title="Behavioral prompting" wrap theme={null}
ai_context: |
  You are an analyst for an eCommerce retailer called BlobsRUs. After generating a query, always provide a summary of the data in both English and Brazilian Portuguese.
```

### Personalized context using user attributes

```yaml title="Personalized context using user attributes" wrap theme={null}
ai_context: |
  You are an analyst for a {{omni_attributes.company_type}} company. Focus on metrics relevant to the {{omni_attributes.region}} region.
```

### Model-specific instructions

The following context will apply when the model tier is `smartest`.

```yaml title="Applies when the model tier is smartest" wrap theme={null}
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".

  You are running on {{ omni_llm.model }}.
  {{/ omni_llm.smartest }}
```

The following context will apply when the model tier is **not** `smartest`.

```yaml title="" wrap theme={null}
ai_context: |
  {{^ omni_llm.smartest }}
  Proceed directly to generating the query without intermediate explanation steps.

  You are running on {{ omni_llm.model }}.
  {{/ omni_llm.smartest }}
```

### Agent-specific instructions

The following context provides detailed modeling conventions to the [`build_configuration` agent](/modeling/models/parameters/ai-settings/build-configuration) while keeping the context concise for other agents.

```yaml title="Agent-specific modeling conventions" wrap theme={null}
ai_context: |
  {{# omni_agent.build }}
  Modeling conventions for this model:
  - Always define primary keys for all base tables
  - Use snake_case for all field names
  - Prefix measures with aggregation type (e.g., total_revenue, count_orders)
  - Document all custom SQL with inline comments
  {{/ omni_agent.build }}

  {{^ omni_agent.build }}
  Standard modeling conventions apply.
  {{/ omni_agent.build }}

  You are the {{ omni_agent.name }} agent.
```

### Using constant references

You can reference [`constants`](/modeling/models/constants) to maintain reusable AI instruction blocks instead of duplicating them:

```yaml title="Model file with constants" theme={null}
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 are analyzing company financial data.
```

### Branch layer appending to parent context

```yaml title="Branch layer appending to parent context" theme={null}
# In the SHARED layer:
ai_context: |
  You are an analyst for BlobsRUs eCommerce.

# In a BRANCH layer, adding region-specific context:
ai_context: |
  You are an analyst for BlobsRUs eCommerce.
  
  Focus on the European market and use metric names in euros.
ai_context_patch:
  append: |
    
    Focus on the European market and use metric names in euros.
```

### Workbook layer modifying parent context

```yaml title="Workbook layer modifying parent context" theme={null}
# In the SHARED layer:
ai_context: |
  You are an analyst for BlobsRUs. Provide detailed explanations.

# In a WORKBOOK layer, changing tone:
ai_context: |
  You are an analyst for BlobsRUs. Keep responses concise.
ai_context_patch:
  diff: |
    @@ -1 +1 @@
    -You are an analyst for BlobsRUs. Provide detailed explanations.
    +You are an analyst for BlobsRUs. Keep responses concise.
```


# auto_run - Model files
Source: https://docs.omni.co/modeling/models/auto-run

Forces workbook queries to require a run click to return new results.

Forces workbook queries to require a run click to return new results. This can be useful if there are cost concerns on running queries as they are built, but it will reduce UI interactivity.

<Note>
  This parameter is independent from [`auto_run_dashboard`](/modeling/models/auto-run-dashboard), which controls dashboard behavior.
</Note>

## Syntax

```yaml theme={null}
auto_run: true/false
```

## Properties

<ParamField type="boolean">
  Controls whether workbook queries automatically run. When set to `false`, users must click a run button to execute queries in the workbook. When set to `true`, queries run automatically as they are built.
</ParamField>

## Examples

```yaml title="Disable auto-run for the model" theme={null}
auto_run: false
```


# auto_run_dashboard - Model files
Source: https://docs.omni.co/modeling/models/auto-run-dashboard

Forces dashboards using the model to require a run click before filter and control changes re-run their queries.

Forces dashboards using the model to require a run click before filter and control changes re-run their queries, letting viewers set every filter before any query fires.

<Note>
  This parameter is independent from [`auto_run`](/modeling/models/auto-run), which controls workbook behavior.
</Note>

## Syntax

```yaml theme={null}
auto_run_dashboard: true/false
```

## Properties

<ParamField type="boolean">
  Controls whether dashboard queries automatically run when filter or control values change. When `false`, a manual **Run** button appears in the dashboard's filter/control bar. When unset or `true`, dashboards auto-run on filter and control changes.
</ParamField>

## Examples

```yaml title="Disable auto-run for dashboards" theme={null}
auto_run_dashboard: false
```


# cache_policies - Model files
Source: https://docs.omni.co/modeling/models/cache-policies

Defines cache policies for the model.

Defines cache policies for the model. Each policy must have a `max_cache_age` parameter that defines the time limit for the policy.

Omni defaults to the following cache policy and filter suggestion retention period:

* **Default cache policy** - 6 hours; overridden with [`max_cache_age`](#param-max-cache-age)
* **Filter suggestion retention** - 30 days; overridden when [`filter_suggestions_must_obey_policy`](#param-filter-suggestions-must-obey-policy) is `true`
* **Omni Agent chat summary responses** - 30 days

**Note**: This parameter allows you to set defaults for the model, but caching policies can also be set at the dashboard level. Editing cache policies in a workbook model or query model effectively applies the policy to the associated dashboard.

Refer to the [Topics documentation](/modeling/topics) for information about setting topic-level cache policies.

## Syntax

```yaml theme={null}
cache_policies:
  <cache_policy_name>:
     max_cache_age: <0_seconds_to_30_days>
     filter_suggestions_must_obey_policy: true/false
```

## Properties

<ParamField type="string">
  A map of cache policy objects where each key is the name of a cache policy. Cache policy names must be unique.

  <Expandable title="cache_policies properties">
    <ParamField type="string">
      A name that uniquely identifies the cache policy.

      <Expandable title="cache_policy_name properties">
        <ParamField type="string">
          Defines a rolling-window time limit for the cache policy. The limit is calculated using the timestamp when the cache entry was written, not a specific time of day.

          For example, if a query populates the cache at 9pm and `max_cache_age` is `24 hours`, users loading the dashboard at 8am the next morning will still see the 9pm result until 9pm that day.

          Accepted values must be between `0 seconds` and `30 days`. If a value exceeding `30 days` is entered Omni will default to the model's specified `default_cache_policy`. If a default policy isn't set, Omni's default policy of 6 hours will be used.

          <Tip>
            To guarantee fresh data at a specific time (for example, at the start of each business day), pair a longer cache policy with a scheduled dashboard run. The scheduler always bypasses the cache and repopulates it with fresh results. Refer to [Cache warming](/analyze-explore/performance/caching#cache-warming-preemptively-caching-data) for the full pattern.
          </Tip>
        </ParamField>

        <ParamField type="boolean">
          <Warning>
            This setting can't currently be removed if set, but it can be changed if needed.
          </Warning>

          Determines whether filter suggestions obey the cache policy. If `false`, filter suggestions will be retained for 30 days. Defaults to `false`.
        </ParamField>

        <ParamField type="string">
          Defines the default cache policy for the model.

          If set, the cache policy will be applied to all topics in the model and override Omni's default cache policy. Refer to the [Topics documentation](/modeling/topics) for information about setting topic-level cache policies.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Retain filter suggestions for 30 days" theme={null}
cache_policies:
  dont_cache_at_all:
    max_cache_age: 0 seconds
    filter_suggestions_must_obey_policy: false       # Retain filter suggestions for 30 days
```

```yaml title="Obey cache policy & retain for 24 hours" theme={null}
cache_policies:
  cache_for_a_day:
    max_cache_age: 24 hours
    filter_suggestions_must_obey_policy: true        # Obey cache policy & retain for 24 hours
```


# calcs_default_pushdown - Model files
Source: https://docs.omni.co/modeling/models/calcs-default-pushdown

Determines if calculations that reference a range are evaluated before the row limit by default.

Determines if calculations that reference a range are evaluated before the row limit by default.

## Syntax

```yaml theme={null}
calcs_default_pushdown: <true|false>
```

## Properties

<ParamField type="boolean">
  When true, calculations that reference a range (e.g. `=SUM(B:B), =RANK(B1, B:B, 0)`) are evaluated before the row limit by default, so they see the full underlying dataset instead of only the visible rows. Users can override this on a per-calculation basis from the column menu in the workbook.
</ParamField>


# compute_routing - Model files
Source: https://docs.omni.co/modeling/models/compute-routing

Routes different job types to different warehouses or slot reservations.

<Note>
  Supported only for Snowflake, Databricks, and BigQuery connections.
</Note>

This setting allows you to route different job types to different warehouses or BigQuery slot reservations without creating duplicate connections. This is useful for optimizing resource allocation based on workload characteristics - for example, routing AI traffic to a small warehouse while sending scheduled deliveries to a larger one.

`compute_routing` is additive. Existing models that use [`warehouse_override`](/modeling/models/warehouse-override) or [`slot_reservation`](/modeling/models/slot-reservation) continue to work unchanged, as those parameters take precedence over `compute_routing`. See [Resolution precedence](#resolution) for more information.

## Syntax

```yaml theme={null}
compute_routing:
  workbook: "<warehouse_or_reservation_name>"
  dashboard: "<warehouse_or_reservation_name>"
  scheduled: "<warehouse_or_reservation_name>"
  export_download: "<warehouse_or_reservation_name>"
  api_run: "<warehouse_or_reservation_name>"
  suggestions: "<warehouse_or_reservation_name>"
  agentic: "<warehouse_or_reservation_name>"
```

## Properties

All keys are optional. Any job type without a routing entry falls through to [lower-precedence routing mechanisms](/modeling/models/compute-routing#resolution) or the connection default.

<ParamField type="object">
  An object that maps job types to warehouse names (for Snowflake and Databricks) or slot reservation names (for BigQuery).

  <Expandable title="properties">
    <ParamField type="string">
      Active editing traffic from the workbook editor, the dashboard editor, and Custom Bin min/max queries.
    </ParamField>

    <ParamField type="string">
      Queries from published dashboards. Covers initial dashboard load and filter changes from viewers.
    </ParamField>

    <ParamField type="string">
      Scheduled deliveries and alerts.
    </ParamField>

    <ParamField type="string">
      User-triggered downloads and exports from the Omni UI, including tile downloads and AI chat query downloads.
    </ParamField>

    <ParamField type="string">
      Queries triggered through the [Query run API](/api/queries/run-query), including spreadsheet-format responses from the same endpoint.
    </ParamField>

    <ParamField type="string">
      Filter autocomplete dropdown queries. These are high-volume, low-cost queries that are typically routed to a small, dedicated warehouse.
    </ParamField>

    <ParamField type="string">
      All AI-triggered traffic, including queries from [Omni's AI agents](/ai), the [MCP server](/ai/mcp), and AI context-gathering.
    </ParamField>
  </Expandable>
</ParamField>

## Resolution precedence

When multiple compute routing mechanisms are defined, Omni resolves them in the following order, with the highest precedence first:

1. [`sql_preamble`](/modeling/models/sql-preamble) if it contains warehouse or session commands
2. **Topic**-level [`warehouse_override`](/modeling/topics/parameters/warehouse-override) or [`slot_reservation`](/modeling/models/slot-reservation)
3. **Model**-level [`warehouse_override`](/modeling/models/warehouse-override) or [`slot_reservation`](/modeling/models/slot-reservation)
4. [`compute_routing` entry](/modeling/models/compute-routing) for the matching job type
5. Connection or user ([Snowflake OAuth](/connect-data/oauth/snowflake) only) default warehouse, or slot reservation

If a model defines both `warehouse_override` (or `slot_reservation`) and `compute_routing`, every query uses `warehouse_override` and `compute_routing` has no effect. To use per-job-type routing, omit `warehouse_override` and `slot_reservation` from the model.

## Validation

Omni validates `compute_routing` when the model is saved. Using `compute_routing` on a connection other than Snowflake, Databricks, or BigQuery surfaces a model validation error.

Omni does not check whether the referenced warehouse or slot reservation exists until query run time. If you reference a warehouse or reservation that doesn't exist or that the connection user can't access, queries for that job type fail at run time.

## Examples

### Route dashboards and exports to different warehouses

In this example, dashboard queries use `DASHBOARD_WH` while exports use `EXPORT_WH`. Other job types fall through to the connection default.

```yaml theme={null}
compute_routing:
  dashboard: "DASHBOARD_WH"
  export_download: "EXPORT_WH"
```

### Isolate AI workloads to a dedicated warehouse

This configuration routes filter autocomplete suggestions to a small warehouse and AI-triggered traffic (Omni's AI agents, MCP, and AI context-gathering) to a dedicated agent warehouse.

```yaml theme={null}
compute_routing:
  suggestions: "SUGGESTIONS_XS_WH"
  agentic: "AGENT_WH"
```

### BigQuery slot reservation routing

For BigQuery connections, `compute_routing` values reference [slot reservation](/modeling/models/slot-reservation) names rather than warehouse names.

```yaml theme={null}
compute_routing:
  dashboard: "dashboard_reservation"
  scheduled: "batch_reservation"
```

## Related

* [warehouse\_override](/modeling/models/warehouse-override)
* [slot\_reservation](/modeling/models/slot-reservation)
* [sql\_preamble](/modeling/models/sql-preamble)


# constants - Model files
Source: https://docs.omni.co/modeling/models/constants

Define reusable string values that can be referenced throughout your model.

Constants are string values that can be defined once in a [model file](/modeling/models) 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`](/modeling/models/ai-context) fields

Constants are also inherited by [shared extension models](/modeling/develop/shared-extensions).

## Syntax

```yaml theme={null}
constants:
  <constant_name>:
    value: <string_value>
```

## Properties

<ParamField type="object">
  A map of constant definitions where each key is the constant name. Names must be unique within the model.

  <Expandable title="constant_name properties">
    <ParamField type="string">
      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}`
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Dynamic schema reference

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

```yaml title="Model file" theme={null}
constants:
  base_schema:
    value: analytics_prod
  staging_schema:
    value: analytics_staging
```

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

```yaml title="View file" theme={null}
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:

```yaml title="Model file" theme={null}
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:

```yaml title="Dimensions in a view" theme={null}
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](/modeling/models/format-values#conditional-formats) branches).

<Note>
  For standard currency and number display, use a [named format](/modeling/models/format-values#named-formats) like `usdcurrency_2` or `percent_1` directly. Constants are most valuable for **custom** Excel-style patterns that appear in several fields.
</Note>

```yaml title="Model file" theme={null}
constants:
  compact_time:
    value: 'm:ss "min"'
  margin_display:
    value: '#,##0.00 "bps"'
```

```yaml title="View file" theme={null}
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](/modeling/models/format-values#constants-in-formats) on the formatting page for more detail.

### Reusable AI context

Constants can be referenced in [`ai_context`](/modeling/models/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.

```yaml title="Model file" theme={null}
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."
```

```yaml title="Topic file" theme={null}
ai_context: |
  @{tone} @{privacy_high}
  @{domain_finance}
  This topic covers invoices. One row is an invoice.
```

<Note>
  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.
</Note>


# custom_formats - Model files
Source: https://docs.omni.co/modeling/models/custom-formats

Define reusable format objects that can be referenced in dimension and measure format parameters.

Custom formats are format objects that can be defined once in a [model file](/modeling/models) and referenced throughout your model. Unlike [constants](/modeling/models/constants), which hold string values, custom formats are complete format objects that can include conditional logic, named formats, Excel-style strings, and other [format features](/modeling/models/format-values).

Custom formats are resolved when formatting values in queries and visualizations, making them ideal for format patterns that need to be centrally managed and consistently applied across multiple fields. For example:

* Complex conditional formats that vary based on field values
* Format patterns that include named formats or custom strings
* Formats that need to be maintained in a single location and used across multiple dimensions or measures

Custom formats are also inherited by [shared extension models](/modeling/develop/shared-extensions).

## Syntax

`custom_formats` accepts either a string or a conditional object:

<Tabs>
  <Tab title="String">
    ```yaml theme={null}
    custom_formats:
      <format_name>: <format_string>
    ```
  </Tab>

  <Tab title="Conditional">
    ```yaml theme={null}
    custom_formats:
      <format_name>:
        depends_on:
          <field|user_attribute|filter>: <field_name|user_attribute_reference|filter_name>
          conditions:
            - condition:
                <filter_expression>
              value: <format_string>
        else: <fallback_format_string>
    ```
  </Tab>
</Tabs>

## Properties

`custom_formats` is a map of format definitions where each key is the format name. Names must be unique within the model.

<Tabs>
  <Tab title="String">
    <ParamField type="string">
      The format definition. This can be any valid [format type](/modeling/models/format-values#choosing-a-format-type):

      * A named format (e.g., `currency_2`, `percent_1`)
      * An Excel-style string (e.g., `'#,##0.00 "kg"'`)
      * A [reference](#reference-custom-format) to another custom format
    </ParamField>
  </Tab>

  <Tab title="Conditional">
    <ParamField type="object">
      Defines the source value to evaluate conditions against. Set exactly one of `field`, `user_attribute`, or `filter`.

      These options resolve as follows:

      | Source           | Resolution timing         | Behavior                                                                                                         |
      | ---------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
      | `field`          | At display time (per row) | Evaluated against each row's value after query results are returned. Each row can resolve to a different format. |
      | `user_attribute` | At query preparation time | The user attribute value is evaluated once. The entire field uses the single resolved format.                    |
      | `filter`         | At query preparation time | The filter value is evaluated once. The entire field uses the single resolved format.                            |

      <Expandable title="depends_on properties">
        <ParamField type="string">
          The name of a field in the same view.
        </ParamField>

        <ParamField type="string">
          The reference of a [user attribute](/administration/users/attributes).
        </ParamField>

        <ParamField type="string">
          The name of a filter applied to the query.
        </ParamField>

        <ParamField type="object[]">
          An ordered list of condition entries. Each entry contains a `condition` using [Omni filter syntax](/modeling/filters) and a `value` specifying the format string to apply when the condition matches.

          <Expandable title="conditions properties">
            <ParamField type="object">
              An Omni filter expression. Supported condition types:

              | Condition                  | Description                    | Example                            |
              | -------------------------- | ------------------------------ | ---------------------------------- |
              | `is`                       | Exact match                    | `is: "USD"`                        |
              | `not`                      | Not equal                      | `not: "USD"`                       |
              | `greater_than`             | Greater than                   | `greater_than: "1000"`             |
              | `greater_than_or_equal_to` | Greater than or equal to       | `greater_than_or_equal_to: "1000"` |
              | `less_than`                | Less than                      | `less_than: "0"`                   |
              | `less_than_or_equal_to`    | Less than or equal to          | `less_than_or_equal_to: "100"`     |
              | `between`                  | Between two values (inclusive) | `between: [10, 100]`               |
              | `not_between`              | Outside a range                | `not_between: [10, 100]`           |
              | `starts_with`              | String starts with             | `starts_with: "US"`                |
              | `ends_with`                | String ends with               | `ends_with: "Corp"`                |
              | `contains`                 | String contains                | `contains: "special"`              |
              | `not_starts_with`          | String does not start with     | `not_starts_with: "US"`            |
              | `not_ends_with`            | String does not end with       | `not_ends_with: "Corp"`            |
              | `not_contains`             | String does not contain        | `not_contains: "special"`          |

              Additional conditions follow the same structure as [filters](/modeling/filters).
            </ParamField>

            <ParamField type="string">
              The format string to apply when the condition matches. Can be a named format or an Excel-style string.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Fallback format string used when no condition matches.
    </ParamField>
  </Tab>
</Tabs>

## Difference from constants

While both `custom_formats` and [`constants`](/modeling/models/constants) enable reusability, they serve different purposes:

* Use `custom_formats` when you need to define a complete format object that will be used across multiple fields
* Use `constants` when you need a reusable string value that might be used in format strings or other contexts

## Referencing custom formats

Once defined in the model file, custom formats can be referenced in [dimension](/modeling/dimensions/parameters/format) and [measure](/modeling/measures/parameters/format) `format` parameters using either a plain string or explicit object syntax:

**Plain string syntax** (recommended):

```yaml theme={null}
format: <format_name>
```

**Explicit object syntax**:

```yaml theme={null}
format:
  custom_format: <format_name>
```

The plain string syntax is the recommended approach — it's cleaner and more concise.

## Examples

### Named format reference

Define custom formats that reference built-in named formats:

```yaml title="Model file" theme={null}
custom_formats:
  standard_currency: currency_2
  high_precision: number_4
  compact_number: big_1
```

```yaml title="View file" theme={null}
dimensions:
  price:
    sql: '"price"'
    format: standard_currency
measures:
  total_revenue:
    sql: '"amount"'
    aggregate_type: sum
    format: standard_currency
```

### Excel-style strings

Define custom formats with Excel-style strings:

```yaml title="Model file" theme={null}
custom_formats:
  weight_display: '#,##0.00 "kg"'
  margin_bps: '#,##0.00 "bps"'
  compact_time: 'm:ss "min"'
```

```yaml title="View file" theme={null}
dimensions:
  product_weight:
    sql: '"weight"'
    format: weight_display
measures:
  avg_margin:
    sql: '"margin"'
    aggregate_type: avg
    format: margin_bps
```

### Conditional formats

Define custom formats with conditional logic that selects different formats based on field values:

```yaml title="Model file" theme={null}
custom_formats:
  dynamic_currency:
    depends_on:
      field: orders.currency_code
      conditions:
        - condition:
            is: USD
          value: usdcurrency_2
        - condition:
            is: GBP
          value: gbpcurrency_2
        - condition:
            is: EUR
          value: eurcurrency_2
    else: currency_2
  
  performance_indicator:
    depends_on:
      field: metrics.status
      conditions:
        - condition:
            is: excellent
          value: '"🚀 "0.0'
        - condition:
            is: poor
          value: '"📉 "-0.0'
    else: number_2
```

```yaml title="View file" theme={null}
dimensions:
  total_amount:
    sql: '"amount"'
    format: dynamic_currency
measures:
  performance_score:
    sql: '"score"'
    aggregate_type: avg
    format: performance_indicator
```

### Combining custom formats with model constants

Custom formats can reference [model constants](/modeling/models/constants) to create even more flexible formatting patterns.

<Tabs>
  <Tab title="Use constants to add a unit suffix">
    ```yaml title="Model file" theme={null}
    constants:
      unit_suffix:
        value: "units"

    custom_formats:
      quantity_format: '#,##0 "@{unit_suffix}"'
    ```

    ```yaml title="View file" theme={null}
    measures:
      total_quantity:
        sql: '"quantity"'
        aggregate_type: sum
        format: quantity_format
    ```
  </Tab>

  <Tab title="Use constants to specify time and numeric formats with suffixes">
    ```yaml title="Model file" theme={null}
    constants:
      compact_time:
        value: 'm:ss "min"'
      margin_display:
        value: '#,##0.00 "bps"'
    ```

    ```yaml title="View file" theme={null}
    measures:
      avg_duration:
        sql: '"duration_secs"'
        aggregate_type: avg
        format: "@{compact_time}"
      margin:
        sql: '"margin_bps"'
        aggregate_type: avg
        format: "@{margin_display}"
    ```
  </Tab>
</Tabs>


# default_cache_policy - Model files
Source: https://docs.omni.co/modeling/models/default-cache-policy

Defines the default cache policy for the model.

Defines the default cache policy for the model. If set, the cache policy will be applied to all topics in the model and override Omni's default cache policy.

## Syntax

```yaml theme={null}
default_cache_policy: <cache_policy_name>
```

## Properties

<ParamField type="string">
  The name of the policy to use as the default cache policy for the model. This value must be the name of a cache policy defined in the model's [`cache_policies`](/modeling/models/cache-policies) parameter.

  If not set, Omni's default cache policy will be used.
</ParamField>

## Examples

```yaml theme={null}
default_cache_policy: daily_cache_policy
```


# default_group_by - Model files
Source: https://docs.omni.co/modeling/models/default-group-by

Controls whether measure-less queries get an implicit GROUP BY.

<Note>
  This parameter is distinct from the query view-level [`default_group_by`](/modeling/query-views/parameters/default-group-by) parameter. The two settings apply at different scopes and serve different purposes.
</Note>

Controls whether measure-less queries get an implicit `GROUP BY`.

`always_having`, totals, and pivots will continue to force aggregation regardless of this setting.

## Syntax

```yaml theme={null}
default_group_by: <always | never | primary_key>
```

## Properties

<ParamField type="string">
  Controls whether measure-less queries get an implicit `GROUP BY`. Valid values are:

  * `always` — **Default**. Measure-less queries always get an implicit `GROUP BY`.
  * `never` — Measure-less queries never get an implicit `GROUP BY`
  * `primary_key` — The implicit `GROUP BY` is dropped only when the full primary key is selected unparameterized and there is no fan-out join. This avoids unnecessary deduplication when the result set is already guaranteed to be unique.

  <Note>
    `always_having`, totals, and pivots will continue to force aggregation regardless of this setting.
  </Note>
</ParamField>

## Examples

### Always group

In this example, measure-less queries always include a `GROUP BY`, deduplicating rows where all selected dimensions have identical values.

```yaml theme={null}
default_group_by: always
```

### Never group

In this example, measure-less queries will not include an implicit `GROUP BY` and will potentially return duplicate rows.

```yaml theme={null}
default_group_by: never
```

### Group by primary key

In this example, the implicit `GROUP BY` is only dropped when the full primary key is selected unparameterized and there is no fan-out join. This avoids unnecessary deduplication when the result set is already guaranteed to be unique.

```yaml theme={null}
default_group_by: primary_key
```


# default_numeric_locale - Model files
Source: https://docs.omni.co/modeling/models/default-numeric-locale

Defines global number formatting in the model.

Defines global number formatting in the model, including how thousands and decimals are delimited and the default currency symbol.

This parameter can be set dynamically using a [user attribute](/administration/users/attributes), which is for multi-regional organizations where different users need to see numbers formatted according to their local conventions.

## Syntax

```yaml theme={null}
default_numeric_locale: <locale>
```

## Properties

<ParamField type="string">
  Defines the locale to use for global number formatting. Value must be one of the following:

  * `en_US` - **Default**. Comma-delimited thousands, period-delimited decimals, dollar default currency
  * `br_BR` (Brazil) - Dot-delimited thousands, comma-delimited decimals, Real default currency
  * `de_DE` (Germany) - Dot-delimited thousands, comma-delimited decimals, Euro default currency
  * `en_GB` (United Kingdom) - Comma-delimited thousands, period-delimited decimals, pound default currency
  * `fi_FI` (Finland) - Space-delimited thousands, comma-delimited decimals, Euro default currency
  * `fr_FR` (French) - Space-delimited thousands, comma-delimited decimals, Euro default currency
  * `ja_JP` (Japan) - Comma-delimited thousands, period-delimited decimals, yen default currency
  * `nl_NL` (Netherlands) - Dot-delimited thousands, comma-delimited decimals, Euro default currency
  * `pt_PT` (Portugal) - Dot-delimited thousands, comma-delimited decimals, Euro default currency

  Can be set dynamically using [user attributes](/administration/users/attributes). See the [**Examples**](#dynamic-value-using-user-attributes) section for an example.
</ParamField>

## Examples

### Static value

```yaml title="French numeric locale" theme={null}
default_numeric_locale: fr_FR
```

### Dynamic value using user attributes

This example assumes your Omni instance has an existing user attribute called `user_locale` and that users have been assigned appropriate locale codes, such as `en_US` for US users.

```yaml title="Set numeric locale based on user's region" theme={null}
default_numeric_locale: {{ omni_attributes.user_locale }}
```


# default_row_limit - Model files
Source: https://docs.omni.co/modeling/models/default-row-limit

Sets the default row limit for new queries within the model.

When set, the default row limit will be applied to topic-based queries and queries built from **All Views and Fields** that are created **after** the limit is defined. If not set, the system default of 1,000 rows is used.

Individual topics can override the model-level setting with their own [`default_row_limit`](/modeling/topics/parameters/default-row-limit) value.

## Syntax

```yaml theme={null}
default_row_limit: number
```

## Properties

<ParamField type="integer">
  The default number of rows to return for new queries. Must be between 1 and 50,000.
</ParamField>

## Examples

```yaml title="Set default row limit to 5,000" theme={null}
default_row_limit: 5000
```


# default_timeframes - Model files
Source: https://docs.omni.co/modeling/models/default-timeframes

Sets the default timeframes available for date and time fields across the model.

Defines the set of timeframes available by default for every date and time field in the model. This overrides Omni's built-in default set of `raw`, `date`, `week`, `month`, `quarter`, and `year`.

Use this parameter to surface only the timeframes that matter for your use case (for example, dropping `quarter` and `year` for operational models, or adding `hour` for high-frequency event data).

Individual date or time dimensions can override this set with their own [`timeframes`](/modeling/dimensions/parameters/timeframes) parameter.

## Syntax

```yaml theme={null}
default_timeframes: [<timeframe_1>, <timeframe_2>, ...]
```

## Properties

<ParamField type="string[]">
  An array of timeframe names to use as the default for date and time fields in the model. The following timeframes are supported:

  | Name               | Notes                                                                  |
  | ------------------ | ---------------------------------------------------------------------- |
  | `date`             |                                                                        |
  | `day_of_month`     |                                                                        |
  | `day_of_quarter`   | Behaves as fiscal day of quarter when fiscal offset is applied         |
  | `day_of_week_name` | Sorts by `day_of_week_num`                                             |
  | `day_of_week_num`  |                                                                        |
  | `day_of_year`      |                                                                        |
  | `fiscal_quarter`   | Requires [`fiscal_month_offset`](/modeling/models/fiscal-month-offset) |
  | `fiscal_year`      | Requires [`fiscal_month_offset`](/modeling/models/fiscal-month-offset) |
  | `hour`             |                                                                        |
  | `hour_of_day`      |                                                                        |
  | `millisecond`      |                                                                        |
  | `minute`           |                                                                        |
  | `month`            |                                                                        |
  | `month_name`       | Sorts by `month_num`                                                   |
  | `month_num`        |                                                                        |
  | `quarter`          |                                                                        |
  | `quarter_of_year`  |                                                                        |
  | `raw`              |                                                                        |
  | `second`           |                                                                        |
  | `week`             |                                                                        |
  | `year`             |                                                                        |
</ParamField>

## Examples

```yaml title="Limit defaults to day, week, and month" theme={null}
default_timeframes: [date, week, month]
```

```yaml title="Include hourly and fiscal granularities by default" theme={null}
default_timeframes: [date, week, month, quarter, year, hour, fiscal_quarter, fiscal_year]
```


# default_topic_access_filters - Model files
Source: https://docs.omni.co/modeling/models/default-topic-access-filters

Defines default access filters for topics in the model.

Defines a list of default access filters for topics in the model. Access filters limit row-level access to data based on user attributes.

## Syntax

```yaml theme={null}
default_topic_access_filters:
  - field: <view>.<field>
    user_attribute: <user_attribute_reference>
    values_for_unfiltered: [<user_attribute_value>]
  - field: <view>.<field>
    user_attribute: <user_attribute_reference>
    values_for_unfiltered: [<user_attribute_value>]
```

## Properties

<ParamField type="object[]">
  A list of default access filters to apply to topics in the model.

  <Expandable title="default_topic_access_filters properties">
    <ParamField type="string">
      The name of a field, specified using `<view>.<field>` convention, to match to the `user_attribute`.
    </ParamField>

    <ParamField type="string">
      A user attribute reference. Records with `field` values that match the user's attribute value will be visible to the user.

      For example, if a user has a `customer` value of `blobsrus` and the `products.brand` field in a record has a `blobsrus` value, the user will have access to the record.
    </ParamField>

    <ParamField type="string[]">
      User attribute values that allow unrestricted access. Users with these values will not have the access filter applied.

      <Warning>
        Do not use the same value as the attribute's default. Any user who inherits the attribute's default value will receive unfiltered data.
      </Warning>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Match brand field value to customer user attribute value" theme={null}
default_topic_access_filters:
  - field: products.brand
    user_attribute: customer
    values_for_unfiltered: [is_admin]
```

## Troubleshooting

If an access filter can't be mapped to a topic, an error will surface in the model IDE. Add a blank [`access_filters`](/modeling/topics/parameters/access-filters) parameter to the topic to resolve the issue:

```yaml title="Topic file" theme={null}
access_filters: []
```


# default_topic_required_access_grants - Model files
Source: https://docs.omni.co/modeling/models/default-topic-required-access-grants

Defines a default required access grant for all topics contained in a model.

Defines a list of default required [access grants](/modeling/develop/data-access-control) for all topics contained in a model, unless other grants are applied at the topic level. Access grants control data access for topics in a model based on user attributes.

Refer to the [Controlling data access guide](/modeling/develop/data-access-control#overriding-default-topic-access-grants) for an example of overriding a default topic access grant.

## Syntax

```yaml theme={null}
default_topic_required_access_grants: [access_grant_one, access_grant_two, ...]
```

## Properties

<ParamField type="string[]">
  A list of default required access grants for all topics in the model, including [composite topics](/modeling/composite-topics/parameters/required-access-grants) that don't set their own `required_access_grants`. These values must be the names of access grants defined in the model's [`access_grants`](/modeling/models/access-grants) parameter.

  <Note>
    Topics created from [CSV/Excel uploads](/analyze-explore/data-input-csvs#modeling-and-promoting-data-input-tables) are automatically exempt from model-level default access grants. They receive empty access grants (`[]`) at creation time, making them accessible to all users including embed users. This ensures that uploaded CSVs remain accessible without additional configuration.
  </Note>
</ParamField>

## Examples

```yaml title="Defines finance as the required access grant for topics" theme={null}
default_topic_required_access_grants: [finance]

access_grants:
  nw_region:
    user_attribute: region
    allowed_values: [washington, idaho, oregon, wyoming, alaska]
  finance:
    user_attribute: omni_user_groups
    allowed_values: [Finance]
  marketing:
    user_attribute: omni_user_groups
    allowed_values: [Marketing]
```


# dynamic_schemas - Model files
Source: https://docs.omni.co/modeling/models/dynamic-schemas

Creates a copy of the specified schema as a virtual schema.

Creates a copy of the specified schema as a virtual schema. The views in the dynamic schema are generated from the schema specified in `from_schema`. When generating SQL against dynamic schema views, the `user_attribute` assigned to the user running the query is used to scope table references.

If you're using [embedding](/embed), you can use this setting to partition customer data into separate, but identical schemas.

<Note>
  If `from_schema` references a Redshift datashare-backed external schema, that schema must be created and the Omni user must be granted access to it **before** running a schema refresh. Omni will not discover datashare-backed schemas that haven't been explicitly created and permissioned in the connected database. See [Connecting to Redshift datashares](/connect-data/setup/redshift#connecting-to-redshift-datashares).
</Note>

All modeling will reference views in the dynamic schema with this naming convention: `dynamic_schema_name__view_name`

## Syntax

```yaml theme={null}
dynamic_schemas:
  <dynamic_schema_name>:
    from_schema: <canonical_schema_name>
    user_attribute: <user_attribute_name>
```

## Properties

<ParamField type="object">
  A map of dynamic schema objects where each key is the name of the new dynamic schema.

  <Expandable title="dynamic_schemas properties">
    <ParamField type="string">
      The name of the new dynamic schema.

      <Expandable title="dynamic_schema_name properties">
        <ParamField type="string">
          The name of the schema to copy.
        </ParamField>

        <ParamField type="string">
          The reference of the user attribute to use to scope table references.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>


# dynamic_shared_extensions - Model files
Source: https://docs.omni.co/modeling/models/dynamic-shared-extensions

Dynamically extends the model based on user attribute values, enabling user-specific model customization.

<Note>
  See [Shared extension models](/modeling/develop/shared-extensions/index) for an overview of extension models.
</Note>

Advanced feature for dynamically extending the model based on [user attributes](/administration/users/attributes). Each extension maps user attribute values to model extensions, enabling user-specific model customization. This can be used for localization or other advanced use cases.

This parameter requires enabling the **Shared extensions model** feature for your Omni instance. Reach out to Omni support to have this feature enabled.

## Syntax

Each extension must use either `mappings` (explicit) or `map_pattern` (programmatic), but not both.

<CodeGroup>
  ```yaml Explicit attribute mapping theme={null}
  dynamic_shared_extensions:
    - user_attribute: <user_attribute_reference>
      mappings:
        <extension_model_name>:
          values_for_model: [<user_attribute_value>, ...]
  ```

  ```yaml Programmatic attribute mapping theme={null}
  dynamic_shared_extensions:
    - map_pattern: "<template_with_{{omni_attributes.attribute_name}}>"
  ```
</CodeGroup>

## Properties

<ParamField type="object[]">
  A list of dynamic extensions to apply to the model. Each extension must specify either `mappings` or `map_pattern`, but not both.

  <Expandable title="dynamic_shared_extensions properties">
    <ParamField type="string">
      The reference of the user attribute that determines which extension to apply. Required when using `mappings`. Optional when using `map_pattern` — if omitted, attributes referenced in the pattern are used.
    </ParamField>

    <ParamField type="object">
      A map of extension model names to the user attribute values that trigger them. If a user's `user_attribute` value is included in a mapping's `values_for_model` list, the corresponding extension model (the mapping key) is applied. If no mapping matches, no extension is applied.

      <Expandable title="mappings properties">
        <ParamField type="object">
          A key whose name matches the name of the extension model to apply.

          <Expandable title="extension_model_name properties">
            <ParamField type="string[]">
              A list of values for the referenced `user_attribute`. When the user's attribute value matches any value in this list, the extension model is applied.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      A Mustache template string that generates extension model names from user attribute values. Use `{{omni_attributes.<attribute_name>}}` placeholders to reference user attributes.

      At query time, the placeholders are substituted with the current user's attribute values to produce one or more extension model names. If the generated name matches an existing extension model, it's applied; otherwise it's silently skipped.

      **Note**: User attributes can have multiple values. In this case, Omni will try all values for the attribute. Multiple matches may occur as a result.

      If the pattern references multiple attributes and the user has multiple values for one or more of them, Omni generates all combinations.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Explicit customer extensions

In this example, users with a `customer_id` of `blobs_r_us` have the `blobs_r_us` extension model applied; users with `mega_blobs` have the `mega_blobs` extension model applied.

```yaml title="Apply per-customer extension models" theme={null}
dynamic_shared_extensions:
  - user_attribute: customer_id
    mappings:
      blobs_r_us:
        values_for_model: [blobs_r_us]
      mega_blobs:
        values_for_model: [mega_blobs]
```

### Localize model by language attribute

In this example, each extension model (`model_es`, `model_fr`, `model_de`) overrides view and field labels with translated values for that language.

```yaml title="Localize the model by language" theme={null}
dynamic_shared_extensions:
  - user_attribute: language
    mappings:
      model_es:
        values_for_model: [es, spanish]
      model_fr:
        values_for_model: [fr, french]
      model_de:
        values_for_model: [de, german]
```

Users with the `language` attribute set to `es` or `spanish` have the `model_es` extension applied, and so on. Users whose attribute value doesn't match any entry in a `values_for_model` list have no extension applied.

### Programmatic extensions by department

In this example, the user's `department` attribute value is substituted into the pattern to produce the extension model name.

```yaml title="Programmatically apply per-department extension models" theme={null}
dynamic_shared_extensions:
  - user_attribute: department
    map_pattern: "{{omni_attributes.department}}_extension"
```

A user with `department: marketing` has the `marketing_extension` model applied; a user with `department: sales` has `sales_extension` applied. This avoids enumerating each department explicitly, but requires extension model names to follow a set pattern.

### Create a pattern with multiple user attributes

In this example, both `department` and `region` are combined to generate the extension model name.

```yaml title="Combine multiple attributes in the pattern" theme={null}
dynamic_shared_extensions:
  - map_pattern: "{{omni_attributes.department}}_{{omni_attributes.region}}_model"
```

A user with `department: marketing` and `region: us` has the `marketing_us_model` extension applied. If a user has multiple values for either attribute, all combinations are generated and any matching extension models are applied.


# extends - Model files
Source: https://docs.omni.co/modeling/models/extends

Enables extending a model.

Enables extending a model. Check out this [community post](https://community.omni.co/t/how-can-i-share-logic-across-multiple-models-hub-and-spoke/150) for more information.


# facet_workbook_filters - Model files
Source: https://docs.omni.co/modeling/models/facet-workbook-filters

Facets all filter suggestions in the workbook to the current filter selections.

Facets all filter suggestions in the workbook to the current filter selections.

<Tip>
  See [Customizing filter suggestions](/guides/modeling/filter-suggestions) for more information about filter suggestions.
</Tip>

## Syntax

```yaml theme={null}
facet_workbook_filters: true/false
```

## Properties

<ParamField type="boolean">
  When `false` (default), one filter selection won't facet another filter. For example, when selecting `state = California`, `country` would still suggest `US` and `UK`.

  When `true`, all filter suggestions in the workbook will be faceted based on the current filter selection. This may result in filter suggestions taking more time to run complex queries with less caching. Additionally, results may not be returned when suggestions are expected.
</ParamField>

## Examples

```yaml theme={null}
facet_workbook_filters: true
```


# fiscal_month_offset - Model files
Source: https://docs.omni.co/modeling/models/fiscal-month-offset

Sets a fiscal calendar in Omni and enables adding fiscal time metrics to time dimension groups and filters in the UI.

Sets a fiscal calendar in Omni and enables adding fiscal time metrics to time dimension groups and filters in the UI.

<Tip>
  `fiscal_quarter` and `fiscal_year` timeframes will not work without a `fiscal_month_offset`.
</Tip>

This parameter can be set dynamically using a [user attribute](/administration/users/attributes), which is useful when different users or business units use different fiscal calendars.

## Syntax

```yaml theme={null}
fiscal_month_offset: positive_or_negative_number
```

## Properties

<ParamField type="number">
  A positive or negative number used to set the fiscal calendar. A positive month offset will set the fiscal calendar in front of the [Gregorian calendar date](https://en.wikipedia.org/wiki/Gregorian_calendar).

  Can be set dynamically using [user attributes](/administration/users/attributes). See the [**Examples**](#dynamic-value-using-user-attributes) section for an example.
</ParamField>

## Examples

### Static values

```yaml title="Feb 1 start - FY Month 1 of 2025 = Feb 2024" theme={null}
fiscal_month_offset: 11
```

```yaml title="March 1 start" theme={null}
fiscal_month_offset: 10
```

```yaml title="Feb 1 start but FY Month 1 of 2024 = Feb 2024" theme={null}
fiscal_month_offset: -1
```

### Dynamic value using user attributes

This example assumes your Omni instance has an existing user attribute called `fiscal_offset` and that users have been assigned appropriate numeric values, such as `11` for users in Region A, `10` for users in Region B, etc.

```yaml title="Set fiscal month offset based on user's region" theme={null}
fiscal_month_offset: {{ omni_attributes.fiscal_offset }}
```


# Formatting values
Source: https://docs.omni.co/modeling/models/format-values

Format dimension and measure values with named formats, Excel-style strings, conditional formats, model constants, locale settings, and Markdown table cells.

Formatting controls how values display in queries and visualizations. You set a format on a [dimension](/modeling/dimensions/parameters/format) or [measure](/modeling/measures/parameters/format) using the `format` parameter, or define reusable formats at the model level with [`custom_formats`](/modeling/models/custom-formats).

Formats can also be set on a per-query basis from visualization configuration, using the same format types.

## Common questions

<AccordionGroup>
  <Accordion title="When are formats applied?">
    Formats are applied **after** the SQL runs, so they do not impact grouping. To handle grouping with truncation, use `ROUND()` or `FLOOR()`.
  </Accordion>

  <Accordion title="How are custom formats and model constants different?">
    While both `custom_formats` and `constants` enable reusability, they serve different purposes:

    * Use [`custom_formats`](/modeling/models/custom-formats) when you need to define a complete format object that will be used across multiple fields
    * Use [`constants`](/modeling/models/constants) when you need a reusable string value that might be used in format strings or other contexts
  </Accordion>

  <Accordion title="Can I use model constants in formats?">
    Yes. You can reuse a [model constant](/modeling/models/constants) inside any format string — named, custom Excel-style, or a conditional format branch — with `@{constant_name}`:

    ```yaml title="Model file" theme={null}
    constants:
      compact_time:
        value: 'm:ss "min"'
      margin_display:
        value: '#,##0.00 "bps"'
    ```

    ```yaml title="Dimension or measure" theme={null}
    dimensions:
      margin:
        sql: '"margin_bps"'
        format: "@{margin_display}"
    ```

    Constants are validated against the model: unknown names and malformed `@{...}` references surface as model validation issues in the IDE.
  </Accordion>

  <Accordion title="Do I need a constant to reuse a named format?">
    No. If a [named format](#named-formats) like `usdcurrency_2` or `percent_1` already does what you need, use it directly — there is no benefit to wrapping a named format in a constant.
  </Accordion>

  <Accordion title="How do formats work with Markdown?">
    There are two separate ways Markdown can factor in:

    | Approach                                                 | How                                                                                                                              | When to use                                                                                         |
    | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
    | `format` with a [Mustache template](#mustache-templates) | Add `{{field}}` references to a format string. Omni fills them in at display time and returns **plain text**.                    | You want to pull in values from other fields — for example, a currency symbol that changes per row. |
    | `markdown` parameter                                     | A separate Mustache template on a dimension or measure that Omni renders through its Markdown processor in **data table** cells. | You want Omni itself to render bold text, links, or images directly in the workbook table.          |

    The key difference: `format` returns **plain text**; `markdown` returns **rendered Markdown HTML** in table cells.

    You can set both on the same field: `format` controls display in standard value cells (and for numeric/date fields); `markdown` takes over when the column is shown as Markdown in a table visualization.

    See [Mustache templates](#mustache-templates), [Dimension `markdown`](/modeling/dimensions/parameters/markdown), and [Measure `markdown`](/modeling/measures/parameters/markdown) for syntax and examples.
  </Accordion>
</AccordionGroup>

## Where to define formats

Formats can be defined in two places:

| Approach        | Where                                                                                                                              | Use when                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Field-level** | The `format` parameter on a [dimension](/modeling/dimensions/parameters/format) or [measure](/modeling/measures/parameters/format) | The format is specific to a single field                                                |
| **Model-level** | The [`custom_formats`](/modeling/models/custom-formats) parameter in a model file                                                  | The same format is used across multiple fields and you want to maintain it in one place |

Both approaches support the same format types — the difference is whether the format is defined inline on the field or defined once and referenced by name.

## Choosing a format type

Formats accept four shapes. Pick the one that matches your use case:

| Use this                                   | When you want to                                                                                                                                                                                                                                                | Examples                                              |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Named format](#named-formats)             | Apply a built-in format. Start here — named formats handle currency, percentages, and compact numbers. Use a currency prefix like `usd`, `gbp`, or `jpy` for a specific currency; omit the prefix to use the [locale's default](#locale-and-number-formatting). | `currency_2`, `usdaccounting_0`, `percent_1`, `big_2` |
| [Excel-style string](#excel-style-strings) | Control layout beyond what named formats offer — append units, add text, use semicolon sections for positive/negative display, or add [Mustache](#mustache-templates) `{{field}}` references to interpolate other row values.                                   | `'#,##0.00 "kg"'`, `'"{{currency.raw}}" #,###.00'`    |
| [Conditional format](#conditional-formats) | Choose the format at runtime based on a field value, user attribute, or filter. Each branch can reference a named format, an Excel-style string, or a [model constant](#constants-in-formats).                                                                  | `depends_on: { field: currency_code }`                |
| [Reusable format](#custom-formats)         | Define a reusable format at the model level. Reusable formats can include named formats, Excel-style strings, or conditional logic.                                                                                                                             | `format: dynamic_currency`, `format: margin_bps`      |

### Named formats

Numeric and currency formats default to two decimal places, with the exception of `id`. You can explicitly set decimal places by appending `_<number_of_places>` (up to 4) to a numeric or currency format. For example, `format: number_4`, `format: big_1`, `format: usdaccounting_0`.

When decimal length isn't set, decimals will be truncated to the shortest possible length for each row.

#### Numeric formats

| Format      | Example                       | Notes                                                                |
| ----------- | ----------------------------- | -------------------------------------------------------------------- |
| `number`    | 1,234.50 (`number_2`)         |                                                                      |
| `percent`   | 24.4% (`percent_1`)           |                                                                      |
| `id`        | 123450                        | Numbers, no commas                                                   |
| `billions`  | 1.20B (`billions_2`)          |                                                                      |
| `millions`  | 5.6M (`millions_1`)           |                                                                      |
| `thousands` | 8.90K (`thousands_2`)         |                                                                      |
| `big`       | 5.60M; 1.23K; 12.23 (`big_2`) | Uses `millions` if `>1M`; `thousands` if `>1000`; otherwise `number` |

#### Currency formats

Currency formats are available for **USD**, **EUR**, **GBP**, **AUD**, **JPY**, and **BRL**. Prefix the format category with the currency code (for example, `usdcurrency`, `jpyaccounting`). Formats without a currency prefix use the organization's default currency.

| Format category                                                              | Example                                     | Notes                            |
| ---------------------------------------------------------------------------- | ------------------------------------------- | -------------------------------- |
| `accounting` (e.g. `usdaccounting`, `jpyaccounting`)                         | \$(1,234.50) (`usdaccounting_2`)            |                                  |
| `currency` (e.g. `usdcurrency`, `gbpcurrency`)                               | -£1,234.50 (`gbpcurrency_2`)                |                                  |
| `bigcurrency` (e.g. `bigusdcurrency`, `bigjpycurrency`)                      | €5.60M; €1.23K; €12.23 (`biggbpcurrency_2`) | Compact display                  |
| `financial` (e.g. `audfinancial`, `brlfinancial`)                            | (1,234.50) (`financial_2`)                  | Does not contain a currency mark |
| `bigaccounting`, `bigfinancial` (e.g. `bigusdaccounting`, `bigjpyfinancial`) | Same compact rules as `big*` formats        |                                  |

#### Time formats

Time formats are available for [dimensions](/modeling/dimensions/parameters/format) only.

| Format                                                                | Notes                                                                      |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [d3 time formats](https://github.com/d3/d3-time-format#locale_format) | Individual timeframe elements can be formatted using `timeframe_metadata`. |
| `"%Y-%m"`                                                             |                                                                            |
| `"%Y-%m-%d"`                                                          |                                                                            |
| `"%Y-%m-%d %H:%M:%S"`                                                 |                                                                            |

```yaml title="Time format with timeframe metadata" theme={null}
created_at:
  timeframe_metadata:
    month:
      format: "%Y-%m-%d"
```

### Excel-style strings

In addition to [named formats](#named-formats), formats accept Excel-style strings. These follow the same conventions as spreadsheet number formats.

<Tip>
  **For standard currency display**, prefer [named formats](#named-formats) like `usdcurrency_2` or `gbpaccounting_0`. Use Excel-style strings when you need layout control that named formats don't offer — for example, appending units, mixing text with numbers, or using semicolon sections for positive/negative display.
</Tip>

| Pattern         | Description                                  | Example output |
| --------------- | -------------------------------------------- | -------------- |
| `#,##0`         | Number with thousands separator, no decimals | 1,234          |
| `#,##0.00`      | Number with thousands separator, 2 decimals  | 1,234.56       |
| `0%`            | Percentage, no decimals                      | 75%            |
| `0.00%`         | Percentage, 2 decimals                       | 75.00%         |
| `0.00E+00`      | Scientific notation                          | 1.23E+03       |
| `#,##0 "units"` | Number with literal text suffix              | 1,234 units    |
| `#,##0.0,`      | Divide by 1,000 (trailing comma)             | 1.2            |
| `#,##0.0,,"M"`  | Divide by 1,000,000 with suffix              | 1.2M           |

#### Semicolon-separated sections

Excel-style format strings support up to four sections separated by semicolons, applied in order: **positive values**; **negative values**; **zero**; **text**. You can omit trailing sections — for example, two sections apply the first to positive values and the second to negative values.

```yaml theme={null}
format: '"🚀 "0.0;"📉 "-0.0;0'
```

This renders:

* Positive values as `🚀 1.5`
* Negative values as `📉 -1.5`
* Zero as `0`

Use quoted YAML strings so `"` and `;` parse correctly.

#### Mustache field references

Excel-style strings can include [Mustache](/visualize-present/mustache-reference) references to other field values using `{{view_name.field_name.property}}`. This lets you build format strings that incorporate values from other fields in the query, such as a dynamic currency symbol.

Supported properties:

| Property            | Description                     |
| ------------------- | ------------------------------- |
| `value`             | The formatted field value       |
| `raw`               | The unformatted field value     |
| `value_url_encoded` | The URL-encoded formatted value |

```yaml title="Dynamic currency symbol from another field" theme={null}
revenue:
  sql: '"amount"'
  aggregate_type: sum
  format: '#,##0.00 "{{orders.currency_symbol.value}}"'
```

<Warning>
  Referencing other fields in a format string implicitly requires those fields to be included in the query results. Omni will automatically add them, which may change the `GROUP BY` clause of the generated SQL.
</Warning>

### Mustache templates

Any `format` string — named, Excel-style, or a conditional branch — can embed [Mustache](/visualize-present/mustache-reference) references to other fields in the row using `{{view_name.field_name.property}}` syntax. Omni resolves these references at display time before applying the format. What happens with the resolved string depends on the field type:

| Field type                                  | What Omni does with the resolved format string                                                                                                  |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Number**                                  | Uses it as the Excel-style format string for the number. Use this to embed a dynamic symbol or suffix — for example, a per-row currency symbol. |
| **Date/time**                               | Uses it as the strftime format string, but only if it contains `%`. Resolved strings without `%` are silently ignored.                          |
| **All other types** (string, boolean, etc.) | Returns the resolved string directly as the field's display value. Use this to build a computed label from multiple fields.                     |

```yaml title="Dynamic currency symbol for a number (embed in format string)" theme={null}
measures:
  revenue:
    sql: '"amount"'
    aggregate_type: sum
    format: '"{{orders.currency_symbol.value}}" #,###.00'
```

```yaml title="Dynamic currency symbol as a conditional else branch" theme={null}
measures:
  total_value:
    format:
      depends_on:
        filter: reporting_currency_filter
        conditions:
          - condition:
              is: converted_EUR
            value: eurcurrency
          - condition:
              is: converted_USD
            value: usdcurrency
      else: '"{{order_items.reporting_currency_symbol.value}}" #,###.00'
```

```yaml title="Computed display value for a string field" theme={null}
dimensions:
  location:
    sql: '"city"'
    format: '{{orders.city.value}}, {{orders.country.value}}'
```

<Note>
  When used on a string or other non-number field, the resolved string is returned as **plain text** — it is not processed as Markdown HTML. If you need Markdown rendering in table cells (bold text, links, images), use the [`markdown`](/modeling/dimensions/parameters/markdown) parameter instead.
</Note>

Mustache templates in `format` can be made reusable using [`custom_formats`](/modeling/models/custom-formats) or [`constants`](#constants-in-formats), the same as any other format string.

### Conditional formats

Conditional formats apply different format strings depending on a runtime value — for example, formatting a `revenue` measure with the right currency symbol based on a `currency_code` dimension, or showing different decimal precision based on a user attribute.

Define a `depends_on` source and an ordered list of `conditions` using [Omni filter syntax](/modeling/filters):

| Source           | Resolves at            | Use when                                            |
| ---------------- | ---------------------- | --------------------------------------------------- |
| `field`          | Display time (per row) | The format depends on a value in the query results  |
| `user_attribute` | Query time             | The format depends on the user running the query    |
| `filter`         | Query time             | The format depends on a filter applied to the query |

The first matching condition determines the format. If no condition matches, the `else` format is used. See the [`custom_formats` documentation](/modeling/models/custom-formats#conditional-properties) for a complete list of properties.

```yaml title="Conditional format based on a field value" theme={null}
dimensions:
  currency_code:
    sql: '"currency_code"'
measures:
  revenue:
    sql: '"amount"'
    aggregate_type: sum
    format:
      depends_on:
        field: currency_code
        conditions:
          - condition:
              is: "USD"
            value: usdcurrency_0
          - condition:
              is: "GBP"
            value: gbpcurrency_0
        else: currency_0
```

```yaml title="Conditional format with numeric conditions" theme={null}
dimensions:
  age:
    sql: '"age"'
measures:
  total:
    sql: '"amount"'
    aggregate_type: sum
    format:
      depends_on:
        field: age
        conditions:
          - condition:
              greater_than: "18"
            value: "#,##0.00"
          - condition:
              between:
                - 10
                - 18
            value: "#,##0"
        else: "0"
```

```yaml title="Conditional format based on a user attribute" theme={null}
revenue:
  sql: '"amount"'
  aggregate_type: sum
  format:
    depends_on:
      user_attribute: preferred_currency
      conditions:
        - condition:
            is: "USD"
          value: usdcurrency_2
        - condition:
            is: "EUR"
          value: eurcurrency_2
      else: currency_2
```

```yaml title="Conditional format based on a filter value" theme={null}
revenue:
  sql: '"amount"'
  aggregate_type: sum
  format:
    depends_on:
      filter: currency_filter
      conditions:
        - condition:
            is: "USD"
          value: usdcurrency_2
        - condition:
            is: "GBP"
          value: gbpcurrency_2
      else: currency_2
```

```yaml title="Branch formats referencing model constants" theme={null}
constants:
  high_precision:
    value: "#,##0.0000"
  low_precision:
    value: "#,##0.0"

measures:
  measurement:
    sql: '"value"'
    aggregate_type: avg
    format:
      depends_on:
        field: unit_type
        conditions:
          - condition:
              is: "scientific"
            value: "@{high_precision}"
          - condition:
              is: "summary"
            value: "@{low_precision}"
      else: "@{low_precision}"
```

```yaml title="Reporting currency filter driving named formats" theme={null}
filters:
  reporting_currency:
    type: string
    suggestion_list:
      - value: converted_EUR
        label: Converted to EUR
      - value: converted_USD
        label: Converted to USD

measures:
  revenue_display:
    sql: '"amount"'
    aggregate_type: sum
    format:
      depends_on:
        filter: reporting_currency
        conditions:
          - condition:
              is: converted_EUR
            value: eurcurrency
          - condition:
              is: converted_USD
            value: usdcurrency
      else: usdcurrency
```

### Reusable formats (`custom_formats`)

Reusable formats are format objects defined in a model file using the [`custom_formats`](/modeling/models/custom-formats) parameter. They let you centrally manage format definitions and apply them consistently across multiple dimensions and measures.

Reusable formats can include any valid format type — named formats, Excel-style strings, Mustache templates, or conditional formats.

#### Referencing custom formats

Reference a reusable format using either a plain string or explicit object syntax:

**Plain string** (recommended):

```yaml theme={null}
<field_name>:
  format: <custom_format_name>
```

**Explicit object**:

```yaml theme={null}
<field_name>:
  format:
    custom_format: <custom_format_name>
```

See the [`custom_formats`](/modeling/models/custom-formats) parameter page for syntax, properties, and examples.

## Locale and number formatting

The [`default_numeric_locale`](/modeling/models/default-numeric-locale) model parameter controls how all formatted numbers are displayed — including the thousands delimiter, decimal delimiter, and default currency symbol. When you set a locale, every named format and Excel-style string in that model respects the locale's conventions automatically.

| Locale            | Thousands   | Decimal | Default currency | `currency_2` renders as |
| ----------------- | ----------- | ------- | ---------------- | ----------------------- |
| `en_US` (default) | `,`         | `.`     | `$`              | \$1,234.50              |
| `en_GB`           | `,`         | `.`     | `£`              | £1,234.50               |
| `fi_FI`           | ` ` (space) | `,`     | `€`              | €1 234,50               |
| `fr_FR`           | ` ` (space) | `,`     | `€`              | €1 234,50               |
| `de_DE`           | `.`         | `,`     | `€`              | €1.234,50               |
| `ja_JP`           | `,`         | `.`     | `¥`              | ¥1,234.50               |
| `br_BR`           | `.`         | `,`     | `R$`             | R\$1.234,50             |
| `nl_NL`           | `.`         | `,`     | `€`              | €1.234,50               |
| `pt_PT`           | `.`         | `,`     | `€`              | €1.234,50               |

### Locale interaction with format types

* [**Named formats**](#named-formats) (`currency_2`, `accounting_0`, etc.) — The locale's default currency symbol is used when no currency prefix is specified. Prefixed formats like `usdcurrency_2` override the locale's default symbol.
* [**Excel-style strings**](#excel-style-strings) (`#,##0.00`) — the `#`, `,`, `.` tokens are locale-aware. A format of `#,##0.00` renders `1.234,50` under `de_DE`.
* [**Currency-prefixed named formats**](#named-formats) (`gbpcurrency_2`, `jpyaccounting_0`) — Always use the specified currency symbol, regardless of locale. The delimiter and decimal conventions still come from the locale.

## Durations and wallclock-style times

Timestamp dimensions should use strftime-style strings (they must include `%` in the format). See [Time formats](/modeling/models/format-values#time-formats).

For **numeric durations** stored as milliseconds (or seconds) that you want to display as hours, minutes, or seconds:

<Steps>
  <Step>
    Convert the raw value to a fraction of a day (divide milliseconds by `86400000`). This will get the fraction that Excel-style time format codes expect.
  </Step>

  <Step>
    Apply a format string using either:

    * An [**Excel-style string**](#excel-style-strings) (possibly through a [model constant](/modeling/models/constants)), or
    * A [**conditional format**](#conditional-formats) that picks a shorter or longer pattern based on how large the duration is (for example, show `h:mm:ss` when duration is at least 1 hour, otherwise `m:ss`).

    <Warning>
      `h` displays clock hours (wraps at 24). If your durations can exceed 24 hours, use `[h]` for elapsed hours — for example, `[h]:mm:ss` renders 25 hours as `25:00:00` instead of `1:00:00`. The same applies to `[m]` for elapsed minutes.
    </Warning>
  </Step>
</Steps>

```yaml title="Duration dimension: scale ms to Excel day fraction" theme={null}
dimensions:
  total_duration_ms:
    sql: '"total_duration_ms"'

  duration_as_excel_day:
    sql: ${total_duration_ms} / 86400000.0
    label: Total duration
    format:
      depends_on:
        field: total_duration_ms
        conditions:
          - condition:
              greater_than_or_equal_to: 3600000
            value: 'h "hr" mm "min" ss.0 "sec"'
          - condition:
              greater_than_or_equal_to: 60000
            value: 'm "min" ss.00 "sec"'
      else: 'ss.000 "sec"'
```

Adjust the thresholds (`3600000` ms = 1 hour, `60000` ms = 1 minute) to control when the display switches between hour-, minute-, and second-scale patterns.


# ignored_schemas - Model files
Source: https://docs.omni.co/modeling/models/ignored-schemas

Excludes a list of schemas from workbooks.

<Warning>
  This parameter can't be used if [`included_schemas`](/modeling/models/included-schemas) is in use.
</Warning>

Excludes specific schemas from use in workbooks. Listed schemas will still be available for use in SQL queries.

<Note>
  Topics whose `base_view` is in an ignored schema are automatically hidden in workbooks and excluded from model validation. No manual topic ignoring is required.
</Note>

## Syntax

```yaml theme={null}
# Values can be provided as an indented list
ignored_schemas:
  - <schema_one>
  - <schema_two>

# Or as a comma-delimited list
ignored_schemas: [<schema_one>, <schema_two>]
```

## Properties

<ParamField type="string[]">
  A list of schema names to exclude from use in workbooks. Each value must be the name of a schema in the underlying database connection.
</ParamField>

## Examples

```yaml theme={null}
ignored_schemas:
  - information_schema
```


# ignored_views - Model files
Source: https://docs.omni.co/modeling/models/ignored-views

Excludes specific views from use in workbooks.

<Warning>
  This parameter can't be used if [`included_views`](/modeling/models/included-views) is in use.
</Warning>

Excludes specific views from use in workbooks. Listed views will still be available for use in SQL queries.

<Note>
  Topics whose `base_view` is listed in `ignored_views` are automatically hidden in workbooks and excluded from model validation. No manual topic ignoring is required.
</Note>

## Syntax

```yaml theme={null}
# Values can be provided as an indented list
ignored_views:
  - users
  - main.products        # Schema and view separated by .
  - main__customers      # Schema and view separated by __

# Or as a comma-delimited list
ignored_views: [users, products]
```

## Properties

<ParamField type="string[]">
  A list of view names to exclude from use in workbooks. Each value must be the name of a view in the underlying database connection.

  Individual view names must be fully qualified (`<schema>.<view>` or `<schema>__<view>`), or you can use wildcard syntax (`\*`) to match multiple views within a schema.
</ParamField>

## Examples

```yaml theme={null}
ignored_views:
  - users
  - main.products
  - main__customers
```


# included_schemas - Model files
Source: https://docs.omni.co/modeling/models/included-schemas

Includes only the listed schemas for use in workbooks.

<Warning>
  This parameter can't be used if [`ignored_schemas`](/modeling/models/ignored-schemas) is in use.
</Warning>

Includes only the listed schemas for use in workbooks. Schemas that aren't included will still be available for use in SQL queries.

<Note>
  Topics whose `base_view` is in a schema not listed in `included_schemas` are automatically hidden in workbooks and excluded from model validation. No manual topic ignoring is required.
</Note>

## Syntax

```yaml theme={null}
# Values can be provided as an indented list
included_schemas:
  - <schema_one>
  - <schema_two>

# Or as a comma-delimited list
included_schemas: [<schema_one>, <schema_two>]
```

## Properties

<ParamField type="string[]">
  A list of schema names to include for use in workbooks. Each value must be the name of a schema in the underlying database connection.
</ParamField>

## Examples

```yaml theme={null}
included_schemas:
  - marketing
  - sales
```


# included_views - Model files
Source: https://docs.omni.co/modeling/models/included-views

Defines a list of views from the database schema to include in the model.

<Warning>
  This parameter can't be used if [`ignored_views`](/modeling/models/ignored-views) is in use.
</Warning>

Defines a list of views from the database schema to include in the model. Views that aren't included can't be referenced when modeling.

<Note>
  Topics whose `base_view` is not in the `included_views` list are automatically hidden in workbooks and excluded from model validation. No manual topic ignoring is required.
</Note>

## Syntax

```yaml theme={null}
# Values can be provided as an indented list
included_views:
  - users
  - main.products
  - main__customers

# Or as a comma-delimited list
included_views: [users, products]
```

## Properties

<ParamField type="string[]">
  A list of view names to include for use in workbooks. Each value must be the name of a view in the underlying database connection.

  Individual view names must be fully qualified (`<schema>.<view>` or `<schema>__<view>`), or you can use wildcard syntax (`\*`) to match multiple views within a schema.
</ParamField>

## Examples

```yaml theme={null}
included_views:
  - users
  - main.products
  - main__customers
```


# Configuring your models
Source: https://docs.omni.co/modeling/models/index

Model files are used to define configuration for the analytical environment (topics, views, and so on) associated with a specific model.

| Parameter                                                                                         | Description                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [access\_grants](/modeling/models/access-grants)                                                  | Limits user access to a particular field (dimension or measure) through user attributes.                                                                                                   |
| [ai\_chat\_topics](/modeling/models/ai-chat-topics)                                               | Controls the topics that are available to the Omni Agent, Chat with Content, and embedded chat instances.                                                                                  |
| [ai\_context](/modeling/models/ai-context)                                                        | Sets context for the Omni Agent that is applicable for the entire model.                                                                                                                   |
| [ai\_settings](/modeling/models/parameters/ai-settings)                                           | Configure AI behavior for the model, including query scope, analysis validation, conversation context management, model thinking levels, and tool availability.                            |
| [auto\_run](/modeling/models/auto-run)                                                            | Forces workbook queries to require a run click to return new results.                                                                                                                      |
| [auto\_run\_dashboard](/modeling/models/auto-run-dashboard)                                       | Forces dashboards to require a run click before filter and control changes re-run their queries.                                                                                           |
| [cache\_policies](/modeling/models/cache-policies)                                                | Defines cache policies for the model.                                                                                                                                                      |
| [calcs\_default\_pushdown](/modeling/models/calcs-default-pushdown)                               | Determines if calculations that reference a range are evaluated before the row limit by default.                                                                                           |
| [compute\_routing](/modeling/models/compute-routing)                                              | Routes different job types to different warehouses or slot reservations.                                                                                                                   |
| [constants](/modeling/models/constants)                                                           | Define reusable string values that can be referenced throughout your model.                                                                                                                |
| [custom\_formats](/modeling/models/custom-formats)                                                | Defines reusable format objects that can be referenced in dimension and measure format parameters.                                                                                         |
| [default\_cache\_policy](/modeling/models/default-cache-policy)                                   | Defines the default cache policy for the model.                                                                                                                                            |
| [default\_group\_by](/modeling/models/default-group-by)                                           | Controls whether measure-less queries get an implicit GROUP BY.                                                                                                                            |
| [default\_numeric\_locale](/modeling/models/default-numeric-locale)                               | Defines global number formatting in the model.                                                                                                                                             |
| [default\_row\_limit](/modeling/models/default-row-limit)                                         | Sets the default row limit for new queries within the model.                                                                                                                               |
| [default\_timeframes](/modeling/models/default-timeframes)                                        | Sets the default timeframes available for date and time fields across the model.                                                                                                           |
| [default\_topic\_access\_filters](/modeling/models/default-topic-access-filters)                  | Defines default access filters for topics in the model.                                                                                                                                    |
| [default\_topic\_required\_access\_grants](/modeling/models/default-topic-required-access-grants) | Defines a default required access grant for all topics contained in a model.                                                                                                               |
| [dynamic\_schemas](/modeling/models/dynamic-schemas)                                              | Creates a copy of the specified schema as a virtual schema.                                                                                                                                |
| [dynamic\_shared\_extensions](/modeling/models/dynamic-shared-extensions)                         | Dynamically extends the model based on user attribute values, enabling user-specific model customization.                                                                                  |
| [extends](/modeling/models/extends)                                                               | Enables extending a model.                                                                                                                                                                 |
| [facet\_workbook\_filters](/modeling/models/facet-workbook-filters)                               | Facets all filter suggestions in the workbook to the current filter selections.                                                                                                            |
| [fiscal\_month\_offset](/modeling/models/fiscal-month-offset)                                     | Sets a fiscal calendar in Omni and enables adding fiscal time metrics to time dimension groups and filters in the UI.                                                                      |
| [ignored\_schemas](/modeling/models/ignored-schemas)                                              | Excludes a list of schemas from workbooks.                                                                                                                                                 |
| [ignored\_views](/modeling/models/ignored-views)                                                  | Excludes specific views from use in workbooks.                                                                                                                                             |
| [included\_schemas](/modeling/models/included-schemas)                                            | Includes only the listed schemas for use in workbooks.                                                                                                                                     |
| [included\_views](/modeling/models/included-views)                                                | Defines a list of views from the database schema to include in the model.                                                                                                                  |
| [sample\_queries](/modeling/models/sample-queries)                                                | Defines a list of sample queries that could be performed using the topics in the model.                                                                                                    |
| [sets](/modeling/models/sets)                                                                     | Defines a list of fields that can be referenced in parameters that accept lists of fields.                                                                                                 |
| [skills](/modeling/models/skills)                                                                 | Defines a set of instructions for the Omni Agent that users can trigger with a button click. **Scheduled to be deprecated in favor of [skills](/ai/skills) created from the Skills page**. |
| [slot\_reservation](/modeling/models/slot-reservation)                                            | Specifies a dedicated slot for queries in a Google BigQuery-backed model to use.                                                                                                           |
| [sql\_preamble](/modeling/models/sql-preamble)                                                    | Runs a setup query before executing SQL statements against a model.                                                                                                                        |
| [template](/modeling/models/template)                                                             | Disables the content validator for an abstract model.                                                                                                                                      |
| [topic\_group\_descriptions](/modeling/models/topic-group-descriptions)                           | Defines descriptions for topic groups.                                                                                                                                                     |
| [topics](/modeling/models/topics)                                                                 | Define topics within model files.                                                                                                                                                          |
| [warehouse\_override](/modeling/models/warehouse-override)                                        | Specifies a different warehouse to use for a given workbook or branch.                                                                                                                     |
| [week\_start\_day](/modeling/models/week-start-day)                                               | Defines the day that weeks start on.                                                                                                                                                       |


# allow_ctes - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/allow-ctes

Controls whether the AI can generate CTEs (common table expressions) in its queries, based on user permission levels.

Controls whether the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) can generate CTEs (common table expressions) in their queries.

This setting only applies to AI-generated queries. Hand-written SQL is not affected by this setting.

<Warning>
  **Disabling CTEs is not recommended**. Omni's AI evals are not run in this mode, and CTEs are still governed by your model - they build on top of it, not around it. Turning off CTEs limits what the AI can generate, and Omni will not address reports of the AI failing to produce certain queries as a result.
</Warning>

## Syntax

```yaml theme={null}
ai_settings:
  allow_ctes: <always | never | not_for_restricted_queriers>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="string">
      When the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) can generate CTEs in their queries. Does not apply to hand-written SQL.

      Must be one of the following:

      * `always` - **Default**. The AI can generate CTEs for all users, regardless of whether their role allows direct SQL access.
      * `never` - The AI cannot generate CTEs.
      * `not_for_restricted_queriers` - The AI can generate CTEs for all users with querying access except **Restricted Queriers**.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Disable CTEs for Restricted Queriers" theme={null}
ai_settings:
  allow_ctes: not_for_restricted_queriers
```

```yaml title="Disable CTEs for all users" theme={null}
ai_settings:
  allow_ctes: never
```

```yaml title="Disable CTEs and custom field generation for Restricted Queriers" theme={null}
ai_settings:
  allow_custom_fields: not_for_restricted_queriers
  allow_ctes: not_for_restricted_queriers
```

See [`allow_custom_fields`](/modeling/models/parameters/ai-settings/allow-custom-fields) for more information.


# allow_custom_fields - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/allow-custom-fields

Controls whether the AI can generate custom fields in its queries, based on user permission levels.

Controls whether the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) can generate custom fields in their queries. Custom fields are ad-hoc dimensions and measures that users can create in workbooks with their own calculations.

This setting only applies to AI-generated queries. Hand-written SQL is not affected by this setting.

<Warning>
  **Disabling custom fields is strongly discouraged.** It exists only for scenarios where only governed, model-based reporting is required.

  Omni does not run its AI evals in this mode. Additionally, custom fields are still governed by your model - this means that turning them off substantially limits the AI. Omni will not address reports of it failing to generate certain queries as a result.
</Warning>

## Syntax

```yaml theme={null}
ai_settings:
  allow_custom_fields: <always | never | not_for_restricted_queriers>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="string">
      When the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) can generate custom fields in their queries. Does not apply to hand-written SQL.

      Must be one of the following:

      * `always` - **Default**. The AI can generate custom fields for all users, regardless of whether their role allows direct SQL access.
      * `never` - The AI cannot generate custom fields.
      * `not_for_restricted_queriers` - The AI can generate custom fields for all users with querying access except **Restricted Queriers**.

      <Tip>
        Plain column reference dimensions are allowed even when custom fields are disabled on CTEs. Computed dimensions and all measures will be rejected.
      </Tip>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Disable custom fields for Restricted Queriers" theme={null}
ai_settings:
  allow_custom_fields: not_for_restricted_queriers
```

```yaml title="Disable custom fields for all users" theme={null}
ai_settings:
  allow_custom_fields: never
```

```yaml title="Disable custom fields and CTEs for Restricted Queriers" theme={null}
ai_settings:
  allow_custom_fields: not_for_restricted_queriers
  allow_ctes: not_for_restricted_queriers
```

See [`allow_ctes`](/modeling/models/parameters/ai-settings/allow-ctes) for more information.


# analyze_configuration - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/analyze-configuration

Controls the model and thinking level for complex analytical tasks, such as query and visualization generation.

<Note>
  This setting is only supported for Claude models.
</Note>

Controls the model and thinking level for complex analytical tasks, including query generation, visualization generation, formulas, calculations, AI summary visualization, and the agentic coordinator.

## Syntax

```yaml theme={null}
ai_settings:
  analyze_configuration:
    model: <smartest | standard | fastest | opus | sonnet | haiku>
    thinking: <none | low | medium | high>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="object">
      Controls the model and thinking level for complex analytical tasks, including query generation, visualization generation, formulas, calculations, AI summary visualization, and the agentic coordinator.

      <Expandable title="analyze_configuration properties">
        <ParamField type="string">
          The model tier to use.

          Must be one of the following:

          * **Provider-agnostic** - `smartest`, `standard`, `fastest`
          * **Anthropic-specific, supported for backwards compatibility** - `opus`, `sonnet`, `haiku`
        </ParamField>

        <ParamField type="string">
          The thinking level, which controls how much reasoning the model performs before responding. Higher levels use more tokens but can improve accuracy on complex tasks.

          Must be one of the following: `none`, `low`, `medium`, `high`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Set model and thinking level (Anthropic-specific)" theme={null}
ai_settings:
  analyze_configuration:
    model: opus
    thinking: medium
```

```yaml title="Set model and thinking level (provider-agnostic)" theme={null}
ai_settings:
  analyze_configuration:
    model: smartest
    thinking: medium
```


# build_configuration - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/build-configuration

Controls the model and thinking level for model-building tasks, such as the modeling subagent, dashboard creation, and topic metadata generation.

<Note>
  This setting is only supported for Claude models.
</Note>

Controls the model and thinking level for model-building tasks, including the modeling subagent, [AI dashboard creation](/ai/chat#creating-dashboards), [learn from conversation](/ai/learn-from-conversation), and topic metadata generation.

## Syntax

```yaml theme={null}
ai_settings:
  build_configuration:
    model: <smartest | standard | fastest | opus | sonnet | haiku>
    thinking: <none | low | medium | high>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="object">
      Controls the model and thinking level for model-building tasks, including the modeling subagent, [AI dashboard creation](/ai/chat#creating-dashboards), [learn from conversation](/ai/learn-from-conversation), and topic metadata generation.

      <Expandable title="build_configuration properties">
        <ParamField type="string">
          The model tier to use.

          Must be one of the following:

          * **Provider-agnostic** - `smartest`, `standard`, `fastest`
          * **Anthropic-specific, supported for backwards compatibility** - `opus`, `sonnet`, `haiku`
        </ParamField>

        <ParamField type="string">
          The thinking level, which controls how much reasoning the model performs before responding.

          Must be one of the following: `none`, `low`, `medium`, `high`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Set thinking level (Anthropic-specific)" theme={null}
ai_settings:
  build_configuration:
    model: opus
    thinking: high
```

```yaml title="Set model and thinking level (provider-agnostic)" theme={null}
ai_settings:
  build_configuration:
    model: standard
    thinking: high
```


# conversation_prune_length - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/conversation-prune-length

Controls how aggressively Claude prunes conversation history to balance cost optimization with context preservation.

<Note>
  This setting is only supported for Claude models.
</Note>

Controls how aggressively Claude manages conversation context by pruning conversation history when LLM token limits are reached. This setting allows you to balance cost optimization against context preservation for longer conversations.

## Syntax

```yaml theme={null}
ai_settings:
  conversation_prune_length: <short | medium | max | long>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="string">
      Controls how aggressively Claude manages conversation context by pruning conversation history when LLM token limits are reached.

      Must be one of the following values:

      | Value    | Pruning triggers at | Description                                          |
      | -------- | ------------------- | ---------------------------------------------------- |
      | `short`  | 75,000 tokens       | Aggressive pruning, cost-optimized                   |
      | `medium` | 125,000 tokens      | Balanced approach                                    |
      | `long`   | 175,000 tokens      | **Default**. Preserves most context.                 |
      | `max`    | 175,000 tokens      | Reserved for future expansion to >200k context sizes |

      When conversation context reaches the specified token threshold, Claude automatically prunes older messages from the conversation history to stay within limits while preserving the most recent and relevant context.

      <Note>
        The `max` value currently matches `long` (175k LLM tokens) but is reserved to allow future expansion to >200k context sizes. Using `max` as the default ensures you'll automatically benefit from increased context limits as they become available, while `long` will remain at 175k LLM tokens.
      </Note>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Optimize for cost with aggressive context pruning" theme={null}
ai_settings:
  conversation_prune_length: short
```

```yaml title="Balance cost and context preservation" theme={null}
ai_settings:
  conversation_prune_length: medium
```

```yaml title="Preserve maximum context" theme={null}
ai_settings:
  conversation_prune_length: max
```


# disabled_tools - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/disabled-tools

Disables specific tools in the AI chat interface, such as dashboard creation, Slack, Google Calendar, GitHub, visualize, forecasting, or learn from conversation.

Disables specific tools in the AI chat interface when the model is in use. Auxiliary tools, integration tools, and certain generation capabilities (like dashboard creation) can be disabled. Core query generation tools remain available to prevent breaking basic chat functionality.

## Syntax

```yaml theme={null}
ai_settings:
  disabled_tools:
    - <tool_name>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="string[]">
      A list of auxiliary tools to disable in the chat interface. Valid values are:

      | Tool                         | What it disables                                                    |
      | ---------------------------- | ------------------------------------------------------------------- |
      | `create_dashboard_from_chat` | [Dashboard creation from chat](/ai/chat#creating-dashboards)        |
      | `fetch_github_file`          | Fetching [GitHub](/integrations/ai/github) file content             |
      | `fetch_google_drive_file`    | Fetching [Google Drive](/integrations/ai/google-drive) file content |
      | `fetch_slack_thread`         | Fetching [Slack](/integrations/ai/slack) thread content             |
      | `generate_forecast`          | [Forecasting](/ai/forecasting)                                      |
      | `learn_from_conversation`    | [Learn from conversation](/ai/learn-from-conversation)              |
      | `search_github_code`         | [GitHub](/integrations/ai/github) repository search                 |
      | `search_google_calendar`     | [Google Calendar](/integrations/ai/google-calendar) search          |
      | `search_google_drive`        | [Google Drive](/integrations/ai/google-drive) search                |
      | `search_slack_messages`      | [Slack](/integrations/ai/slack) channel search                      |
      | `visualize`                  | Automatic chart generation                                          |
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Disable dashboard creation from chat" theme={null}
ai_settings:
  disabled_tools:
    - create_dashboard_from_chat
```

```yaml title="Disable forecasting" theme={null}
ai_settings:
  disabled_tools:
    - generate_forecast
```

```yaml title="Disable a single AI tool" theme={null}
ai_settings:
  disabled_tools:
    - visualize
```

```yaml title="Disable multiple AI tools" theme={null}
ai_settings:
  disabled_tools:
    - learn_from_conversation
    - visualize
    - search_google_calendar
```

```yaml title="Disable Slack integration tools" theme={null}
ai_settings:
  disabled_tools:
    - search_slack_messages
    - fetch_slack_thread
```


# ai_settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/index

Configure AI behavior for the model, including query scope, analysis validation, context management, and AI model and thinking settings.

Configure AI behavior for the model, including query scope, analysis validation, context management, and AI model and thinking settings.

Use this parameter to:

* **Expand query scope** — Let the AI query any view in the model - not just topics - for more unconstrained analysis
* **Enable analysis validation** — Have the AI automatically check its work for errors before returning results
* **Manage conversation context** — Control how aggressively Claude prunes conversation history to balance cost optimization with context preservation
* **Tune model and thinking levels** — **Supported for Claude models only.** Control the tradeoff between speed and accuracy for different task types (analysis, model building, summarization)
* **Disable specific AI tools** — Restrict the Blobby chat assistant from using specific tools like dashboard creation, Slack, Google Calendar, GitHub, visualize, or learn from conversation
* **Control AI-generated custom fields and CTEs** — Restrict whether the AI can generate custom fields and CTEs (common table expressions) based on user permission levels

## Syntax

```yaml theme={null}
ai_settings:
  <sub-parameters>:
  ...
```

## Properties

<ParamField type="object">
  The parent object containing all AI settings sub-parameters:

  | Parameter                                                                                                  | Description                                                                                                                                          |
  | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
  | [allow\_ctes](/modeling/models/parameters/ai-settings/allow-ctes)                                          | Controls whether the AI can generate CTEs (common table expressions) in its queries, based on user permission levels.                                |
  | [allow\_custom\_fields](/modeling/models/parameters/ai-settings/allow-custom-fields)                       | Controls whether the AI can generate custom fields in its queries, based on user permission levels.                                                  |
  | [analyze\_configuration](/modeling/models/parameters/ai-settings/analyze-configuration)                    | Controls the model and thinking level for complex analytical tasks, such as query and visualization generation.                                      |
  | [build\_configuration](/modeling/models/parameters/ai-settings/build-configuration)                        | Controls the model and thinking level for model-building tasks, such as the modeling subagent, dashboard creation, and topic metadata generation.    |
  | [conversation\_prune\_length](/modeling/models/parameters/ai-settings/conversation-prune-length)           | Controls how aggressively Claude prunes conversation history to balance cost optimization with context preservation.                                 |
  | [disabled\_tools](/modeling/models/parameters/ai-settings/disabled-tools)                                  | Disables specific tools in the AI chat interface, such as dashboard creation, Slack, Google Calendar, GitHub, visualize, or learn from conversation. |
  | [query\_all\_views\_and\_fields](/modeling/models/parameters/ai-settings/query-all-views-and-fields)       | Controls whether the AI can query any view in the model or only views organized within topics.                                                       |
  | [simple\_summarize\_configuration](/modeling/models/parameters/ai-settings/simple-summarize-configuration) | Controls the model and thinking level for lightweight tasks, such as summaries, documentation search, and field metadata.                            |
  | [validate\_analysis](/modeling/models/parameters/ai-settings/validate-analysis)                            | Controls whether the AI automatically validates its analysis for errors before returning results.                                                    |
</ParamField>

## Examples

```yaml title="Expand query scope and validate analysis" theme={null}
ai_settings:
  query_all_views_and_fields: enabled
  validate_analysis: enabled
```

```yaml title="Override model categories (provider-agnostic)" theme={null}
ai_settings:
  analyze_configuration:
    model: smartest
    thinking: medium
  build_configuration:
    model: standard
    thinking: high
  simple_summarize_configuration:
    model: fastest
    thinking: low
```

```yaml title="Restrict AI capabilities for Restricted Queriers" theme={null}
ai_settings:
  allow_custom_fields: not_for_restricted_queriers
  allow_ctes: not_for_restricted_queriers
```


# query_all_views_and_fields - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/query-all-views-and-fields

Controls whether the AI can query any view in the model or only views organized within topics.

When enabled, the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) can generate queries on any view in the model, not just views that are organized within [topics](/modeling/topics). This is useful when you have ad-hoc tables that users want to query without creating a dedicated topic for each one.

<Tip>
  For curated, self-service analytics, organize your views into [topics](/modeling/topics) and keep `query_all_views_and_fields` disabled. Topics provide better structure, improved performance, and a more guided experience for users.
</Tip>

## Syntax

```yaml theme={null}
ai_settings:
  query_all_views_and_fields: <enabled | disabled | default>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="string">
      <Note>
        If your instance was created **on or before** March 5, 2026, the default behavior is `disabled`. Instances created after this date are `enabled` by default.
      </Note>

      Controls whether the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) can generate queries on any view in the model, not just views that are organized within [topics](/modeling/topics).

      Must be one of the following:

      * `default` - Uses Omni's default behavior (`enabled`)
      * `disabled` - The AI can only query views organized within topics
      * `enabled` - The AI can query any view in the model. This means:
        * The AI can use any view in the model as a starting point for queries
        * The AI can discover and join other views that are related to the selected view
        * Users don't need to specify a topic when asking the AI to generate queries

      <Tip>
        When using the [Generate a query API](/api/ai/generate-a-query), this setting must be enabled and the `queryAllViews` parameter must be set to `true` to allow querying views outside of topics. The Omni Agent and Workbook Agent in the UI apply this behavior automatically when the setting is enabled.
      </Tip>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Enable querying all views" theme={null}
ai_settings:
  query_all_views_and_fields: enabled
```

```yaml title="Restrict AI to topic views only" theme={null}
ai_settings:
  query_all_views_and_fields: disabled
```


# simple_summarize_configuration - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/simple-summarize-configuration

Controls the model and thinking level for lightweight tasks, such as summaries, documentation search, and field metadata.

<Note>
  **Supported for Claude models only.**
</Note>

Controls the Claude model and thinking level for lightweight tasks, including subtitle and description summaries, documentation search, and field metadata.

## Syntax

```yaml theme={null}
ai_settings:
  simple_summarize_configuration:
    model: <smartest | standard | fastest | opus | sonnet | haiku>
    thinking: <none | low | medium | high>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="object">
      Controls the Claude model and thinking level for lightweight tasks, including subtitle and description summaries, documentation search, and field metadata.

      <Expandable title="simple_summarize_configuration properties">
        <ParamField type="string">
          The model tier to use.

          Must be one of the following:

          * **Provider-agnostic** - `smartest`, `standard`, `fastest`
          * **Anthropic-specific, supported for backwards compatibility** - `opus`, `sonnet`, `haiku`
        </ParamField>

        <ParamField type="string">
          The thinking level, which controls how much reasoning the model performs before responding.

          Must be one of the following: `none`, `low`, `medium`, `high`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Set thinking level (Anthropic-specific)" theme={null}
ai_settings:
  simple_summarize_configuration:
    model: haiku
    thinking: low
```

```yaml title="Set model and thinking level (provider-agnostic)" theme={null}
ai_settings:
  simple_summarize_configuration:
    model: fastest
    thinking: low
```


# validate_analysis - AI settings
Source: https://docs.omni.co/modeling/models/parameters/ai-settings/validate-analysis

Controls whether the AI automatically validates its analysis for errors before returning results.

When enabled, the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) automatically validate their analysis before returning results to users. The AI checks for critical errors such as degenerate pivot results, incorrect date ranges, or hallucinated calculations, and self-corrects issues before the user sees them.

## Syntax

```yaml theme={null}
ai_settings:
  validate_analysis: <enabled | disabled | default>
```

## Properties

<ParamField type="object">
  An object that contains various AI settings. See [`ai_settings`](/modeling/models/parameters/ai-settings) for more information.

  <Expandable title="ai_settings properties">
    <ParamField type="string">
      Controls whether the [Omni Agent](/ai/chat) and [Workbook Agent](/ai/queries) automatically validate their analysis before returning results.

      Must be one of the following:

      * `default` - Uses the default behavior (`disabled`)
      * `disabled` - Validation is never performed
      * `enabled` - Validation is always performed after the AI completes analytical work. When enabled, the AI will:
        * Review its most recent queries and calculations for critical errors
        * Check for common issues such as:
          * Wrong topics selected
          * Incorrect date filters (e.g., period-over-period date ranges)
          * Degenerate calculation results (e.g., all zeros)
          * Hallucinated numbers not supported by the data
          * Malformed pivots or aggregations
        * Automatically fix issues if critical errors are detected
        * Display a validation indicator in the chat interface

      <Note>
        Validation runs automatically at the end of each analytical turn. To prevent infinite loops, validation is limited to a maximum of 2-3 attempts per turn.
      </Note>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Enable AI analysis validation" theme={null}
ai_settings:
  validate_analysis: enabled
```

```yaml title="Disable AI analysis validation" theme={null}
ai_settings:
  validate_analysis: disabled
```


# sample_queries - Model files
Source: https://docs.omni.co/modeling/models/sample-queries

Defines a list of sample queries that could be performed using the topics in the model.

Defines a list of sample queries that could be performed using the topics in the model, which is used:

* **To present example queries** when a model is selected in the workbook or using the [embedded version of the Omni Agent](/embed/customization/ai-chat).

  To hide the query, set the `hidden` parameter to `true`.

* [**By the Omni Agent to improve results.**](/ai/chat) To exclude the query from the model's AI context, set the `exclude_from_ai_context` to `true`.

You can also add [sample queries to individual topics](/modeling/topics/parameters/sample-queries).

## Syntax

```yaml theme={null}
sample_queries:
  <query_name>:
    query:
      fields: [ "<field_one>", "<field_two>", ... ]
      base_view: "<base_view_name>"
      calculations:
        <calculation_name>:
          sql: "<sql_expression>"
      limit: <number>
      sorts:
        - field: "<field_name>"
          desc: true/false
      topic: "<topic_name>"
    description: "<query_description>"
    hidden: true/false
    prompt: "<natural_language_prompt>"
    ai_context: "<ai_context_description>"
    exclude_from_ai_context: true/false
```

## Properties

<ParamField type="object">
  A map of queries, where each key is the name of a sample query.

  <Expandable title="sample_queries properties">
    <ParamField type="object">
      The name of the sample query (e.g., "Summary Stats"). Each query is defined as a key in the `sample_queries` object.

      <Expandable title="query properties">
        <ParamField type="object">
          The query definition object containing the structure of the query to be executed.

          <Expandable title="query properties">
            <ParamField type="string[]">
              List of fields to include in the query. Can reference model fields or calculations.
            </ParamField>

            <ParamField type="string">
              The base view or topic to query from.
            </ParamField>

            <ParamField type="object">
              Optional calculations to include in the query. Each calculation is defined with a name and SQL expression.

              <Expandable title="calculation properties">
                <ParamField type="string">
                  The SQL expression for the calculation.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="number">
              Maximum number of rows to return.
            </ParamField>

            <ParamField type="object[]">
              List of fields to sort the results by.

              <Expandable title="sort properties">
                <ParamField type="string">
                  The field name to sort by.
                </ParamField>

                <ParamField type="boolean">
                  When set to `true`, sorts the field in descending order. Omit or set to `false` to sort in ascending order.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="string">
              The name of the topic used in the query, if applicable.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          A human-readable description of what the query does or what insights it provides.
        </ParamField>

        <ParamField type="boolean">
          When set to `true`, hides the query from being presented as an example query in the workbook or embedded Omni Agent.
        </ParamField>

        <ParamField type="string">
          A natural language prompt that represents how a user might ask for this query. Used by the Omni Agent.
        </ParamField>

        <ParamField type="string">
          Additional context to help the Omni Agent understand how to use this query or what it demonstrates.
        </ParamField>

        <ParamField type="boolean">
          When set to `true`, excludes this query from the model's AI context, preventing the AI from using it as a reference.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
sample_queries:
  Summary Stats:
    query:
      fields: [ order_items.sale_price_sum, users.count, calc_1 ]
      base_view: order_items
      calculations:
        calc_1:
          sql: OMNI_FX_SAFE_DIVIDE(${order_items.sale_price_sum}, ${users.count})
      limit: 1000
      sorts:
        - field: order_items.sale_price_sum
          desc: true
      topic: order_items
    description: Total Revenue, Users and Revenue per User
    hidden: false
    prompt: show me total revenue, count of users and revenue per user
    ai_context: uses a calculation to compute avg. revenue per user
    exclude_from_ai_context: false
```


# sets - Model files
Source: https://docs.omni.co/modeling/models/sets

Defines a list of fields that can be referenced in parameters that accept lists of fields.

Defines a list of fields that can be referenced in parameters that accept lists of fields, such as [`drill_fields`](/modeling/measures/parameters/drill-fields).

Once defined, you can reference a set with `[ set:<set_name> ]`. Refer to the [Examples](#examples) section for more information.

## Syntax

```yaml theme={null}
sets:
  <set_name>:
    - "<view_name>.<field_name>"
    - "<view_name>.<field_name>"
    ...
```

## Properties

<ParamField type="string[]">
  A name that uniquely identifies the field set. The value is an array of field references in the format `view_name.field_name`.
</ParamField>

## Examples

```yaml title="Define a field set named revenue" theme={null}
sets:
  revenue:
    - "order_items.id"
    - "order_items.item_id"
    - "order_items.sales_price"
```

```yaml title="Reference the revenue set" theme={null}
measures:
  count:
    aggregate_type: count
    drill_fields: [ set:revenue ]
```


# skills - Model files
Source: https://docs.omni.co/modeling/models/skills

Defines a set of instructions for the Omni Agent that users can trigger with a button click.

<Note>
  Model-defined skills (skills defined with this parameter) will be deprecated in the near future. Skills defined using this parameter will continue to work, but going forward, create skills using the Omni Agent or **Skills** page instead. See [AI skills](/ai/skills) for more information.
</Note>

When triggered, the Omni Agent follows those instructions — querying data, summarizing results, interacting with the user, or walking through a multi-step process — all without the user needing to write a prompt. Each defined skill will display as a button in the [Omni Agent](/ai/chat).

See the [Skills guide](/ai/skills) for more information about this feature, including use cases and best practices.

## Syntax

```yaml theme={null}
skills:
  <skill_id>:
    label: <string>
    input: |
      <string>
    description: |
      <string>
```

## Properties

<ParamField type="object">
  A map of skills, each defined with a unique `skill_id`.

  <Expandable title="skill properties">
    <ParamField type="string">
      A unique name for the skill. Use underscores for spaces.

      <Expandable title="skill_id properties">
        <ParamField type="string">
          The display name shown on the skill button. Keep this short — aim for 2-4 words that clearly describe the task.
        </ParamField>

        <ParamField type="string">
          An opening message that sets the initial interaction. This is sent to the AI before the `description` and is useful for:

          * Greeting the user and explaining what the skill does
          * Asking the user for input before proceeding (e.g., an account name or date range)

          When `input` is set, the AI will typically respond to the `input` first, then use the `description` as its instructions for the rest of the conversation.
        </ParamField>

        <ParamField type="string">
          The instructions sent to the AI when the skill is triggered. This can range from a single sentence to a detailed, multi-step prompt with specific output formats, decision logic, and references to topics.

          Write this as if you're instructing an analyst: be specific about which data to query, how to structure the output, and what steps to follow.
        </ParamField>

        <ParamField type="string[]">
          Controls skill visibility based on user access grants. Skills with this parameter will only appear to users who hold the required access grants.

          Values must match [`access_grants`](/modeling/models/access-grants) defined in the model file. Supports conditional grant expressions using `|` for OR and `&` for AND conditions.

          **Note**: This controls visibility only. Actual data access at execution time is still enforced by access grants on the underlying topics, fields, and views the skill touches.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<Tip>
  See the [Agent Skills guide](/ai/skills) for additional examples.
</Tip>

```yaml title="A simple one-step query" theme={null}
skills:
  top_customers:
    label: Top Customers
    description: >
      Find the top 20 customers by total lifetime revenue.
      Include customer name, total revenue, order count,
      and date of most recent order. Sort by revenue descending.
```

```yaml title="Skill with required access grants" theme={null}
skills:
  finance_summary:
    label: Finance Summary
    description: >
      Generate a financial summary including revenue, costs, and margins.
    required_access_grants: [ finance ]
```

```yaml title="Skill with conditional access grants" theme={null}
skills:
  regional_analysis:
    label: Regional Analysis
    description: >
      Analyze performance metrics across all regions.
    required_access_grants: [ northwest_region|southwest_region&manager ]
```

```yaml title="Interactive skill" expandable theme={null}
skills:
  account_lookup:
    label: Account Lookup
    input: >
      Ask the user for the name of the account they want to
      look up before proceeding.
    description: >
      Look up information for the account the user specified.

      1. Find all records matching the account name.
         Pull back key fields: account value, status, owner,
         and created date.
      2. Find their recent product usage trends
      3. Find their recent support tickets
      4. Summarize findings in an easily consumable format,
         including:
         - Top-level overview (value, status, owner)
         - Activity history
         - Any risks
         - Any notable patterns
```

```yaml title="Answer product roadmap questions skill" expandable theme={null}
skills:
  product_answers:
      label: Product Roadmap Answers
      input: Greet the user by their first name and offer help with a product question.
      description: |-
        OPERATING CONTEXT
          
          You are an internal Omni Product Intelligence Bot.
          
          You operate inside Omni's internal skill and have read-only access to:
          - Slack messages (especially #product channels)
          - Google Drive (Product roadmap spreadsheet)
          - GitHub Issues topic (bugs and feature requests)
          - Demos topic (engineering demos of new features)
          
          Your purpose is to assist Omni field team members by:
          - Answering questions about roadmap status and feature timelines
          - Surfacing recent discussions and decisions about features
          - Finding relevant engineering demos that showcase upcoming/recent work
          - Reducing back-and-forth with product team for common questions
  
        SUCCESS CRITERIA
  
        A successful response:
        - Clearly answers whether something is on the roadmap and its current status
        - Shows the most recent information available (prioritizing recency)
        - Always includes direct links to sources (Slack messages, Google Docs, GitHub issues, demos)
        - Identifies if the question needs follow-up in #product channel
        - ALWAYS completes the full synthesis step with a definitive answer
  
        EXECUTION STEPS
  
        1) Search Slack Messages
        - Search Slack for messages relevant to the current query.
        - Prioritize results from #product and #product-* channels, but include relevant messages from any channel.
        - Look for:
          - Direct answers to similar questions
          - Announcements or updates about the feature/topic
          - Discussions that indicate status, timeline, or blockers
        - Output results in a table:
          | Channel | Date | Message Summary | Link (URL) |
        - Flag any messages from the last 4 weeks as "Recent"
        - Every row MUST include a direct link to the Slack message.
  
        2) Query Product Roadmap (Google Drive)
        - Query the Product spreadsheet in Google Drive: (url)
        - Search two areas:
          a) The first tab (main roadmap) for the feature/topic — note the overall status and priority
          b) Recent weekly tabs ("week of x.x.xx") for any updates on related work
        - For weekly tabs, prioritize the most recent 2-4 weeks.
        - Output results in a table:
          | Source (Main Roadmap / Week of X.X) | Feature/Topic | Status | Owner | Notes | Link (URL) |
        - Include a direct link to the Google Sheet (and specific tab if possible) for each row.
  
        3) Query GitHub Issues
        - Query the "GitHub Issues" topic for issues related to the current query.
        - Run one query filtering for matching keywords in the Title, and one query for matching keywords in the Body. When filtering, prefer 'contains' filter conditions.
        - Look for both feature requests and bugs related to the topic.
        - Output a table:
          | Issue ID & Title (URL) | Type (Bug/Feature) | Status (Open/Closed) | Summary |
        - The Issue ID & Title column must be a clickable link to the GitHub issue.
        - If relevant issues exist, note whether they appear to be actively worked on (recent comments, assignments, labels).
  
        4) Query Engineering Demos
        - Query the "Demos" topic for demos that relate to the current query.
        - Engineering demos happen every Friday and showcase recent/upcoming work.
        - Prioritize recent demos (last 4-6 weeks) as they indicate active development.
        - Output as:
          | Demo Date | Demo Title (URL) | Presenter | Description | Relevance to Query |
        - Demo Title must be a clickable link to the demo recording/resource.
  
        5) Feature Flags 
        - If it appears the feature is in development or available in beta, check if there is an associated feature flag using the Feature Flag topic
  
        6) Synthesize + Answer (REQUIRED — MUST ALWAYS COMPLETE)
  
        THIS STEP IS MANDATORY. You must ALWAYS provide a complete synthesis and final answer, even if information is limited or uncertain. Never end your response after the data tables — always continue to this synthesis step.
  
        Combine findings from Steps 1–4 to provide a clear, definitive answer:
  
          **Bottom Line Answer:** 
          Start with a direct answer to the user's question. Use one of these formats:
          - "Yes, [feature] is on the roadmap. Here's what I found..."
          - "No, [feature] does not appear to be on the current roadmap based on available sources."
          - "Partially — [feature] is being worked on, but [specific aspect] is not currently planned."
          - "Unknown — I couldn't find clear information, but here's what's related..."
          
          Do NOT skip this section. Do NOT leave the answer ambiguous. Take a position based on available evidence.
          
          **Roadmap Status:** Is this on the roadmap? What's the current priority/timeline?
          
          **Recent Activity:** What's the most recent work or discussion on this topic?
          
          **Key Sources:** List the most relevant sources WITH LINKS. Example:
          - [Slack: #product discussion from 1/10](url)
          - [Kaizeng: Week of 1.6.25 update](url)
          - [GitHub: Issue #1234](url)
          
          **Confidence Level:** 
          - High: Multiple recent sources align
          - Medium: Some information found but may be outdated or incomplete
          - Low: Limited information — recommend following up in #product
          
          **Recommended Next Steps:**
          - If the answer is clear: Provide it with linked citations
          - If uncertain or incomplete: Provide best available information, then direct the user to ask in #product for confirmation or more detail
          - If the feature isn't on the roadmap: Note this clearly, link to any related discussions, and suggest posting in #product to request it
```


# slot_reservation - Model files
Source: https://docs.omni.co/modeling/models/slot-reservation

Specifies a dedicated slot for queries in a Google BigQuery-backed model to use.

<Note>
  Supported only for Google BigQuery connections.
</Note>

Specifies a [dedicated slot](https://cloud.google.com/bigquery/docs/reservations-tasks) for queries in the model to use. This setting is useful for ensuring that Omni-related workloads are isolated from other loads on your database.

If other compute routing mechanisms - such as `compute_routing` or `sql_preamble` - are defined in the model, Omni resolves them in a specific order. See [Resolution precedence](/modeling/models/compute-routing#resolution) for more information.

## Syntax

```yaml theme={null}
slot_reservation: "<reservation_name>"
```

## Properties

<ParamField type="string">
  The name of an existing BigQuery reservation to use for queries in this model. This must be an existing [reservation](https://cloud.google.com/bigquery/docs/reservations-tasks#create_reservations).
</ParamField>

## Examples

```yaml theme={null}
slot_reservation: "blobsrus_reservation"
```


# sql_preamble - Model files
Source: https://docs.omni.co/modeling/models/sql-preamble

Runs a setup query before executing SQL statements against a model.

This parameter is useful for setting database session properties or configurations that need to be applied before queries run, particularly when those configurations need to vary based on user-specific attributes. Supports all database dialects and Mustache syntax injection.

If this parameter includes warehouse or session commands and other compute routing mechanisms - such as `compute_routing` - are defined in the model, Omni resolves them in a specific order. See [Resolution precedence](/modeling/models/compute-routing#resolution) for more information.

## Syntax

```yaml theme={null}
sql_preamble: <sql_statement>
```

## Properties

<ParamField type="string">
  A SQL statement to execute as a setup query before running SQL statements in the connection. Supports Mustache syntax for dynamic value injection, such as user attributes via `{{ omni_attributes.<attribute_name> }}`. All dialects are supported.
</ParamField>

## Examples

Omni automatically quotes user attributes when files are saved in the model IDE, meaning that the attribute value is always treated as a string. For example, even if the value of `{{ omni_attributes.special_prop_name }}` is numeric - like `5` or `102` - it'll be treated as if it were `"5"` or `"102"`:

```yaml title="Set a database property using a custom user attribute" theme={null}
sql_preamble: SET some_database_prop = {{ omni_attributes.special_prop_name }}
```

If you're using Snowflake or Databricks and you need to set a non-string property, you can use `IDENTIFIER` to convert the quoted string:

```yaml title="Snowflake and Databricks - Use IDENTIFIER to convert the attribute value type" theme={null}
sql_preamble: SET some_database_prop = IDENTIFIER({{ omni_attributes.special_prop_name }})
```


# template - Model files
Source: https://docs.omni.co/modeling/models/template

Disables the content validator for an abstract model.

**Used on abstract models**. Disables the content validator. This is useful because abstract models are logical constructs that aren't tied to data.

Refer to this [community article](https://community.omni.co/t/how-can-i-share-logic-across-multiple-models-hub-and-spoke/150) for more information.

## Syntax

```yaml theme={null}
template: true/false
```

## Properties

<ParamField type="boolean">
  When set to `true`, disables the content validator for abstract models that are logical constructs not tied to data.
</ParamField>

## Examples

```yaml theme={null}
template: true
```


# topic_group_descriptions - Model files
Source: https://docs.omni.co/modeling/models/topic-group-descriptions

Defines descriptions for topic groups.

Topic group descriptions - identified by [`group_label`](/modeling/topics/parameters/group-label) on topics - are displayed in the topic selector to help users understand the purpose of each topic group.

## Syntax

```yaml theme={null}
topic_group_descriptions:
  <group_label>: <description>
```

## Properties

<ParamField type="object">
  A map of topic group description definitions where each key is the name of a topic group.

  <Expandable title="topic_group_descriptions properties">
    <ParamField type="string">
      The name of the topic group. This must match the [`group_label`](/modeling/topics/parameters/group-label) value defined on one or more topics.
    </ParamField>

    <ParamField type="string">
      A description of the topic group that will be displayed in the topic selector.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
topic_group_descriptions:
  Sales: Topics related to sales data
  Marketing: Topics for marketing analytics
```


# topics - Model files
Source: https://docs.omni.co/modeling/models/topics

Define topics within model files.

<Note>
  On December 10, 2024, Omni deprecated this field in favor of giving topics their own file. Model files that contain this field will continue to function as they always have, but going forward you'll encounter an error if you attempt to add `topics:` to a model file.
</Note>

Refer to the [Topics documentation](/modeling/topics) for more information.


# warehouse_override - Model files
Source: https://docs.omni.co/modeling/models/warehouse-override

Specifies a different warehouse to use for a given workbook or branch.

<Note>
  Supported only for Snowflake and Databricks connections.
</Note>

This setting is useful for improving the performance of specific dashboards by providing more compute or isolating them from load on the default database.

If other compute routing mechanisms - such as `compute_routing` or `sql_preamble` - are defined in the model, Omni resolves them in a specific order. See [Resolution precedence](/modeling/models/compute-routing#resolution) for more information.

**Additionally, this parameter can only be used in workbook models.** It can't currently be promoted to the shared model. Adding this parameter to the workbook model does not cause any access warnings for **Viewer** or **Restricted querier** users even though it is a deviation from the shared model.

## Syntax

```yaml theme={null}
warehouse_override: "<warehouse_name>"
```

## Properties

<ParamField type="string">
  The name of an alternate warehouse to use for queries in this workbook or branch (e.g., `OMNI_WH`).
</ParamField>

## Examples

```yaml theme={null}
warehouse_override: "OMNI_WH"
```


# week_start_day - Model files
Source: https://docs.omni.co/modeling/models/week-start-day

Defines the day that weeks start on.

Defines the day that weeks start on. This parameter can be set dynamically using a [user attribute](/administration/users/attributes), which is useful when different users or regions follow different calendar conventions.

`OMNI_WEEK()` and `OMNI_DAY_OF_WEEK_NUMBER()` SQL operators are impacted by this setting.

<Note>
  `week_start_day` can also be set at the [topic](/modeling/topics/parameters/week-start-day) and [dimension level](/modeling/dimensions/parameters/week-start-day). When set at more than one level, the most specific setting is applied: dimension overrides topic, and topic overrides model.
</Note>

## Syntax

```yaml theme={null}
week_start_day: <day_of_week>
```

## Properties

<ParamField type="string">
  The day of the week that weeks start on. Valid values are: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`.

  Can be set dynamically using [user attributes](/administration/users/attributes). See the [**Examples**](#dynamic-value-using-user-attributes) section for an example.
</ParamField>

## Examples

### Static value

```yaml theme={null}
week_start_day: Sunday
```

### Dynamic value using user attributes

This example assumes your Omni instance has an existing user attribute called `week_start` and that users have been assigned appropriate day values, such as `Sunday` for US users or `Monday` for European users.

```yaml title="Set week start day based on user's region" theme={null}
week_start_day: {{ omni_attributes.week_start }}
```


# Editing query views
Source: https://docs.omni.co/modeling/query-views/edit

Update query view metadata, edit fields, and edit the underlying query or SQL — from a workbook or the modeling IDE.

<Note>
  **Looking for database views?** See [Editing database views](/modeling/views/edit).
</Note>

You can edit a query view's metadata, fields, and underlying definition from either a workbook or the modeling IDE. For an overview of query views, see [Working with query views](/modeling/query-views).

## Requirements

To edit views, you'll need:

* **Querier, Modeler,** or **Connection Admin** permissions
* **Connection Admin** or **Modeler** permissions to promote the changes to the shared model

## Editing metadata

You can update a query view's label, description, tags, visibility, and AI context from the workbook or the model IDE. Note that some metadata may only be editable from the IDE.

<AccordionGroup>
  <Accordion title="In the workbook" icon="book">
    1. In a workbook query, hover over a view in the field browser.
    2. Click the **<Icon icon="ellipsis-vertical" /> icon** next to the view name.
    3. Select **Edit** from the context menu.

    The **Edit view** drawer opens with the following editable properties:

    * **View label** — The display name for the view
    * **Description** — A description of the view's purpose or contents
    * **Tags** — Tags to organize and categorize the view
    * **Hidden** — Toggle to hide or show the view in the field browser
    * **AI context** — Additional context to help Omni AI understand and work with the view

    Make your changes and click **Update** to save. The **Update** button is disabled until you change a field.
  </Accordion>

  <Accordion title="In the IDE" icon="code">
    1. Navigate to the model IDE.
    2. In the **Schemas** section, locate the view you want to work with.
    3. Click the file to open it and then edit the corresponding parameters:

    * [`label`](/modeling/query-views/parameters/label)
    * [`description`](/modeling/query-views/parameters/description)
    * [`ai_context`](/modeling/query-views/parameters/ai-context)
    * [`tags`](/modeling/query-views/parameters/tags)
    * [`hidden`](/modeling/query-views/parameters/hidden)

    You can also add or edit any of the other supported [query view parameters](/modeling/query-views/parameters).

    4. Click **Save changes** in the IDE to apply your changes.
  </Accordion>
</AccordionGroup>

## Editing fields

You can edit field properties — label, description, AI context, visibility, and more — from either the workbook or the model IDE.

<AccordionGroup>
  <Accordion title="In the workbook" icon="book">
    Open the [Edit view drawer](#editing-metadata). The drawer lists every field in the view, including hidden ones:

    * **Visible fields** — Click a field row to open the **Edit field** panel, or click the <Icon icon="ellipsis-vertical" /> icon for additional options.
    * **Hidden fields** — Appear greyed out. Click the <Icon icon="eye" /> icon next to a hidden field to unhide it, then click it to edit its properties:

      <img alt="Hidden field with eye icon in Fields section of view editor" />
  </Accordion>

  <Accordion title="In the IDE" icon="code">
    Open the view file and locate the field under `dimensions` or `measures`. From there, you can update any of the field's parameters.

    For example, hide a field from the workbook field browser by setting `hidden: true`:

    ```yaml theme={null}
    dimensions:
      internal_notes:
        sql: '"INTERNAL_NOTES"'
        hidden: true
    ```

    Click **Save changes** when you're done. See the [Dimension](/modeling/dimensions) and [Measure](/modeling/measures) references for all available parameters.
  </Accordion>
</AccordionGroup>

## Editing the query view's definition

A query view's underlying definition — the fields, joins, and query it's built from — can be edited from either the workbook or the model IDE.

<AccordionGroup>
  <Accordion title="In the workbook" icon="book">
    1. In a workbook query, hover over the query view in the field browser.
    2. Click the <Icon icon="ellipsis-vertical" /> icon next to the view name.
    3. Click **Edit query view**. If the query view was built using SQL, a SQL editor will open where you can make changes to the view's query definition. Otherwise, a visual editor like the one used to build queries will display.
    4. When finished, click **Save changes to view**.
  </Accordion>

  <Accordion title="In the IDE" icon="code">
    Open the query view file in the IDE under the **Schemas** section of the **Files** panel. You can edit the [`query`](/modeling/query-views/parameters/query) or [`sql`](/modeling/query-views/parameters/sql) parameter directly, along with any other view parameters.

    See the [Query view parameter reference](/modeling/query-views/parameters) for the full list of supported parameters.
  </Accordion>
</AccordionGroup>

## Promoting changes

If you want your changes to be accessible in new and existing workbooks built on the underlying model, you'll need to promote them. See [Promoting changes to the shared model](/modeling/develop/promotion) for more information.

## Next steps

* [Query view parameter reference](/modeling/query-views/parameters)
* [Save queries as views](/analyze-explore/saved-views)
* [Editing database views](/modeling/views/edit)


# Configuring query views
Source: https://docs.omni.co/modeling/query-views/index

Query views are workbook queries that have been saved to the model as a view.

Query views are views created from an underlying workbook query. This workflow allows you to do light transformations on data, which are then compiled as CTEs when queried.

## Query view basics

<AccordionGroup>
  <Accordion title="How are database views and query views different?">
    A **database view** is auto-generated from tables in your database.

    A **query view** is a reusable view created from a workbook query. The query can be created using Omni's point-and-click UI or through SQL.
  </Accordion>

  <Accordion title="Who can create a query view?">
    Users with **Connection Admin**, **Modeler**, or **Querier** permissions can create query views.
  </Accordion>

  <Accordion title="Who can query a query view?">
    Users with **Connection Admin**, **Modeler**, or **Querier** permissions can use query views in workbook queries.
  </Accordion>

  <Accordion title="Are query views visible in the model IDE?">
    Yes. Query views are included in the **Schemas** section of the model IDE's **Files** browser.

    You can identify a query view by its file name. Query view file names are appended with `.query.view`, for example `user_facts.query.view`.
  </Accordion>

  <Accordion title="How can I tell the difference between SQL and point-and-click query views?">
    You can tell the difference between a point-and-click and a SQL query view by how the underlying query is defined in the query view's file:

    * **Point-and-click queries** use the [`query`](/modeling/query-views/parameters/query) parameter
    * **SQL queries** use the [`sql`](/modeling/query-views/parameters/sql) parameter

    <CodeGroup>
      ```yaml title Point-and-click query view theme={null}
      query:
        fields:
          users.id: id
          users.age: age
          users.created_at: created_at
        base_view: users
        sorts:
          - field: users.created_at
      ```

      ```yaml SQL query view theme={null}
      sql: |
        SELECT id, age, created_at
        FROM users
        ORDER BY created_at 
      dimensions:
        user_id: {}
        total_sales: {}
        measures:
          count:
            aggregate_type: count
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Can query views be promoted to the shared model?">
    Yes. When you initially create a query view, it will only be available in the workbook where you create it. You'll need to [promote it to the shared model](/modeling/develop/promotion) to make it accessible outside the workbook.
  </Accordion>
</AccordionGroup>

## Creating query views

See [Saving queries as views](/analyze-explore/saved-views).

## Editing query views

Query views can be edited in a workbook or in the model IDE. See [Editing query views](/modeling/query-views/edit) for more information.

## Next steps

* [Save queries as views](/analyze-explore/saved-views)
* [Editing query views](/modeling/query-views/edit)
* [Query view parameter reference](/modeling/query-views/parameters)


# ai_context - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/ai-context

Free text that can provide context about a query view to the Omni Agent.

Free text that can provide context to the [Omni Agent](/ai/chat). Context could include behavioral prompting or example queries and structured Omni results.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
ai_context: "<context_text>"
```

Or for multiline context:

```yaml theme={null}
ai_context: |
  <multiline_context_text>
```

## Properties

<ParamField type="string">
  Free text that provides context to the Omni Agent. Can include behavioral prompting, use case descriptions, sample queries, or other contextual information to improve AI query results.

  You can reference [user attributes](/administration/users/attributes) using `{{omni_attributes.<attribute_name>}}` syntax to personalize the context for each user.
</ParamField>

<Note>
  Only user attribute references are allowed in `ai_context`. Field references and filter conditions are not supported.
</Note>

## Examples

```yaml title="Personalized context using user attributes" theme={null}
ai_context: |
  This query view contains data for the {{omni_attributes.region}} region only.
```

```yaml title="Behavioral prompting" wrap theme={null}
ai_context: |
  you are the head of finance. you are concerned with the status of customer payments. you often need to project into the future how many invoices are due and for how much. you also need to know if any invoices are late so you can reach out to those customers.
```


# base_view - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/base-view

References the view that is used in the FROM of the generated SQL.

References the view that is used in the `FROM` of the generated SQL. Alternatively, think of the base view as the view that all subsequent views will join to when building a query.

## Syntax

```yaml theme={null}
query:
  base_view: <view_name>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="string">
      The name of the view to use as the base for the query. Only one base view is allowed per query view.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Query with a users base_view" theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
    calc_1: calc_1
  base_view: users
```


# bind - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/bind

Passes filter values from other fields into the subquery defined in a query view.

Passes filter values from other fields into the subquery defined in a query view. This parameter will explicitly pass only the enumerated field to the query view. If you want to pass any filters used in the UI into the query view, use [`bind_all_filters`](/modeling/query-views/parameters/bind-all-filters).

## Limitations

**Only supported for query views based on modeled workbook queries**. If defining a SQL-based query view using the `sql` parameter, use a [parameterized `WHERE` clause](/modeling/templated-filters/#parameterized-where-clause-in-views-based-on-a-sql-query) to achieve the same results.

## Syntax

```yaml theme={null}
query:
  filters:
    <filter_field>:
      bind: <other_view_name>.<other_field_name>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="object[]">
      An object containing the filter to apply to the query.

      <Expandable title="filters properties">
        <ParamField type="string">
          The name of the field that the field in `bind` will be bound to, specified as `view_name.field_name`.

          <Expandable title="filter_field properties">
            <ParamField type="string">
              The field to bind the filter to, specified as `view_name.field_name`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Bind order_items.created_at to users.created_at" highlight={6-8} theme={null}
query:
  fields:
    users.id: id
    order_items.sale_price_sum: sale_price_sum
  base_view: order_items
  filters:
    users.created_at:
      bind: order_items.created_at
  sorts:
    - field: order_items.sale_price_sum
      desc: true
  topic: order_items
```

***

In this example, `bind` is used to push a filter down onto a view that is being re-aggregated over. This enables putting filters on the reaggregate via the `filter` field while mapping to the underlying query rather than the query view.

```yaml title="Push filter down onto re-aggregated view" theme={null}
query:
  fields:
    order_items.user_id: user_id
    order_items.count: dim_count
  base_view: order_items
  filters:
    users.created_at:
      bind: orders_by_user.created_at
  sorts:
    - field: order_items.count
      desc: true
  topic: order_items
dimensions:
  dim_count: {}
  user_id:
    primary_key: true
measures:
  count:
    aggregate_type: count
filters:
  created_at:
    type: timestamp
```


# bind_all_filters - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/bind-all-filters

Passes all chosen filters from the outer query into the query view definition.

Passes all chosen filters from the outer query into the query view definition. In SQL, this parameter allows the filters set in the outer query to be passed into the inner query.

<Tip>
  If filters applied in the outer query aren’t being pushed into the SQL of the query view, check that the filtered field can be joined to the query view’s base view within the topic. Omni can only push filters into the query view when there is a valid join path. In some cases, filters also won’t be pushed down if the field is only accessible via an `XLOOKUP` rather than a join.
</Tip>

## Limitations

**Only supported for query views based on modeled workbook queries**. If defining a SQL-based query view using the `sql` parameter, use a [parameterized `WHERE` clause](/modeling/templated-filters/#parameterized-where-clause-in-views-based-on-a-sql-query) to achieve the same results.

## Syntax

```yaml theme={null}
query:
  bind_all_filters: <true_or_false>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="boolean">
      If `true`, all filters from the outer query will be passed into the query view.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

When this query view is used, Omni will attempt to push all filters from the outer query into the query view's SQL. Any filters whose fields can be joined to the query view’s `base_view` will be applied inside the query view. Filters that cannot be joined are not pushed down and remain applied in the outer query instead.

```yaml theme={null}
query:
  fields:
    users.id: id
    order_items.sale_price_sum: sale_price_sum
  base_view: order_items
  sorts:
    - field: order_items.sale_price_sum
      desc: true
  topic: order_items
  bind_all_filters: true
```


# bind_outer_context - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/bind-outer-context

Makes is_selected, is_filtered, and in_query template variables inside a query view resolve against the outer query instead of the view's own query.

Makes [`is_selected`, `is_filtered`, and `in_query` template variables](/modeling/templated-filters/index#self-referential-building) inside a query view resolve against the outer query instead of the view's own query.

When used inside a query view, these variables evaluate against the query view's own inner query by default. This means they typically return `"nothing selected"` or `"nothing filtered"` once a field is wrapped in a query view, unless that field happens to be selected or filtered within the view's own query definition.

Setting `bind_outer_context: true` under the `query:` block makes these three template variables resolve against the outer query that is using the view instead. This allows fields inside query views to react to what's selected or filtered in the outer query, rather than being limited to the view's internal query context.

## Limitations

* **This setting doesn't affect materialized query views.** These views will inherit this property, but cannot react to outer context since they have no outer query at execution time.
* **Querying the view directly will evaluate all template variables to `false`** since there is no outer context to bind to.
* **Nested query views that also set `bind_outer_context: true` chain up to the nearest enclosing query that doesn't itself defer**. The variables resolve against that outermost query's context.

## Syntax

```yaml theme={null}
query:
  bind_outer_context: <true_or_false>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="boolean">
      If `true`, the template variables `is_selected`, `is_filtered`, and `in_query` inside the query view will resolve against the outer query that uses the view, rather than the view's own inner query.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

In this query view, any field that uses `is_selected`, `is_filtered`, or `in_query` will evaluate those variables based on the outer query's field list and filters, not the view's own `fields:` list.

```yaml theme={null}
query:
  fields:
    users.id: id
    users.name: name
    users.created_date: created_date
  base_view: users
  topic: users
  bind_outer_context: true
```

For example, if a dimension inside the `users` view has a `sql` expression that checks `{% if users.email.is_selected %}`, that condition will be `true` if `users.email` is selected in the outer query that references this query view, even though `users.email` is not in the query view's own `fields:` list above.


# calculations - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/calculations

Lists the calculations defined in the query.

Lists the calculations defined in the query.

## Syntax

```yaml theme={null}
query:
  calculations:
    <calculation_name>:
      sql: ${<view_name>.<field_name>} <OMNI SQL TABLE FUNCTION>
      label: <string>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition. See [`query`](/modeling/query-views/parameters/query) for more information.

  <Expandable title="query properties">
    <ParamField type="object">
      A list of calculation definitions, where each key is a unique name for the calculation.

      <Expandable title="calculations properties">
        <ParamField type="object">
          The name of the calculation.

          <Expandable title="calculation_name properties">
            <ParamField type="string">
              An [Omni calculation expression](/analyze-explore/calculations/all). Specify fields using `${view_name.field_name}` syntax.
            </ParamField>

            <ParamField type="string">
              Display name for the calculation.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Calculation that adds 2 to users.age" theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
    age_calc: age_plus_two
  calculations:
    age_calc:
      sql: ${users.age} OMNI_FX_PLUS 2
```

```yaml title="Calculation that creates a link" theme={null}
query:
  fields:
    issues.id: id
    issues.number: number
    issue_link: link
  calculations:
    issue_link:
      sql: CONCAT('https://blobsrus.com/issues/', ${issues.number.id})
```


# default_group_by - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/default-group-by

Enables or disables a GROUP BY in the query.

Enables or disables a `GROUP BY` in the query view's query. Automatically set to `false` if there are no measures in the query view.

<Info>
  This query view-level boolean parameter is distinct from the model-level [`default_group_by`](/modeling/models/default-group-by) parameter, which controls implicit `GROUP BY` behavior for measure-less queries across the entire model. The two settings apply at different scopes.
</Info>

## Syntax

```yaml theme={null}
query:
  default_group_by: <true_or_false>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="boolean">
      If `true`, the query will include a `GROUP BY` clause. If `false`, duplicate rows will not be grouped.

      **Note**: Omni automatically sets this to `false` if the query view does not contain any measures.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Group duplicate rows for users with the same name" theme={null}
query:
  fields:
    users.name: user_name
  default_group_by: true
```


# description - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/description

Free text that describes the query view.

Free text that describes the query view. For example, you could add copy that describes what questions the query view can answer.

## Syntax

```yaml theme={null}
# Single line description
description: <description_text>

# Multi-line description
description: |
  <multiline_description_text>
```

## Properties

<ParamField type="string">
  Free text that describes the query view. For multiline descriptions or descriptions containing special characters like colons, use the pipe (`|`) syntax. Values should be unquoted.
</ParamField>

## Examples

```yaml title="Single line description" theme={null}
description: All transactions related to orders from the online store.
```

```yaml title="Multi-line description" theme={null}
description: |
  Transactions from: California, Washington, and Oregon
```


# dimensions - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/dimensions

Lists all fields selected in the query, making them into dimensions to allow for aggregation in another query.

<Note>
  This is a top-level parameter in query views - it shouldn't be nested under the `query` parameter.
</Note>

Lists all fields selected in the query, making them into dimensions to allow for aggregation in another query.

## Syntax

```yaml theme={null}
dimensions:
  <dimension_name>: {}
  <dimension_name>: {}
  <calc_name>: {}
  <measure_name>: {}
```

## Properties

<ParamField type="object">
  A list of dimension names from the query, with each dimension defined as an empty object (`{}`).
</ParamField>

## Examples

```yaml title="Query view with age, created_at_year, and calc_1 dimensions" theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
    calc_1: calc_1
  base_view: users

dimensions:
  age: {}
  created_at_year: {}
  calc_1: {}
```


# display_order - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/display-order

Overrides the sort order for views in the field browser.

Overrides the sort order for views in the field browser. When set, this will supersede Omni's default alphabetical sorting.

For example, if only one view has `display_order: 1`, it will display at the top of the list of views in the field browser. Other views will be sorted and displayed alphabetically.

## Syntax

```yaml theme={null}
display_order: <number>
```

## Properties

<ParamField type="number">
  A number that determines the view's position in the field browser.
</ParamField>

## Examples

```yaml title="Display view first" theme={null}
display_order: 1
```


# fields - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/fields

Lists the fields in the query.

Lists the fields in the query.

## Syntax

```yaml theme={null}
query:
  fields:
    <view_name>.<field_name>: <optional_alias>
    <view_name>.<field_name>
    calc_1: <optional_alias>
    calc_2: <optional_alias>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="object">
      A list of field names in the query, specified as `view_name.field_name`. For date fields, append the time unit to the field name and enclose it in square brackets. For example, `users.created_at[year]`

      Add an alias to a field with `view_name.field_name: alias`
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Fields with aliases" theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
    calc_1: age_plus_two
```

```yaml title="Fields without aliases" theme={null}
query:
  fields:
    users.age
    users.created_at[year]
    calc_1
```


# fill_fields - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/fill-fields

Ensures that the query returns continuous values for specific dimensions, even when no underlying rows exist.

Ensures that the query returns continuous values for specific dimensions, even when no underlying rows exist. Useful for time-series data and is commonly used to show all months, days, or categories in a visualization, even when some buckets have zero records.

## Syntax

```yaml theme={null}
query:
  fill_fields: ["<view_name>.<field_name>", "<view_name>.<field_name>", ...]
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="string[]">
      An array of field names, specified `view_name.field_name`.

      For date fields, append the time unit in square brackets. For example, `users.created_at[year]`
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Show all months in a 4 year period" highlight={7-10} theme={null}
query:
  fields:
    users.age: age
    users.created_at[month]: created_at_month
    calc_1: calc_1
  base_view: users
  fill_fields: [ "users.created_at[year]" ]
  filters:
    users.created_at:
      time_for_duration: [ 4 years ago, 4 years ]
```


# filters - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/filters

Defines the filters applied in the query.

Defines the filters applied in the query.

<Tip>
  Check out the [Filter documentation](/modeling/filters) for syntax information and [examples](/modeling/filters/examples).
</Tip>

## Syntax

```yaml theme={null}
query:
  filters:
    <filter_field>:
      <filter_condition>: <value>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="object[]">
      A mapping of field names to their filter conditions using [filter syntax](/modeling/filters).

      <Expandable title="filters properties">
        <ParamField type="string">
          The field to filter on, specified in the format `view_name.field_name`. Can be a time, numeric, or string field.

          <Expandable title="filter_field properties">
            <ParamField type="varies">
              The filter condition, specified using [filter syntax](/modeling/filters).
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="users created in 2021 & order_items from the past 30 days" highlight={6-12} theme={null}
query:
  fields:
    users.id: id
    order_items.sale_price_sum: sales
  base_view: order_items
  filters:
    users.age_bin:
      is: []
    users.created_at:
      is: "2021"
    order_items.created_at:
      time_for_duration: [ 30 complete days ago, 30 days ]
```


# hidden - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/hidden

Removes a query view from the workbook UI while keeping it referenceable in the model.

Removes a query view from the workbook UI while keeping it referenceable in the model.

**Note**: Query views are not removed from the model itself and will still be accessible via SQL. To "soft delete" a view instead, use the [`ignored`](/modeling/query-views/parameters/ignored) parameter.

## Syntax

```yaml theme={null}
hidden: true
```

## Properties

<ParamField type="boolean">
  If `true`, the query view will be hidden in the UI.
</ParamField>

## Examples

```yaml title="Hide query view in UI" theme={null}
hidden: true
```


# ignored - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/ignored

Soft-deletes a query view in the model.

Soft-deletes a query view in the model, effectively removing the query view from the model. Useful for hiding undesirable tables. When using this parameter, note that:

* When applied, references to the query view will break, resulting in model validation errors
* Query views are not removed from the schema and will still be accessible via SQL

To instead hide a query view from the workbook UI, use the [`hidden`](/modeling/query-views/parameters/hidden) parameter.

## Syntax

```yaml theme={null}
ignored: true
```

## Properties

<ParamField type="boolean">
  If `true`, the query view will be ignored.
</ParamField>

## Examples

```yaml title="Ignore a query view" theme={null}
ignored: true
```


# Query view parameters
Source: https://docs.omni.co/modeling/query-views/parameters/index

Reference for all query view YAML parameters in Omni, including base_view, filters, sorts, fields, and query configuration.

| Parameter                                                                   | Description                                                                                                                               |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [ai\_context](/modeling/query-views/parameters/ai-context)                  | Free text that can provide context about a query view to the Omni Agent.                                                                  |
| [base\_view](/modeling/query-views/parameters/base-view)                    | References the view that is used in the FROM of the generated SQL.                                                                        |
| [bind\_all\_filters](/modeling/query-views/parameters/bind-all-filters)     | Passes all chosen filters from the outer query into the query view definition.                                                            |
| [bind](/modeling/query-views/parameters/bind)                               | Passes filter values from other fields into the subquery defined in a query view.                                                         |
| [bind\_outer\_context](/modeling/query-views/parameters/bind-outer-context) | Makes `is_selected`, `is_filtered`, and `in_query` inside the query view resolve against the outer query instead of the view's own query. |
| [calculations](/modeling/query-views/parameters/calculations)               | Lists the calculations defined in the query.                                                                                              |
| [default\_group\_by](/modeling/query-views/parameters/default-group-by)     | Enables or disables a GROUP BY in the query.                                                                                              |
| [description](/modeling/query-views/parameters/description)                 | Free text that describes the query view.                                                                                                  |
| [dimensions](/modeling/query-views/parameters/dimensions)                   | Lists all fields selected in the query, making them into dimensions to allow for aggregation in another query.                            |
| [display\_order](/modeling/query-views/parameters/display-order)            | Overrides the sort order for views in the field browser.                                                                                  |
| [fields](/modeling/query-views/parameters/fields)                           | Lists the fields in the query.                                                                                                            |
| [fill\_fields](/modeling/query-views/parameters/fill-fields)                | Ensures that the query returns continuous values for specific dimensions, even when no underlying rows exist.                             |
| [filters](/modeling/query-views/parameters/filters)                         | Defines the filters applied in the query.                                                                                                 |
| [hidden](/modeling/query-views/parameters/hidden)                           | Removes a query view from the workbook UI while keeping it referenceable in the model.                                                    |
| [ignored](/modeling/query-views/parameters/ignored)                         | Soft-deletes a query view in the model.                                                                                                   |
| [join\_via\_map](/modeling/query-views/parameters/join-via-map)             | Maps joins when the query view is based on SQL and the joins are non-default joins.                                                       |
| [label](/modeling/query-views/parameters/label)                             | Overrides the name of the query view in the UI.                                                                                           |
| [limit](/modeling/query-views/parameters/limit)                             | Defines the row limit of the query if a limit is set on the query in the workbook.                                                        |
| [measures](/modeling/query-views/parameters/measures)                       | Describes how to aggregate data in the query.                                                                                             |
| [query](/modeling/query-views/parameters/query)                             | Defines the underlying query for the query view.                                                                                          |
| [schema](/modeling/query-views/parameters/schema)                           | References the query's underlying schema name from the associated database connection.                                                    |
| [sorts](/modeling/query-views/parameters/sorts)                             | Defines the field(s) that the query is sorted by.                                                                                         |
| [sql](/modeling/query-views/parameters/sql)                                 | Defines the SQL query used by the query view.                                                                                             |
| [tags](/modeling/query-views/parameters/tags)                               | Curates view and field groups for organizing and grouping views in the UI.                                                                |
| [topic](/modeling/query-views/parameters/topic)                             | Specifies the topic used by the query.                                                                                                    |


# join_via_map - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/join-via-map

Maps joins when the query view is based on SQL and the joins are non-default joins.

Maps joins when the query view is based on SQL and the joins are non-default joins.

## Syntax

```yaml theme={null}
query:
  join_via_map:
    <view_name>: []
    <view_name>: [<view_name_to_map_to>]
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="object">
      A mapping of view names to arrays indicating how joins should be made. Empty arrays indicate direct joins, while non-empty arrays specify intermediate views to join through.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Join order_items to orders" highlight={6-8} theme={null}
query:
  fields:
    users.id: id
    order_items.sale_price_sum: sales
  base_view: order_items
  join_via_map:
    orders: []
    order_items: [ orders ]
```


# label - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/label

Defines a display name for the query view.

Defines a display name for the query view. This will override the query view's name as it displays in the workbook.

## Syntax

```yaml theme={null}
label: <display name>
```

## Properties

<ParamField type="string">
  The display name that will appear in the UI instead of the query view name.
</ParamField>

## Examples

```yaml title="Query view will display as Users With Orders in the UI" theme={null}
schema: ecomm
label: Users With Orders
```


# limit - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/limit

Defines the row limit of the query if a limit is set on the query in the workbook.

Defines the row limit of the query if a limit is set on the query in the workbook.

## Syntax

```yaml theme={null}
limit: <limit_value>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="number">
      The maximum number of rows to return in the query.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Top ten users by spend" highlight={9} theme={null}
query:
  fields:
    users.id: id
    order_items.sale_price_sum: sales
  base_view: order_items
  sorts:
    - field: order_items.sale_price_sum
      desc: true
  limit: 10
```


# measures - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/measures

Describes how to aggregate data in the query.

<Note>
  This is a top-level parameter in query views - it shouldn't be nested under the `query` parameter.
</Note>

Describes how to aggregate data in the query.

Omni adds this parameter to query views by default, regardless of whether a measure is in the query. The default measure creates a `COUNT(*)` that counts all rows in the query results. **Note**: Other aggregations aren't automatically added to this parameter - they are dimensionalized and added to [`dimensions`](/modeling/query-views/parameters/dimensions).

## Syntax

```yaml theme={null}
measures:
  <measure_name>:
    aggregate_type: <type>
    ...
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="measures properties">
    <ParamField type="object">
      The name of the measure. The default measure added by Omni is named `count`.

      <Tip>
        Refer to the [Measures documentation](/modeling/measures) for a list of measure-specific parameters.
      </Tip>

      <Expandable title="measures properties">
        <ParamField type="string">
          The aggregation type. The default measure added by Omni is set to `count`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Default count measure" theme={null}
measures:
  count:
    aggregate_type: count
```


# query - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/query

Defines the underlying query for the query view.

A top-level object that contains the individual parameters that make up a query view's query definition.

## Syntax

```yaml theme={null}
query:
  <sub-parameters>:
  ...
```

## Properties

<ParamField type="object">
  The parent object containing all query view sub-parameters:

  * [`base_view`](/modeling/query-views/parameters/base-view)
  * [`bind`](/modeling/query-views/parameters/bind)
  * [`bind_all_filters`](/modeling/query-views/parameters/bind-all-filters)
  * [`bind_outer_context`](/modeling/query-views/parameters/bind-outer-context)
  * [`calculations`](/modeling/query-views/parameters/calculations)
  * [`default_group_by`](/modeling/query-views/parameters/default-group-by)
  * [`fields`](/modeling/query-views/parameters/fields)
  * [`fill_fields`](/modeling/query-views/parameters/fill-fields)
  * [`filters`](/modeling/query-views/parameters/filters)
  * [`join_via_map`](/modeling/query-views/parameters/join-via-map)
  * [`limit`](/modeling/query-views/parameters/limit)
  * [`sorts`](/modeling/query-views/parameters/sorts)
  * [`topic`](/modeling/query-views/parameters/topic)
</ParamField>

## Examples

```yaml theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
  base_view: users
  sorts:
    - field: users.created_at[year]
```


# schema - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/schema

References the query's underlying schema name from the associated database connection.

References the query's underlying schema name from the associated database connection.

## Syntax

```yaml theme={null}
schema: <db_schema_name>
```

## Properties

<ParamField type="string">
  The name of the database schema.
</ParamField>

## Examples

```yaml title="Translates to ecommerce.users.[field]" theme={null}
schema: ecommerce
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
  base_view: users
```


# sorts - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/sorts

Defines the field(s) that the query is sorted by.

Defines the field(s) that the query is sorted by.

## Syntax

```yaml theme={null}
query:
  sorts:
    - field: <view_name.field_name>
      desc: <true_or_false>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="array[object]">
      An array of sort definitions. Each sort includes a `field` parameter and optionally a `desc` parameter for descending order.
    </ParamField>

    <Expandable title="sorts properties">
      <ParamField type="string">
        The field to sort by, specified as `view_name.field_name`.
      </ParamField>

      <ParamField type="boolean">
        If `true`, sort in descending order. Defaults to `false` for ascending order.
      </ParamField>
    </Expandable>
  </Expandable>
</ParamField>

## Examples

```yaml title="Sort by created_at (asc) & age (desc)" theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
  base_view: users
  sorts:
    - field: users.created_at[year]
    - field: users.age
      desc: true
```


# sql - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/sql

Defines the SQL query used by the query view.

Defines the SQL query used by the query view. If the query view was created using SQL, this parameter will be automatically populated with the SQL query from the workbook. Otherwise, this parameter will be omitted.

## Syntax

```yaml title="Single line" theme={null}
sql: <sql_statement>
```

```yaml title="Multi-line" theme={null}
sql: |
  <sql_statement>
```

## Properties

<ParamField type="string">
  The SQL statement that the query view is based on. If the query view was created using SQL, this parameter will be automatically populated with the SQL query from the workbook.
</ParamField>

## Examples

```yaml title="sql_query_view.query.view" highlight={2-5} theme={null}
schema: PUBLIC
sql: |
  SELECT user_id, sum(sale_price) as total_sales
  FROM order_items
  GROUP BY 1
dimensions:
  user_id: {}
  total_sales: {}
  measures:
    count:
      aggregate_type: count
```


# tags - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/tags

Curates view and field groups for organizing and grouping views in the UI.

Curates view and field groups for organizing and grouping views in the UI.

## Syntax

```yaml theme={null}
tags: [<tag1>, <tag2>, ...]
```

or

```yaml theme={null}
tags:
  - <tag1>
  - <tag2>
  - ...
```

## Properties

<ParamField type="array">
  A comma-delimited array of strings used for organizing and grouping query views.
</ParamField>

## Examples

```yaml theme={null}
tags: [ sales ]
```


# topic - Query views
Source: https://docs.omni.co/modeling/query-views/parameters/topic

Specifies the topic used by the query.

Specifies the topic used by the query. If the query is not based on a [topic](/modeling/topics), this parameter will be omitted.

## Syntax

```yaml theme={null}
query:
  topic: <topic_name>
```

## Properties

<ParamField type="object[]">
  An object containing the individual parameters that make up a query view's query definition.

  <Expandable title="query properties">
    <ParamField type="string">
      The name of the topic the query is based on.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Query based on orders topic" theme={null}
query:
  fields:
    users.age: age
    users.created_at[year]: created_at_year
  topic: orders
```


# Creating table joins
Source: https://docs.omni.co/modeling/relationships/build

Create table joins in Omni workbooks or the model IDE, configure join types and conditions, and promote joins to the shared model.

## Creating joins in the workbook

<Note>
  Unless promoted to the shared model, joins created in workbooks will only be available in the workbook where they were created.

  Queriers can create joins in workbooks, but Modeler or Connection Admin permissions are required for promotion.
</Note>

In the field browser, right-click on a table and select **Joins > New join**. This opens the join builder:

<Frame>
  <img alt="Diagram showing the architecture of the system" />
</Frame>

From here, you can use the **Builder** or **SQL** tabs to define the join:

<AccordionGroup>
  <Accordion title="Builder tab" icon="eye" description="Define the join with a visual editor">
    <Steps>
      <Step>
        The left and right sides of the **Builder tab** represent the views you want to join. On each side, select the fields that should be used to join the views.

        For example, selecting `orders.customer_id` and `customers.id`.
      </Step>

      <Step>
        Select a **Type** to define what type of join this is. Omni defaults to **Left** (`LEFT JOIN`), but you can change this. Refer to the [`join_type`](/modeling/relationships/parameters/join-type) reference for more information about this setting.
      </Step>

      <Step>
        Select a **Relationship** for the join. This setting is used to ensure that counts across the tables are accurate. If you're not sure what this setting should be, click the **Infer relationship** button at the bottom left corner of the modal.

        Omni will check the cardinality between the datasets and select the relationship type on your behalf. Refer to the [`relationship_type`](/modeling/relationships/parameters/relationship-type) reference for more information about this setting.
      </Step>

      <Step>
        Check the **Reversible** box allow for exploration in both directions of the join.

        <Warning>
          This setting controls how fan out is handled and thus impacts the shape of result sets. Refer to the [`reversible`](/modeling/relationships/parameters/reversible) reference for more information.
        </Warning>
      </Step>

      <Step>
        Use the **Add to topic** settings to select if the join should be added to the current topic, all possible topics, or not added.
      </Step>

      <Step>
        Click **Save** to create the join.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="SQL joins" icon="code" description="Define the join condition using SQL">
    The **SQL** tab is useful if you're creating a complex join or just prefer writing in SQL:

    <img alt="SQL tab in the join modal, useful for creating complex joins" />

    <Steps>
      <Step>
        Select the source and target views using the dropdowns.
      </Step>

      <Step>
        In the code block, write the join using SQL. Use `${view_name.field_name}` syntax to reference fields.
      </Step>

      <Step>
        Select a **Type** to define what type of join this is. Omni defaults to **Left** (`LEFT JOIN`), but you can change this. Refer to the [`join_type`](/modeling/relationships/parameters/join-type) reference for more information about this setting.
      </Step>

      <Step>
        Select a **Relationship** for the join. This setting is used to ensure that counts across the tables are accurate. If you're not sure what this setting should be, click the **Infer relationship** button at the bottom left corner of the modal.

        Omni will check the cardinality between the datasets and select the relationship type on your behalf. Refer to the [`relationship_type`](/modeling/relationships/parameters/relationship-type) reference for more information about this setting.
      </Step>

      <Step>
        Check the **Reversible** box allow for exploration in both directions of the join.

        <Warning>
          This setting controls how fan out is handled and thus impacts the shape of result sets. Refer to the [`reversible`](/modeling/relationships/parameters/reversible) reference for more information.
        </Warning>
      </Step>

      <Step>
        Use the **Add to topic** settings to select if the join should be added to the current topic, all possible topics, or not added.
      </Step>

      <Step>
        Click **Save** to create the join.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

Saving the join will add a new relationship definition to the workbook model's `relationships` file, which you can view by clicking **Model > Model layers > Workbook**.

<Tip>
  [Promote the join](/modeling/develop/model-management) to the shared model to make it accessible outside the workbook.
</Tip>

## Defining relationships in the model IDE

<Note>
  Connection Admin or Modeler permissions are required to access the model IDE.
</Note>

For a code-forward approach, you can use the model IDE to create and modify joins.

<Steps>
  <Step>
    Open the model IDE by clicking **Develop** in the [sidebar](/administration/settings/sidebar). If your organization has more than one model, click the model you want to work with. If you have only one model, Omni opens it automatically.
  </Step>

  <Step>
    In the **Settings** section, click **Relationships**.
  </Step>

  <Step>
    The `relationships` file will open in the editor panel. Add a relationship definition, which will look similar to the following example:

    <CodeGroup>
      ```yaml Example definition theme={null}
      - join_from_view: main__orders
        join_to_view: main__customers
        join_type: always_left
        on_sql: ${main__orders.customer_id} = ${main__customers.id}
        relationship_type: assumed_many_to_one
      ```

      ```yaml Template theme={null}
      - join_from_view:
        join_to_view:
        join_type:
        on_sql: 
        relationship_type:
      ```
    </CodeGroup>

    <Tip>
      Click the **Template** tab in the above code block for a copy + pasteable relationship definition!
    </Tip>
  </Step>

  <Step>
    Define the parameters to complete the join. In addition to the parameters in the above example and template, you can add parameters like  [`where_sql`](/modeling/relationships/parameters/where-sql) or [`reversible`](/modeling/relationships/parameters/reversible) to further customize the relationship. Refer to the [Relationship parameters reference](/modeling/relationships/parameters) for more information and examples.
  </Step>

  <Step>
    Click **Save changes**.

    <Note>
      If the model is currently configured to require branches, merge the branch to apply the changes to the shared model.

      If the model also uses the git integration, you may need to create a pull request to accomplish this.
    </Note>
  </Step>
</Steps>


# Relationships and joins
Source: https://docs.omni.co/modeling/relationships/index

Define relationships between views in your Omni model to enable automatic SQL joins, cross-table exploration, and data analysis.

Relationships define how different datasets connect to each other in your model. They describe how one table (or view) can be joined to another, making it possible to query and explore data across multiple sources in Omni.

Once defined, Omni uses these relationships to automatically generate SQL `JOINS` when users explore data. This allows for exploration without the need to write SQL.

## Relationship definitions

Global relationships are defined in your model's `relationships` file and look similar to the following:

```yaml title="Example joins in relationships.yml file" theme={null}
- join_from_view: users
  join_from_view_as: buyers
  join_from_view_as_label: Buyers
  join_to_view: user_facts
  join_type: always_left
  on_sql: ${users.id} = ${user_facts.id}
  relationship_type: one_to_one

- join_from_view: users
  join_to_view: orders
  join_type: always_left
  on_sql: ${users.id} = ${orders.id}
  relationship_type: many_to_one
  reversible: true
```

Joins defined in this way can be reused across the [topics](/modeling/topics) in the model, allowing you to create a consistent, central definition of how tables relate to each other. This ensures that your model is:

* Consistent, accurate, and free from duplication
* Easy to navigate
* Aligned with your business logic

For example, you might define how `orders` connect to `users` or how `sessions` link to `users`, so that anyone exploring data in Omni can seamlessly combine those sources without writing SQL.

<Tip>
  Refer to the [Relationship parameters reference](/modeling/relationships/parameters) for more information and examples.
</Tip>

### Auto-inferred relationships

When a new model is created, Omni auto-infers relationships based on the schema metadata. You can control how Omni infers relationships during schema refresh using the **Auto-generate relationships** connection setting.

Omni supports two inference strategies:

* **Column name matching** - Omni checks each table and looks for comparable field names and types, using this metadata to infer relationships
* **Foreign key constraints** - For databases that support foreign keys (Postgres, Snowflake), Omni can use constraint metadata to infer relationships

For example, consider an `orders` table and a `users` table like the following:

```mermaid actions={false} theme={null}
classDiagram
  direction LR
    class USERS {
        id
        email
        ...
    }
    class ORDERS {
        id
        user_id
        ...
    }
    USERS --> ORDERS : has
```

The `users` table contains an `id`, and `orders` has a `user_id`. With column name inference enabled, Omni would infer that `users.id = orders.user_id` and create a relationship between the tables. Omni-inferred relationships will have [`relationship_type: assumed_many_to_one`](/modeling/relationships/parameters/relationship-type) in their definition.

#### Configuring relationship auto-generation

The **Auto-generate relationships** setting controls how Omni infers relationships during schema refreshes. The setting is configured per connection on the connection's settings page (**Settings > Connections >** your connection).

For databases that support foreign key constraints (Postgres, Snowflake), the setting provides four modes:

* **Both** - Infer relationships from foreign key constraints and column name matching (default)
* **Foreign keys only** - Infer relationships only from foreign key constraints
* **Column names only** - Infer relationships only from column name matching
* **None** - Skip auto-generation entirely

For other databases (BigQuery, MySQL, etc.), the setting is a simple toggle that controls whether Omni infers relationships from column name matching. By default, column name inference is enabled.

<Tip>
  For large warehouses, disabling auto-generation or limiting it to a single strategy can help reduce the number of auto-generated joins. Refer to the [Postgres](/connect-data/setup/postgres) or [Snowflake](/connect-data/setup/snowflake) connection guides for more details.
</Tip>

### Topic-scoped relationships

If you want a join to only be accessible in a specific topic, you can create a topic-scoped relationship. This type of relationship is defined directly in a [topic file](/modeling/topics) using the [`joins`](modeling/topics/parameters/joins) parameter.

For example, the joins in the following `Transactions` topic would only be available to users when they're in that specific topic:

```yaml title="Transactions topic" theme={null}
label: "Transactions"
base_view: "orders"

joins:
  inventory_items:                  # Includes inventory_items in the topic
    products:                       # Joins products to inventory_items
      distribution_centers: {}      # Joins distribution_centers to products
  users: {}                         # Includes users in the topic
```

Topic-scoped joins are ideal when you want to control how data sources connect for a specific topic or when the same tables might join differently across topics. For example, a `users` view might join to `sessions` by `user_id` in one topic, but by `account_id` in another.

In practice, you might start with global relationships for shared connections like `orders → customers`, and then define topic relationships when a topic requires a customized join or additional context. Omni automatically merges topic and global relationships when generating SQL, giving you the flexibility to tailor joins while keeping your model consistent.

<Note>
  Topic-specific views offer a similar trade-off, where even views and fields can be customized at the topic level. This is a common pattern when using topic-specific joins. For example, you may want to extend an aliased view inside a topic to customize fields for a specific use case.
</Note>

Refer to the [Topic documentation](/modeling/topics) for more information and examples.

<Heading>
  Reversible relationships
</Heading>

Omni curates the workbook experience to prevent unexpected join results. When exploring in **All Views and Fields,** Omni hides joins that would fan out the base dataset unless the relationship explicitly allows it with [`reversible: true`](/modeling/relationships/parameters/reversible).

<img alt="Example joins of orders to users and users to orders" />

In the above example, `users` is joined into `orders`. This join doesn’t change the number of rows — each `order` simply gains descriptive information about the `user` who placed it. This is a `many_to_one` relationship and represents the default join direction Omni includes in the workbook.

In contrast, the bottom example shows `orders` joined into `users`. Here, the base table’s shape changes because each `user` now appears multiple times, once for every `order` they’ve placed. This is a `one_to_many` relationship that fans out the data.

By default, Omni surfaces only joins like the first example (`many_to_one`) to keep workbook results intuitive and prevent duplicate rows. **To make a join usable in both directions**, you can explicitly flag it as bi-directional by setting [`reversible: true`](/modeling/relationships/parameters/reversible) in the relationship's definition.

## Building joins

Joins can be built in Omni workbooks or in the model IDE. Refer to the [Building joins guide](/modeling/relationships/build) for a detailed walkthrough.


# id - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/id

Omni-generated identifier for duplicate joins.

Omni-generated identifier for duplicate joins; automatically added when duplicate joins are detected in your model. This identifier helps distinguish between multiple joins to the same table, but its presence typically indicates that your model needs attention.

<Warning>
  Rather than using this parameter explicitly, you should review your join relationships and eliminate any unnecessary duplicates.
</Warning>

## Syntax

```yaml theme={null}
id: <identifier>
```

## Properties

<ParamField type="string">
  An identifier Omni adds to relationships when duplicate joins are detected. Avoid explicit use.
</ParamField>

## Examples

```yaml title="Duplicate joins for buyers to buyer_facts" theme={null}
- id: buyers_0
  join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one

- id: buyers_1
  join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```


# Relationship file parameters
Source: https://docs.omni.co/modeling/relationships/parameters/index

Reference for all relationship YAML parameters in Omni, including join type, cardinality, on_sql conditions, and reversibility.

| Parameter                                                                                 | Description                                                                 |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [id](/modeling/relationships/parameters/id)                                               | Omni-generated identifier for duplicate joins.                              |
| [join\_from\_view\_as\_label](/modeling/relationships/parameters/join-from-view-as-label) | Controls the display name of the source view in the UI when using the join. |
| [join\_from\_view\_as](/modeling/relationships/parameters/join-from-view-as)              | Aliases the source view with a new name.                                    |
| [join\_from\_view](/modeling/relationships/parameters/join-from-view)                     | Defines the source view from which the join originates.                     |
| [join\_to\_view\_as\_label](/modeling/relationships/parameters/join-to-view-as-label)     | Controls the display name of the joined view in the UI when using the join. |
| [join\_to\_view\_as](/modeling/relationships/parameters/join-to-view-as)                  | Aliases the joined view with a new name.                                    |
| [join\_to\_view](/modeling/relationships/parameters/join-to-view)                         | Specifies the view to join to the source view.                              |
| [join\_type](/modeling/relationships/parameters/join-type)                                | Specifies the type of SQL join to perform.                                  |
| [on\_sql](/modeling/relationships/parameters/on-sql)                                      | Specifies the SQL condition that determines how to perform the join.        |
| [relationship\_type](/modeling/relationships/parameters/relationship-type)                | Defines the cardinality relationship between joined tables.                 |
| [reversible](/modeling/relationships/parameters/reversible)                               | Controls whether the join can function bi-directionally for topics.         |
| [where\_sql](/modeling/relationships/parameters/where-sql)                                | Adds a WHERE clause to the generated SQL when a join is established.        |


# join_from_view - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-from-view

Defines the source view from which the join originates.

Defines the source view from which the join originates. This parameter works in conjunction with [`join_to_view`](/modeling/relationships/parameters/join-to-view) to establish the relationship between two views in your data model.

## Limitations

Views representing a [data input table (CSV/XLSX upload)](/analyze-explore/data-input-csvs) can't be used in a join unless the table has been uploaded to a database. This requires defining an **Upload schema** for the underlying database connection.

## Syntax

```yaml theme={null}
join_from_view: <source_view>
```

## Properties

<ParamField type="string">
  The name of the source view from which the join originates. This view must exist in your data model.
</ParamField>

## Examples

```yaml title="Join originating from the buyers view" highlight={1} theme={null}
- join_from_view: buyers
  join_from_view_as: users
  join_to_view: user_facts
  join_type: always_left
  on_sql: ${users.id} = ${user_facts.id}
  relationship_type: one_to_one
```


# join_from_view_as - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-from-view-as

Aliases the source view with a new name.

Aliases the source view with a new name. This parameter is often used for multiple joins, such as when both `buyers` and `sellers` are populated via the `users` table.

## Syntax

```yaml theme={null}
join_from_view_as: <alias>
```

## Properties

<ParamField type="string">
  The alias name for the source view. Both the original view name ([`join_from_view`](/modeling/relationships/parameters/join-from-view)) and this alias can be used in the [`on_sql`](/modeling/relationships/parameters/on-sql) parameter.
</ParamField>

<Warning>
  This alias only exists within this relationship's `on_sql` and the topic's [`joins`](/modeling/topics/parameters/joins) parameter. It can't be referenced in a view file's own field or dimension SQL, declared in a topic's [`views`](/modeling/topics/parameters/views) parameter without an `extends` parameter, or used as a join target in a different relationship — doing so produces a `Relationship alias duplicates view name` or `Table not found` error. See [Alias scope](/modeling/views/alias#alias-scope) for the workaround.
</Warning>

## Examples

```yaml title="Re-labels buyers as users in the join" highlight={2} theme={null}
- join_from_view: users
  join_from_view_as: buyers
  join_to_view: user_facts
  join_type: always_left
  on_sql: ${users.id} = ${user_facts.id}
  relationship_type: one_to_one
```


# join_from_view_as_label - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-from-view-as-label

Controls the display name of the source view in the UI when using the join.

Controls the display name of the source view in the UI when using the join. For example, you might want fields from `users` to appear as if they belong to the `buyers` table. In reality, the fields come from `users`, which is aliased in the model and generated in SQL as `user_facts`.

This can be used jointly with [`join_from_view_as`](/modeling/relationships/parameters/join-from-view-as) or used as a way to label a view within a topic.

## Syntax

```yaml theme={null}
join_from_view_as: <alias>
```

## Properties

<ParamField type="string">
  The display name for the source view in the UI.
</ParamField>

## Examples

```yaml title="Label the users view as Buyers in UI" highlight={3} theme={null}
- join_from_view: users
  join_from_view_as: buyers
  join_from_view_as_label: Buyers
  join_to_view: user_facts
  join_type: always_left
  on_sql: ${users.id} = ${user_facts.id}
  relationship_type: one_to_one
```


# join_to_view - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-to-view

Specifies the view to join to the source view.

Specifies the view to join to the source view. This parameter works in conjunction with [`join_from_view`](/modeling/relationships/parameters/join-from-view) to establish the relationship between two views in your data model.

## Limitations

Views representing a [data input table (CSV/XLSX upload)](/analyze-explore/data-input-csvs) can't be used in a join unless the table has been uploaded to a database. This requires defining an **Upload schema** for the underlying database connection.

## Syntax

```yaml theme={null}
join_to_view: <target_view>
```

## Properties

<ParamField type="string">
  The name of the view to join into the source view. This view must exist in your data model.
</ParamField>

## Examples

```yaml title="Join buyers to user_facts" highlight={2} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```


# join_to_view_as - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-to-view-as

Aliases the joined view with a new name.

Aliases the joined view with a new name. This parameter is often used for multiple joins, such as when both `buyers` and `sellers` are populated via the `users` table.

## Syntax

```yaml theme={null}
join_to_view_as: <alias>
```

## Properties

<ParamField type="string">
  The alias name for the joined view. Both the original view name ([`join_to_view`](/modeling/relationships/parameters/join-to-view)) and this alias can be used in the [`on_sql`](/modeling/relationships/parameters/on-sql) parameter.
</ParamField>

<Warning>
  This alias only exists within this relationship's `on_sql` and the topic's [`joins`](/modeling/topics/parameters/joins) parameter. It can't be referenced in a view file's own field or dimension SQL, declared in a topic's [`views`](/modeling/topics/parameters/views) parameter without an `extends` parameter, or used as a join target in a different relationship — doing so produces a `Relationship alias duplicates view name` or `Table not found` error. See [Alias scope](/modeling/views/alias#alias-scope) for the workaround.
</Warning>

## Examples

```yaml highlight={3} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```


# join_to_view_as_label - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-to-view-as-label

Controls the display name of the joined view in the UI when using the join.

Controls the display name of the joined view in the UI when using the join. For example, you might want fields from `user_facts` to appear as if they belong to the `buyers` table. In reality, the fields come from `user_facts`, which is aliased in the model and generated in SQL as `buyer_facts`.

This can be used jointly with [`join_to_view_as`](/modeling/relationships/parameters/join-to-view-as) or used as a way to label a view within a topic.

## Syntax

```yaml theme={null}
join_to_view_as_label: <display_label> 
```

## Properties

<ParamField type="string">
  The display name for the joined view in the UI.
</ParamField>

## Examples

```yaml title="Label the buyer_facts view as Buyers in the UI" highlight={4} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_to_view_as_label: Buyers
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```


# join_type - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/join-type

Specifies the type of SQL join to perform.

Specifies the type of SQL join to perform. This parameter defaults to left join (`always_left`) and supports several standard SQL join types, as well as two directional join types that are specific to Omni.

## Syntax

```yaml theme={null}
join_type: <type>
```

## Properties

<ParamField type="string">
  The type of join to perform. Can be:

  A standard join type:

  * `always_left` - Generates `LEFT JOIN`
  * `inner` - Generates `INNER JOIN`
  * `full_outer` - Generates `FULL JOIN`
  * `cross` - Generates `CROSS JOIN`

  Or a directional join type:

  * `right_left` - Generates a `RIGHT JOIN` when used in the `FROM/TO` direction, and a `LEFT JOIN` when used in the opposite direction
  * `left_right` - Generates a `LEFT JOIN` when used in the `FROM/TO` direction, and a `RIGHT JOIN` when used in the opposite direction
</ParamField>

## Examples

```yaml title="Create LEFT JOIN with always_left" highlight={4} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```

```yaml title="Create LEFT JOIN with left_right type" highlight={4} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: left_right
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```

```yaml title="Create RIGHT JOIN with right_left type" highlight={4} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: right_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```


# on_sql - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/on-sql

Specifies the SQL condition that determines how to perform the join.

Specifies the SQL condition that determines how to perform the join. Supports simple equality joins as well as complex join conditions.

## Syntax

```yaml theme={null}
on_sql: <sql_join_condition>
```

## Properties

<ParamField type="string">
  The SQL condition for matching rows between views. Use `${view_name.field_name}` syntax to reference fields.

  <Tip>
    When using aliased joins, both the original view names ([`join_from_view`](/modeling/relationships/parameters/join-from-view), [`join_to_view`](/modeling/relationships/parameters/join-to-view)) and aliased view names ([`join_from_view_as`](/modeling/relationships/parameters/join-from-view-as), [`join_to_view_as`](/modeling/relationships/parameters/join-to-view-as)) can be used in this parameter.
  </Tip>
</ParamField>

## Examples

```yaml title="Basic equality join" highlight={5} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```

```yaml title="Complex inequality join" highlight={4} theme={null}
- join_from_view: table_1
  join_to_view: table_2
  join_type: always_left
  on_sql: ${table_1.id} > ${table_2.id}
```

```yaml title="Compound join keys" highlight={4} theme={null}
- join_from_view: table_1
  join_to_view: table_2
  join_type: always_left
  on_sql: ${table_1.key_1} = ${table_2.key_1} AND ${table_1.key_2} = ${table_2.key_2}
```


# relationship_type - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/relationship-type

Defines the cardinality relationship between joined tables.

Defines the cardinality relationship between joined tables. This parameter ensures that joins that fan out the result set (i.e., many orders for a single user) do not impact counts or sums. Properly defining the relationship type is crucial for accurate metric calculations.

## Syntax

```yaml theme={null}
relationship_type: <relationship>
```

## Properties

<ParamField type="string">
  The cardinality of the relationship between the joined tables. Can be:

  * `one_to_one` - Each row in the source view matches exactly one row in the joined view
  * `many_to_one` - Multiple rows in the source view can match one row in the joined view
  * `one_to_many` - One row in the source view can match multiple rows in the joined view
  * `many_to_many` - Multiple rows in the source view can match multiple rows in the joined view
  * `assumed_many_to_one` - **Omni-generated**. This is a default join generated by Omni based on naming convention. For example, an `orders` table with a `user_id` and a `users` table with an `id` or `user_id`.

    These joins are intended to accelerate the initial exploration of a data source and can therefore be modified or deleted. To accept the joins as canonical to the model, remove the `assumed_` prefix from the relationship type.
</ParamField>

## Examples

```yaml title="One-to-one relationship between buyers and buyer_facts" highlight={6} theme={null}
- join_from_view: buyers
  join_to_view: user_facts
  join_to_view_as: buyer_facts
  join_type: always_left
  on_sql: ${buyers.id} = ${buyer_facts.id}
  relationship_type: one_to_one
```

```yaml title="Omni-generated assumed_many_to_one" theme={null}
- join_from_view: order_items
  join_to_view: orders
  join_type: always_left
  on_sql: ${order_items.order_id} = ${orders.id}
  relationship_type: assumed_many_to_one
```


# reversible - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/reversible

Controls whether the join can function bi-directionally for topics.

Controls whether the join can function bi-directionally for topics. This parameter allows you to explore data in both directions when two datasets are connected. By default, it's set to `false` to keep your results clean and predictable.

Omni restricts joins in the exploration process to joins that do not fan out the result set. For example, this means that `users` are always available with `orders` (each `order` has one `user`), but will not be shown by default when querying `users` (one `user` has many `orders`, and thus joining `orders` changes the shape of the result set).

To summarize:

* By default, `one_to_many` joins will be created as `many_to_one` joins with `reversible: true`, meaning they will fan out the data set
* One-to-one and many-to-many joins are always reversible as they do not change the shape of the data set, they only add columns
* Many-to-many joins are reversible by default, as they always change the shape of the data

**Note:** this parameter will automatically be removed upon saving if added to one-to-one or many-to-many joins since reversing the direction of these types doesn't change the shape of the data.

## Syntax

```yaml theme={null}
reversible: <boolean>
```

## Properties

<ParamField type="boolean">
  Controls bi-directional join functionality.

  When `false`, you can explore data in one direction: from the source view **to** the joined view. Exploring data in the opposite direction would fan out the result set.

  When `true`, you can explore data in both directions. This may fan out the dataset and create more rows than you started with, which you would need to account for in your analysis.
</ParamField>

## Examples

```yaml theme={null}
- join_from_view: users
  join_to_view: orders
  join_type: always_left
  on_sql: ${users.id} = ${orders.id}
  relationship_type: many_to_one
  reversible: true
```


# where_sql - Relationships
Source: https://docs.omni.co/modeling/relationships/parameters/where-sql

Adds a WHERE clause to the generated SQL when a join is established.

Adds a `WHERE` clause to the generated SQL when a join is established, applying a filter condition to all rows in the query after the join has been performed.

The clause does **not** pre-filter and then join; it joins first and then uses the `WHERE` statement to filter the results.

## Syntax

```yaml theme={null}
where_sql: <sql_filter_condition>
```

## Properties

<ParamField type="string">
  A SQL condition that filters rows after the join is performed. Use `${view_name.field_name}` syntax to reference fields.
</ParamField>

## Examples

```yaml title="Only include rows with order counts less than 20" highlight={6} theme={null}
- join_from_view: users
  join_to_view: orders
  join_type: always_left
  on_sql: ${users.id} = ${orders.id}
  relationship_type: many_to_one
  where_sql: ${orders.count} < 20
```


# Templated filters
Source: https://docs.omni.co/modeling/templated-filters/index

Use Mustache template syntax to inject dynamic, user-driven values into SQL definitions for views and fields in your Omni model.

<Tip>
  Refer to the [Filters documentation](/modeling/filters) for information about defining curated filters directly in your model YAML.
</Tip>

Omni allows parameterization of SQL using the Mustache template engine, which can be used in the definition of both views and fields. This is perhaps best understood through examples.

Templated filters can inject dynamic text into a SQL query, often a dimension or fact table. Our syntax requires an opening and closing reference around the dynamic input, using `{{# }}` to open, and `{{/ }}` to close the dynamic sections. Inside the braces, you use the name of the object, usually of the form `view.field_name.filter` (the word "filter"). This will correspond to a filter\_only field in the view (see examples below). Inside the pair of braces, you will include the lookup value.

## Setting default values

Default values can be set using `{{^ }}default_value_clause{{/ }}` immediately after the existing templated filter syntax.

For example, the following would use a default filter of name like `'foo'`:

```yaml wrap theme={null}
{{# users.filter_field.filter }}name{{/ users.filter_field.filter }}
{{^ users.filter_field.filter }}name like '%foo%'{{/ users.filter_field.filter }}
```

## Examples

<Note>
  Any YAML parameter that expects a string must be wrapped in double quotes if the leading character has special meaning in YAML. For example, `sql: {{ view.field_name.filter }}` would need to be `sql: "{{ view.field_name.filter }}"` to avoid validation errors.
</Note>

### Parameterized WHERE clause in views based on a SQL query

This simple example allows a query-view to be parameterized. This example uses a filter-only field (see more on this in the dedicated section below), but can also reference a field in the view itself.

```yaml theme={null}
# Reference this view as user_fact_example
sql: |
  SELECT
    user_id,
    COUNT(*) AS total_items
  FROM order_items
  WHERE
    {{# schema__user_fact_example.order_date.filter }} order_items.created_at {{/ schema__user_fact_example.order_date.filter}}
    AND {{# schema__user_fact_example.status.filter }} order_items.status {{/ schema__user_fact_example.status.filter}}
  GROUP BY 1

dimensions:
  user_id:
    sql: '"USER_ID"'
  total_items:
    sql: '"TOTAL_ITEMS"'

measures:
  count:
    aggregate_type: count

filters:
  order_date:
    type: timestamp
  status:
    type: string
    suggest_from_field: order_items.status
```

The `filters` will appear as filter-only fields in the field picker, in their own section under the measures section. These can then be used as normal filters, and the specified expression is inserted in place.

<img alt="" />

### Time frame switcher

<Tip>
  In many cases, the [UI-based time frame switcher control](/visualize-present/dashboards/controls) may be a better path.
</Tip>

A field of dynamic granularity can be constructed such that a single filter on a dashboard swaps the granularity for multiple time series in one.

By editing the .view file, it is necessary to add a dynamic dimension and a filter. In the example below, replace all references to `created_date` with the appropriate date field and `order_items` with the fully qualified view reference.

```yaml theme={null}
# In the .view file
dimensions:
  created_date_dynamic:
    sql: |
      CASE
        WHEN {{# schema__order_items.timeframe_selector.filter }} 'Daily' {{/ schema__order_items.timeframe_selector.filter }} THEN ${created_at[date]}
        WHEN {{# schema__order_items.timeframe_selector.filter }} 'Weekly' {{/ schema__order_items.timeframe_selector.filter }} THEN ${created_at[week]}
        WHEN {{# schema__order_items.timeframe_selector.filter }} 'Monthly' {{/ schema__order_items.timeframe_selector.filter }} THEN ${created_at[month]}
      END
    label: Dynamic
    timeframes: [Date]

filters:
  timeframe_selector:
    type: string
    suggestion_list:
      - value: Daily
      - value: Weekly
      - value: Monthly
```

This `timeframe_selector` filter can then be used either in workbooks or on dashboards across multiple tiles to update them all at once.

<img alt="" />

### Conversion rates

A common analytical pattern is to compare conversion rates with 1, 3, 7, 30, or however many days.

For the more static form, one might do something like this:

```yaml theme={null}
# Reference this view as order_items
dimensions:
  days_after_user_signup:
    # assumes a join has been made to a users view
    sql: DATEDIFF(DAY,${users.created_at},${order_items.created_at})

measures:
  count_users_with_order_within_7_days:
    aggregate_type: count_distinct
    sql: ${user_id}
    filters:
      days_after_user_signup:
        less_than: 8
  user_created_to_order_conversion_rate_7d:
    sql: 1.0 * ${count_users_with_order_within_7_days} / NULLIF(${users.count},0)
```

This is very useful, but requires that measures be created for 1, 3, 7, 30, etc. -day conversion rates. We can add a dynamic option:

```yaml theme={null}
measures:
  user_created_to_order_conversion_rate_dynamic:
    sql: |
      1.0 * COUNT(
        CASE
          WHEN {{# order_items.conversion_days.filter }} ${days_after_user_signup} {{/ order_items.conversion_days.filter }}
          THEN ${order_items.user_id}
        END)
      / NULLIF(${users.count},0)
    format: PERCENT_1

filters:
  conversion_days:
    type: number
```

<img alt="" />

### Dynamically filter active subscriptions using date range (SCD2)

If you have data that defines the dates for the beginning of a subscription and the end of a subscription, this example allows end users the ability to filter for active subscriptions during a dynamic time frame.

This utilizes Omni's out of the box time frame selector, so some dates selections will not work well such as "On Day of Month", but any value that is a range of dates or a specific date will return the active subscriptions during that time.

```yaml theme={null}
# table that has subscription start and end data
schema: ...
table_name: your_table_name

dimensions:
  valid_from: {}
  valid_to: {}
  # add a dimension that is set to Active or Not Active depending on date from dynamic filter
  is_active:
    sql: |
      CASE
        WHEN ${valid_from} <= {{filters.your_table_name.subscription_active_date.range_end}} AND ${valid_to} >= {{filters.your_table_name.subscription_active_date.range_start}}
        THEN 'Active'
        ELSE 'Not Active'
      END

# filter only field for setting dynamic time frame
filters:
  subscription_active_date:
    type: timestamp
```

### Dynamically switching database table in a query

In some cases, users may need to be able to quickly switch between multiple tables when performing an analysis. For example, tables with similar data structures but differing data, such as different time grains.

**Note**: The approach described below should be placed in a new view. You can add a view in the model IDE by clicking **File > New View**.

<Warning>
  For some databases, such as Snowflake, you will need to wrap the `{{filters.your_table_name.filter_field.value}}` in `IDENTIFIER()` to cast from a string to a SQL query-able value.
</Warning>

```yaml theme={null}
# code for the query view in IDE
# sql code to dynamically select a table as defined by filter_field filter
sql: |-
  SELECT *
  FROM {{filters.your_table_name.filter_field.value}}

dimensions: ...

# filter only field creating a suggestion list of tables to select
# set to default to the first table in the list
# set to only allow for one table to be selected
filters:
  filter_field:
    type: string
    suggestion_list:
      - value: existing_table_1
      - value: existing_table_2
    default_filter:
      is: existing_table_1
    filter_single_select_only: true
```

### Dynamically filter total count

Dynamically filter a count down to just the count for a specific value. This allows for creating visualizations where you compare the overall count to the count filtered by the dynamic value on a single visualization.

```yaml theme={null}
# code for view in IDE
schema: main
table_name: baby_names_last_five_years

dimensions:
  # baby name in view
  baby_name:
    sql: baby_name
    label: Baby Name

  # count of baby name
  count:
    sql: count
    label: Count

measures:
  # measure that takes count then filters by filter only field
  # reads name select from filter only field (baby_name_filter) then filters the baby_name and then returns the count when true else 0
  count_filter_by_baby_name:
    sql: |
      CASE 
        WHEN {{# main__baby_names_last_five_years.baby_name_filter.filter }} main__baby_names_last_five_years.baby_name {{/ main__baby_names_last_five_years.baby_name_filter.filter }} THEN ${main__baby_names_last_five_years.count}
        ELSE 0
      END
    aggregate_type: sum

filters:
  # filter only field to be used for filtering added meaure (count_filter_by_baby_name) to be the total count for just the selected baby name
  baby_name_filter:
    type: string
    suggest_from_field: main__baby_names_last_five_years.baby_name
```

<img alt="" />

### Dynamic period-over-period with custom date range

Having the ability to create custom date ranges in period over period allows for flexibility to select any date range within each period to compare values against.

In the below example, there is a view file of demo real estate data where two filter-only fields have been added to create the custom date range selectors that will then be used to filter against the added measures that sum the sales\_amount if the date matches the date selected in the custom filter\_only field.

```yaml theme={null}
# Reference this view as main__real_estate_sales
schema: main
table_name: real_estate_sales

# dimensions that already existed on the table trimmed to just dimensions used in templated filter
dimensions:
  ...
  date_recorded:
    sql: '"Date Recorded"'
  sale_amount:
    sql: '"Sale Amount"'
  ...

measures:
  count:
    aggregate_type: count
  # added measures that are filtered by added filter only fields
  # filtered on date_recorded and only return the sale amount if date_recorded matches the custom filter only field date
  previous_period_sale_amount:
    sql: |
      SUM(CASE
        WHEN {{# main__real_estate_sales.previous_period.filter }} ${main__real_estate_sales.date_recorded} {{/ main__real_estate_sales.previous_period.filter }} THEN ${main__real_estate_sales.sale_amount}
        ELSE 0
      END)
  current_period_sale_amount:
    sql: |
      SUM(CASE
        WHEN {{# main__real_estate_sales.current_period.filter }} ${main__real_estate_sales.date_recorded} {{/ main__real_estate_sales.current_period.filter }} THEN ${main__real_estate_sales.sale_amount}
        ELSE 0
      END)

# filter only fields used for creating custom period over period
filters:
  previous_period:
    type: timestamp
    suggest_from_field: main__real_estate_sales.date_recorded
  current_period:
    type: timestamp
    suggest_from_field: main__real_estate_sales.date_recorded
```

<img alt="" />

## Filter-only fields

```yaml theme={null}
filters:
  order_date:
    type: timestamp
  status:
    type: string
    suggest_from_field: order_items.status
```

```yaml theme={null}
filters:
  rolling_window:
    type: string
    suggestion_list:
      - value: "6"
        label: 7 days
      - value: "13"
        label: 14 days
    default_filter:
      is: "6"
    filter_single_select_only: true
```

```yaml theme={null}
filters:
  timeframe_selector:
    type: string
    suggest_from_field: date_spine.date_string
    suggest_from_topic: opp_line_items
```

For specific filter syntax, like measure filters see [here](/modeling/filters).

### aliases

```yaml theme={null}
filter_name:
  aliases: [old_filter_name]
```

Similar to table level aliases, occasionally a field name may change in your database, which can cause content to break. To fix this, we can add `aliases:` to the field in question pointing references from the old field name to the updated field name, restoring content and eliminating content related errors. This behaves similar to table level aliases, as shown

### bind\_to

```yaml theme={null}
filters:
  date_filter:
    type: timestamp
    bind_to: [created_at, updated_at]
```

A list of field names that the filter-only field's filter expression should be applied to. When a filter is applied to this filter-only field, the filter expression will be applied to each field in this list. Filters on dimensions will go into the `WHERE` clause, while filters will go into the `HAVING` clause.

### default\_filter

```yaml theme={null}
status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list:
    - value: Compeleted
    - value: Returned

# note the [] will default to any value here
templated_filter_default_anything:
  type: string
  default_filter:
    is: []

rolling_window:
  type: string
  suggestion_list:
    - value: "6"
      label: 7 days
    - value: "13"
      label: 14 days
  default_filter:
    is: "6"
  filter_single_select_only: true
```

* `default_filter` will automatically populate the filter value in the templated object
* This is often paired with `filter_single_select_only` and `suggestion_list` when a single-selection is required
* For setting the filter arguments, use the [filter syntax](/modeling/filters)

### description

```yaml theme={null}
status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list:
    - value: Compeleted
    - value: Returned
  description: This is for filtering stuff in the status fact table
```

* Metadata about the field, made available in the workbook/dashboard table UI upon hovering over a field with a description, or on right click from the field picker
* Omni expects unquoted text (quotes will be removed / ignored)

### display\_order

```yaml theme={null}
status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list:
    - value: Compeleted
    - value: Returned
  description: This is for filtering stuff in the status fact table
  display_order: 1

other_status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list: [Compeleted, Returned]
  description: This is for filtering stuff in the other status fact table
  display_order: 2
```

* Omni expects a whole number
* This will override the sort order for the field picker, inside the field's grouping (i.e. inside a given view)
  * `display_order` will supersede alphabetical sorting
* For example, if the two fields above in users are given `display_order:` they will float to the top of the field list in users, and the remaining fields would be sorted alphabetically
* To rearrange views, `display_order` can be used at the view level
* For fields inside groups using `group_label`, the group will be ranked with the min of all the fields in the group (i.e. if there are 3 fields with `display_order` of 4, 5 and \{empty}, the group will have a `display_order` of 4)

### filter\_single\_select\_only

```yaml theme={null}
filters:
  rolling_window:
    type: string
    suggestion_list:
      - value: "6"
        label: 7 days
      - value: "13"
        label: 14 days
    default_filter:
      is: "6"
    filter_single_select_only: true
```

* This argument will require the filter field to use a choose-one dropdown rather than the default flexible filter modal
* Recommended with templated filters that require one-and-only-one object

### group\_label

```yaml theme={null}
rolling_window:
  group_label: Time Filters
  type: string
  filter_single_select_only: true
```

* This will nest a group of fields in the field picker for curated organization
* Omni expects unquoted text (quotes will be removed / ignored)
* Note measures and dimensions will still be in separate sections in the field picker under each view
* Fields can be nested under timeframes using the group label - the text rather than the field should be used (i.e. `Created At` not `created_at`)

### hidden

```yaml theme={null}
rolling_window:
  hidden: true
```

* Remove the field from the UI. Still referenceable in the model, but hidden in the workbook UI.
* Expects 'true' or 'false'

### ignored

Likely should not be used with filters, can just delete or comment out if it's not desired in the model

### label

```yaml theme={null}
status:
  type: string
  label: Status Filterer
  suggestion_list:
    - value: "Completed"
    - value: "Returned"
```

* Label will override the field name for all UI appearances of the field
* Omni expects unquoted text (quotes will be removed / ignored)

### required\_access\_grants

You can also conditionally allow access by using pipes (`|`) and ampersands (`&`) to create `OR` and `AND` conditions.

```yaml theme={null}
required_access_grants: [grant_one]

# Grant access if conditions are met for either access grant
required_access_grants: [grant_one|grant_two]

# Grant access if conditions are met for:
# (grant_one OR grant_two)
# AND
# grant_three
required_access_grants: [grant_one|grant_two&grant_three]
```

### suggestion\_list

```yaml theme={null}
filters:
  rolling_window:
    type: string
    suggestion_list:
      - value: "6"
        label: 7 days
      - value: "13"
        label: 14 days
  status:
    type: string
    suggestion_list:
      - value: "Completed"
      - value: "Returned"
```

* Suggestion list will explicitly set the suggestions on

### suggest\_from\_field

```yaml theme={null}
filters:
  timeframe_selector:
    type: string
    suggest_from_field: date_spine.date_string
    suggest_from_topic: opp_line_items
```

```yaml theme={null}
filters:
  status_picker:
    type: string
    suggest_from_field: order_items.status
```

* This argument can be used to populate a filter with another field's values
* Commonly used when the filter is injected in SQL with a corresponding modeled field

### suggest\_from\_topic

```yaml theme={null}
filters:
  timeframe_selector:
    type: string
    suggest_from_field: date_spine.date_string
    suggest_from_topic: opp_line_items
```

* This needs to be paired with `suggest_from_field` and can tune the specific topic (ie access-filters and default filters) for a given suggestion

### type

```yaml theme={null}
filters:
  order_date:
    type: timestamp
  status:
    type: string
```

* Currently, filter-only fields can only be defined in the IDE. They require a name, and a type. The accepted types for a filter-only field are:

  * `boolean`
  * `column` (returns unquoted text, can be used to substitute in column names in query views)
  * `number` *most common*
  * `string` *most common*
  * `timestamp` *most common*

### view\_label

```yaml theme={null}
filters:
  order_date:
    type: timestamp
    view_label: Filters
  status:
    type: string
    view_label: Filters
```

* This will nest a given field under a different view than its default parent view, for example, grouping `user_facts` fields under the `users` view for better organization and discovery
* Note that filters will always be below dimensions and measures
* Sometimes can be valuable to pull all filters into a separate pseudo-view, would do that with the `view` argument as seen here

## Parameters

Parameters can be used in Omni in tandem with filter-only Fields. The value of a filter-only field can be referenced using the structure `{{filters.table_name.field_name.value}}`, and can be used in definitions for other fields. When that filter-only field is applied to a workbook or dashboard, it can be used to change the value of the parameter field, and thus interact with the query accordingly.

Consider using the [filter\_single\_select\_only](/modeling/dimensions/parameters/filter-single-select-only) argument when using a string filter-only field to parameterize some selector.

### Dynamic date range example

```yaml theme={null}
schema: PUBLIC
sql: |-
  SELECT status, sum(sale_price) as sum_sale_price
  FROM public.order_items
  WHERE 1=1
    AND created_at >= {{filters.filter_only_parameter_example.dates.range_start}}
    AND created_at < {{filters.filter_only_parameter_example.dates.range_end}}
  GROUP BY 1

dimensions:
  status:
    sql: '"STATUS"'
  sum_sale_price:
    sql: '"SUM_SALE_PRICE"'

measures:
  count:
    aggregate_type: count

filters:
  dates:
    type: timestamp
```

Users can reference the start or end range of a date filter using the structure `{{filters.table_name.field_name.range_start}}` and `{{filters.table_name.field_name.range_end}}`.

### Dynamic date range comparison example

```yaml theme={null}
dimensions:
  domain: {}
  name: {}
  comparison_period: {}
  revenue: {}
  date:
    timeframes: []
    convert_tz: false
  is_period_one:
    sql: ${date} = TIMESTAMPADD(DAY, -{{filters.service_node_comparision.period_one.value}}, DATE(NOW()))
  is_period_two:
    sql: ${date} = TIMESTAMPADD(DAY, -{{filters.service_node_comparision.period_two.value}}, DATE(NOW()))

measures:
  count:
    aggregate_type: count
  revenue_sum:
    sql: ${service_node_comparision.service_nodes}
    aggregate_type: sum
  revenue_sum_period_one:
    sql: ${service_node_comparision.service_nodes}
    label: Service Nodes Sum Period One
    aggregate_type: sum
    filters:
      is_period_one:
        is: true
  revenue_sum_period_two:
    sql: ${service_node_comparision.service_nodes}
    label: Service Nodes Sum Period Two
    aggregate_type: sum
    filters:
      is_period_two:
        is: true

filters:
  period_one:
    type: string
    suggestion_list:
      - value: "1"
        label: Yesterday
      - value: "182"
        label: 6 Months Ago
    default_filter:
      is: "1"
    filter_single_select_only: true
  period_two:
    type: string
    suggestion_list:
      - value: "1"
        label: Yesterday
      - value: "182"
        label: 6 Months Ago
    default_filter:
      is: "182"
    filter_single_select_only: true
```

This example creates a pair of filtered measures using templated filters to select specific dates.

### Dynamic field examples

```yaml theme={null}
# Note controls are much better for this use case, but may be valuable when you need to riff or put in a query view
dimensions:
  dynamic_dimension:
    sql: {{ filters.view.field_picker.value }}

filters:
  field_picker:
    type: column
    suggestion_list:
      - value: table.field1
        label: Field 1
      - value: table.field2
        label: Field 2
    default_filter:
      is: table.field1
    filter_single_select_only: true
```

This example pipes columns `table.field1` or `table.field2` into the `dynamic_dimension`. For this dynamic dimension, the filter only field requires the use of `type: column`. Note this injects the SQL dialect's column naming convention and will only pass SQL validation if the correct database column reference is defined for the `value` subparameter (e.g. in Snowflake the scoped column names would need to be capitalized).

Consider including the `suggest_from_field` subparameter in the filter only field to generate a list of values from the database's metadata table.

```yaml theme={null}
dimensions:
  state_most_famous_person_dynamic_model:
    sql: |-
      -- DO NOT PARSE
      SNOWFLAKE.CORTEX.COMPLETE( {{ filters.states.dynamic_model.value }}, CONCAT('who is the most famous person from ', ${states.state}) )::varchar

filters:
  dynamic_model:
    type: string
    suggestion_list:
      - value: snowflake-arctic
        label: Snowflake's Default Model (Cheapest)
      - value: claude-3-5-sonnet
        label: Claude's latest
      - value: reka-core
      - value: mistral-large2
      - value: llama3.2-1b
        label: Small Llama model
      - value: mistral-7b
        label: Small Mistral model
      - value: gemma-7b
        label: Small model, best for code completion
    default_filter:
      is: snowflake-arctic
    filter_single_select_only: true
```

Here we've built a Snowflake Cortex dynamic column that can call a model based on the `dynamic_model` specified. The filter is set as single-select, with descriptions on each model to help the end user. This value is piped into the Cortex call to select the given model for analysis using `filters.states.dynamic_model.value`.

### Dynamic date part example

```yaml theme={null}
schema: other
sql: |
  SELECT
    CASE
      WHEN {{ filters.colin_test.timeframe_selector.value }} = 'Daily' THEN date_trunc(created_at, day)
      WHEN {{ filters.colin_test.timeframe_selector.value }} = 'Weekly' THEN date_trunc(created_at, week)
      WHEN {{ filters.colin_test.timeframe_selector.value }} = 'Quarterly' THEN date_trunc(created_at, quarter)
      WHEN {{ filters.colin_test.timeframe_selector.value }} = 'Yearly' THEN date_trunc(created_at, year)
      ELSE date_trunc(created_at, year)
    END as event_date
    , count(*) as dim_count
  FROM users
  GROUP BY 1

dimensions:
  dim_count: {}
  event_date:
    format: "%Y-%m-%d"
    timeframes: []
    primary_key: true

filters:
  timeframe_selector:
    type: string
    suggestion_list:
      - value: Daily
      - value: Weekly
      - value: Monthly
      - value: Quarterly
      - value: Yearly
    default_filter:
      is: Monthly
    filter_single_select_only: true
```

This pattern creates a fact table to be requeried or aggregated using a template filter to set the date part (here BQ SQL). Note we cannot currently inject unquoted strings into the SQL block, but we can instead handle with a CASE statement.

### Self-referential building

We have a few handy parameters that can be leveraged in your models to build joins, dimensions, and measures based on what is present in the query.

The format for calling these parameters is and they will evaluate to `TRUE` or `FALSE`:

* `{{ view_name.field_name.in_query }}` OR `{{ view_name.in_query }}`
* `{{ view_name.field_name.is_selected }}`
* `{{ view_name.field_name.is_filtered }}`

#### in\_query

This will look for the presence of a specific field OR view in the SELECT or WHERE clause of a query.

#### is\_selected

This will look for the presence of a specific field in the SELECT clause of a query.

#### is\_filtered

This will look for the presence of a specific field in the WHERE clause of a query.

**Example of conditional join using `in_query`**

```yaml theme={null}
base_view: inventory_items

joins:
  product_fact: {}

relationships:
  - join_from_view: inventory_items
    join_to_view: product_fact
    join_type: always_left
    on_sql: |-
      CASE
        -- check if inventory_items.product_id is in query
        WHEN {{ inventory_items.product_id.in_query }}
          -- check if there's a match in the fact table
          AND ${inventory_items.product_id} = ${product_fact.product_id}
          THEN 1
        ELSE 0 -- if inventory_items.product_id not present, do not join
      END = 1
    relationship_type: one_to_one
```

**Example of creating measure using `is_selected`**

```yaml theme={null}
max_age:
  sql: ${users.age}
  aggregate_type: max
  description: dummy aggregate for sale_price_per_year_of_life

sale_price_per_year_of_life:
  sql: |-
    CASE
      WHEN {{ users.age.is_selected }}
      THEN ${order_items.sale_price_sum}/${users.max_age}
      ELSE null
    END
```

<Note>
  When `in_query`, `is_selected`, or `is_filtered` are used inside a query view, they normally evaluate against the query view's own inner query. This means they typically answer "nothing selected" or "nothing filtered" once a field is wrapped in a query view, unless the field is selected or filtered within the view's own query definition. To make these variables resolve against the outer query that uses the view instead, use the [`bind_outer_context`](/modeling/query-views/parameters/bind-outer-context) parameter on the query view.
</Note>

You can read more about this pattern in our [community article](https://community.omni.co/t/multiplying-or-dividing-dimensions-and-measures-in-the-data-model-using-in-query/207).


# Topic best practices
Source: https://docs.omni.co/modeling/topics/best-practices

Best practices for designing topics in Omni that balance usability, performance, and maintainability for self-service analytics.

Designing effective topics is about creating a bridge between your data model and your users. A well-designed topic gives users an approachable, curated view of your data that feels familiar and intuitive without requiring SQL or deep knowledge of the underlying data model.

This guide shares best practices for structuring topics that balance usability, performance, and maintainability. Whether you’re migrating an existing model or starting fresh, these recommendations will help you design topics that empower teams to confidently explore data, build dashboards, and answer their own questions.

## Build for your audience

Approach topic design with your business users in mind. Rather than mirroring your database schemas, think through the needs of each department (i.e. Sales, Finance, Marketing, etc). Some departments may be fine with a simple dataset while others will benefit from multiple topics grouped together.

### Avoid analysis paralysis

Topics don't need to be fully planned in advance - you can always add more and refine existing topics as you go.

* **If you're migrating**, you may want to spend some time analyzing current usage and distilling it down to the main topics users will continue to depend on.
* **If you're starting from scratch**, try a model-as-you-go approach. Take an educated guess at building a few key topics and then refine as you go by soliciting feedback. As time goes on you’ll see usage go up and requests start to decrease.

<Check>
  Get insight into how topics are being used with the **Topic Usage summary** in your [**Analytics** dashboard](/administration/analytics).
</Check>

### Curate with metadata

Help your users understand what a topic is and how to use it with metadata:

* Translate table and column names into user-friendly language with labels and [descriptions](/modeling/topics/parameters/description)
* [Group similar topics together](/modeling/topics/parameters/group-label) - such as the `Platform-Specific` group in the accompanying image
* Provide easy starting points with [sample queries](/modeling/topics/parameters/sample-queries)

Check out the [Topic examples](/modeling/topics/examples) for additional examples.

<img alt="Example topics with labels, descriptions, and groups" />

### Be specific

Tailor your topics to focus on specific audiences and use cases rather than trying to cater to everyone at once. Keep in mind that a topic should be easily navigated by a business user - if it has dozens of joins and hundreds of fields, it's likely too large.

When building, keep in mind that:

* **A topic can be as narrow as a single table.** There are still numerous benefits to single-table topics, including the ability to add default filters, AI context, caching policies, etc. Most importantly, this topic will remove all the extra clutter of seeing all possible views at once, many of which may be unrelated.

* **A single table can be used in multiple topics**, so there's no need to worry about being able to only use it once.

  This is common with fact tables. For example, a `users` table might be the base view for its own topic as well as being joined into a separate `Sales` topic. This unlocks the ability to model the table differently for each use case, so you can easily reuse shared logic but tailor specific aspects differently in each topic.

## Favor small topics

While you can build a single large topic, smaller topics are recommended as they:

* Are easier to navigate
* Can create a more focused experience for business users
* Generally translate to simpler queries with less joins, which run faster
* Make model management more straightforward

<Tip>
  Use the **Diagram tab** in the topic editor to visually check whether a topic is getting unwieldy. Topics with more than 20 tables or 50 join relationships won't render in this tab — a useful signal that it may be time to split.

  See the [Creating topics guide](/modeling/topics/setup#review-save-workbook) for more information.
</Tip>

## Keep shared logic in view and relationship files

Since topics act as a curation layer, modeling done in a topic file supersedes the base logic in [model](/modeling/models), [view](/modeling/views), or [relationship](/modeling/relationships) files. This means that shared logic should be kept in the view or relationship files and anything use case-specific should be kept in the topic file.

## Consider many-to-one joins

Omni recommends building topics with `many-to-one` joins, where the base view is the most transactional table and fact tables are selectively joined in. This can help improve the performance of your topics.

Additionally, note that:

* You may need to specify [primary keys](/modeling/dimensions/parameters/primary-key) for these fan-out joins to work
* Even with multiple joins in a topic, Omni will bring in only the required join path to build each query

To further improve performance, consider setting [default filters](/modeling/topics/parameters/default-filters), [caching policies](/modeling/topics/parameters/cache-policy), and [auto-run](/modeling/topics/parameters/auto-run).


# Topic design inspiration
Source: https://docs.omni.co/modeling/topics/examples

Real-world topic design examples from Omni users to inspire how you structure curated datasets for your business use cases.

Every business has its own way of thinking about data. To help you get started, we've put together some examples that are inspired by how other Omni users leverage topics in their own instances.

These examples illustrate how you might structure your topics to align a data model with the questions your users ask most often. When you're ready, check out the [topic design best practices](/modeling/topics/best-practices) to learn how to create efficient, approachable topics using Omni's recommendations.

<Tip>
  Click to enlarge the images.
</Tip>

<Columns>
  <Card title="Software sales">
    <img alt="" />
  </Card>

  <Card title="Hospitality">
    <img alt="" />
  </Card>

  <Card title="Finance">
    <img alt="" />
  </Card>

  <Card title="Retail">
    <img alt="" />
  </Card>

  <Card title="Healthcare">
    <img alt="" />
  </Card>

  <Card title="Media & Entertainment">
    <img alt="" />
  </Card>

  <Card title="SaaS">
    <img alt="" />
  </Card>
</Columns>


# Curating datasets with topics
Source: https://docs.omni.co/modeling/topics/index

Create curated topics in Omni to give non-technical users a self-service way to explore data and build visualizations.

Topics are curated, user-friendly datasets that make it easier for non-technical users to explore, analyze, and create visualizations without writing SQL or needing to deeply understand the underlying data model.

Topics are essential to set up your Omni instance for success. They bring together relevant tables, joins, measures, and dimensions into a logical structure that matches how business users think about their work and allows the data team to curate the UI for easy, intuitive self-service:

<img alt="Comparison of a raw database schema alongside a curated topic that groups related tables, joins, and fields into a user-friendly dataset" />

## Topic basics

<AccordionGroup>
  <Accordion title="How do topics work?">
    Topics are defined within a [model](/modeling) and linked to a specific database connection. They specify a primary base table along with any associated tables that can be joined for analysis. In a topic file, you define what parts of your data model you want used - and how they should be modified - for each use case.
  </Accordion>

  <Accordion title="How are topics helpful?">
    Topics can help you improve:

    * **Self-service** - Curated topics shield end-users from complex database schemas, table relationships, and raw SQL queries. Business users are empowered to self-serve with point-and-click, Excel, and AI without needing to understand the technical aspects of the data model. For example, an analyst could pick fields from the `Order Items` and `Users` tables in the `Orders` topic without needing to think about the underlying joins.

      <img alt="A workbook query using fields from the Order Items and Users tables in the Orders topic, with joins handled automatically" />

    * **AI reliability** - Natural language questions in Omni (i.e. [using Blobby](/ai/queries)) are required to go through topics. This ensures that all questions are routed through the curated datasets that you manage, allowing you to control the context, behavior, and permissions.

      For example, you can choose to [limit which topics can be analyzed by AI](/modeling/models/ai-chat-topics) and contextualize each one differently to achieve better results.

    * **Data curation** - Topics encourage building intuitive, focused experiences that match how your business runs. These datasets can mirror your departmental structure or focus on tailored use cases so that users know exactly where to go to answer their questions. Instead of a massive BI environment with dozens of tables, you can have a few key topics that cover most questions your team needs to answer.

    * **Reusability** - As data adoption grows, refinements made to these curated datasets can be [promoted to the shared model](/modeling/develop/model-management) and directly benefit everyone.

    * **Governance** - Topics allow fine-tuned control over what your users can see. Each topic can be enhanced with [row- or column-level security](/modeling/develop/data-access-control) or even hidden from specific users. You can also use [additional parameters](/modeling/topics/parameters) for tailoring the AI experience, caching behavior, and more to fully customize a topic's behavior.
  </Accordion>

  <Accordion title="How are topics different than my data model?">
    Your data model reflects how the data is structured (i.e. raw relationships, joins & logic living in the warehouse) whereas topics sit on top of that data model and reshape it into business-friendly groupings for easier exploration. Think of topics as a presentation layer tailored for quick insights - they effectively translate your database model into reusable logic for building dashboards and workbooks.

    <img alt="Diagram showing topics as a presentation layer that sits on top of the underlying data model" />
  </Accordion>

  <Accordion title="Why should I use topics if my database is already curated?">
    Your database is likely optimized for data storage and querying, but chances are how your data team interacts with data is different from what your end-users want to see. Think of topics as optimizing the UI experience for business users on top of the already optimized database modeling you have set up.

    If using dbt, your modeling may be a bit closer to how Omni thinks of topics, but you’ll still find plenty of value in being able to design the user experience and apply fine controls over permissions, data access, AI, etc.
  </Accordion>

  <Accordion title="Who should own topic creation and maintenance?">
    We typically see data teams build out the initial datasets, and then stakeholders with business knowledge contribute based on their needs. For large organizations, there may be departmental teams that build on top of the core logic established by data engineers.
  </Accordion>

  <Accordion title="How can I use topics to enhance my Embedded Omni instance?">
    Topics can be a great way to make your data reflect your desired monetization strategy. For example, you may give your base-tier customers access to a few topic-scoped standard dashboards. Then, customers who opt into a higher tier may unlock access to additional topics for more insights. If you’re offering AI querying experiences to your customers, Topics are crucial to generating reliable, accurate results.

    Reach out to your Omni Customer Success manager if you want help designing the right strategy for your business.
  </Accordion>
</AccordionGroup>

## Developing and using topics

<Check>
  Check out the [Topic best practices](/modeling/topics/best-practices) for our recommendations on building efficient, approachable topics. **Not sure what to build?** Get some inspiration from our [Topic examples](/modeling/topics/examples).
</Check>

Omni offers two ways to develop topics: visually (in workbooks) or using code (in the model IDE). You can use one or both of these methods to develop your topics.

<AccordionGroup>
  <Accordion title="Workbooks" icon="book">
    <Note>
      Some settings, such as those controlling cache policies, access grants, and default filters, can only be added using the model IDE.
    </Note>

    There are two ways to create topics in workbooks:

    * **Starting with an existing view.** In a query tab, select the **All view & fields** option in the field browser. Locate the view you want to use, right click, and select **Create topic**.

    * **From a CSV or XLSX upload**. This method requires enabling [data input tables (CSV uploads)](/analyze-explore/data-input-csvs). When uploading the file, users with **Querier permissions or higher** will see a **Create topic** checkbox.

    From here, you can use the visual editor to add metadata, joins, fields, and other settings, as well as visualize the topic's structure with an in-app diagram. Refer to the [Creating topics guide](/modeling/topics/setup) for more information and a step-by-step example.

    **To open the topic editor for an existing topic**, open the topic in a workbook and click **Model > Edit topic**.
  </Accordion>

  <Accordion title="Model IDE" icon="code">
    Using the model IDE allows you to use code to modify a topic's underlying file, which is where the configuration for the topic is stored.

    To get started developing topics in the IDE, we recommend checking out:

    * The [Creating topics guide](/modeling/topics/setup), which will walk you through a step-by-step example
    * The [Topic file parameters reference](/modeling/topics/parameters) for information about supported topic settings
  </Accordion>
</AccordionGroup>

### Using topics in analyses

Once created, users with access to the topics will be able to use them in workbook queries. Refer to the [Building queries on topics guide](/analyze-explore/queries/topics) for more information.

### Deleting topics

<Note>
  **Modeler** or **Connection Admin** permissions are required to delete topics.
</Note>

Deleting a topic will remove the topic's file from the model and break any queries built on the topic. Use the [Content Validator](/modeling/develop/content-validator) to identify and fix issues.

<Steps>
  <Step>
    Open the model you want to work with in the model IDE.
  </Step>

  <Step>
    Locate the topic you want to delete in the **Topics** section.
  </Step>

  <Step>
    Hover over the topic, then click the <Icon icon="ellipsis-vertical" /> icon.
  </Step>

  <Step>
    Click **Delete topic**.
  </Step>

  <Step>
    When prompted, click **OK** to confirm the deletion.
  </Step>
</Steps>

## Composite topics <Badge>BETA</Badge>

<Note>
  Composite topics are currently in beta. They're enabled on all instances — no opt-in required.
</Note>

[Composite topics](/modeling/composite-topics) let you combine two or more topics into a single result set, aligning measures from different fact tables on shared dimensions without fan-out. They're a good fit for multi-fact dashboards and cross-domain KPI reports.

## Tracking topic usage

<Note>
  **Organization Admin** permissions are required to access the **Analytics** dashboard.
</Note>

To track the usage of the topics in your instance, check out the **Topic Usage summary** in the **Model** section of your [**Analytics** dashboard](/administration/analytics). You can use this data to understand which topics your users are using, which ones to prune, and what opportunities there are for new additions.


# access_filters - Topics
Source: https://docs.omni.co/modeling/topics/parameters/access-filters

Limits access to rows in a dataset based on user attributes.

Limits access to rows in a dataset based on user attributes. When enabled, users will be limited to rows in the topic that match their user attribute value. Refer to the [Controlling data access guide](/modeling/develop/data-access-control) for more information.

<Warning>
  Omni expects every user to have a non-null value for any assigned access filter. Errors will arise if the user attribute value is null.
</Warning>

## Syntax

```yaml theme={null}
access_filters:
  - field: "<view_name>.<field_name>"
    user_attribute: "<user_attribute_reference>"
    values_for_unfiltered: ["<value>", ...]
    enable_sql_like_wildcards: true/false
```

## Properties

<ParamField type="object[]">
  A list of access filter configurations that limit row access.

  <Expandable title="access_filters properties">
    <ParamField type="string">
      The field to use as a filter, specified in the format `view_name.field_name`.
    </ParamField>

    <ParamField type="string">
      The reference of the user attribute to filter on.
    </ParamField>

    <ParamField type="string[]">
      User attribute values that allow unrestricted access. Users with these values will not have the access filter applied.

      <Warning>
        Do not use the same value as the attribute's default. Any user who inherits the default — including new users before provisioning and auto-created [email-only users](/administration/users/email-only) — will receive unfiltered data.
      </Warning>
    </ParamField>

    <ParamField type="boolean">
      Determines if exact match (`=`) or `%` wildcard syntax should be applied. Does not automatically add wildcards to the attribute value.

      To achieve pattern matching, manually include the `%` wildcard characters within the user attribute value itself (e.g., setting the attribute to `%@example.com%`). This allows for granular control, enabling exact matches for some users and partial matches for others using the same filter configuration.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Filter by brand_name" theme={null}
access_filters:
  - field: products.brand
    user_attribute: brand_name
    values_for_unfiltered: [all_brands]
    enable_sql_like_wildcards: true
```


# ai_context - Topics
Source: https://docs.omni.co/modeling/topics/parameters/ai-context

Free text that can provide context about a topic to the Omni Agent.

Free text that can provide context to the [Omni Agent](/ai/chat). Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
ai_context: "<context_text>"
```

Or for multiline context:

```yaml theme={null}
ai_context: |
  <multiline_context_text>
```

## Properties

<ParamField type="string">
  Free text that provides context to the Omni Agent. Can include behavioral prompting, instructions for tone, or other guidance to .

  The following references are supported for this field:

  * [**User attributes**](/administration/users/attributes), referenced with `{{omni_attributes.<attribute_name>}}`. This allows you to personalize the context for each user.
  * **Model [`constants`](/modeling/models/constants)**, referenced using `@{constant_name}` syntax. This allows you to maintain reusable instruction blocks such as tone, privacy guidance, and domain context instead of duplicating them.
  * **`omni_llm` namespace,** which allows you to tailor context to specific AI model tiers:

    * `{{ omni_llm.model }}` — Substitutes the active model's family name, which will be one of: `smartest`, `standard`, or `fastest`
    * `{{# omni_llm.<family> }}...{{/ omni_llm.<family> }}` — Conditional sections for specific model tiers. `<family>` must be one of `smartest`, `standard`, or `fastest`
    * `{{^ omni_llm.<family> }}...{{/ omni_llm.<family> }}` — Inverse sections, which apply when the specified tier is **not** used. `<family>` must be one of `smartest`, `standard`, or `fastest`

    See the [Examples section](#model-specific) for more information.
  * **`omni_agent` namespace,** which allows you to scope context to specific AI agents:

    * `{{ omni_agent.name }}` — Substitutes the active agent's name, which will be one of: `analyze`, `build`, or `simple_summarize`
    * `{{# omni_agent.<agent> }}...{{/ omni_agent.<agent> }}` — Conditional sections for specific agents. `<agent>` must be one of `analyze`, `build`, or `simple_summarize`
    * `{{^ omni_agent.<agent> }}...{{/ omni_agent.<agent> }}` — Inverse sections, which apply when the specified agent is **not** used. `<agent>` must be one of `analyze`, `build`, or `simple_summarize`

    See the [Examples section](#agent-specific) for more information.
</ParamField>

## Examples

### Personalized context using user attributes

```yaml title="Personalized context using user attributes" theme={null}
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}}.
```

### Model-specific analysis depth

The following context will apply when the model tier is `smartest`.

```yaml title="Applies when the model tier is smartest" wrap theme={null}
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 }}
```

The following context will apply when the model tier is **not** `smartest`.

```yaml title="Applies when the model tier is not smartest" wrap theme={null}
ai_context: |
  This topic focuses on financial transactions.

  {{^ omni_llm.smartest }}
  Use straightforward joins between directly related tables.
  {{/ omni_llm.smartest }}
```

### Agent-specific context

The following context provides query optimization tips to the `analyze` agent while providing field relationship guidance to the `build` agent.

```yaml title="Agent-specific optimization and field guidance" wrap theme={null}
ai_context: |
  This topic contains e-commerce order data.

  {{# omni_agent.analyze }}
  For optimal query performance, always filter by order_date before joining to customer details. The orders table is very large.
  {{/ omni_agent.analyze }}

  {{# omni_agent.build }}
  When generating field relationships, note that order_id is the primary key. The customer_id foreign key links to the customers table, and product_id links to products.
  {{/ omni_agent.build }}
```

### Using constant references

Reference [`constants`](/modeling/models/constants) to combine reusable context blocks with topic-specific guidance:

```yaml title="Topic file with constant references" theme={null}
ai_context: |
  @{tone} @{domain_finance}
  This topic covers customer invoices. One row is an invoice.
  Focus on payment status and overdue amounts.
```

The `@{tone}` and `@{domain_finance}` references will be substituted with the `constant` values defined in the model file.

### Behavioral prompting

```yaml title="Behavioral prompting" theme={null}
ai_context: |
  you are the head of finance. you are concerned with the status of customer payments. you often need to project into the future how many invoices are due and for how much. you also need to know if any invoices are late so you can reach out to those customers.
```


# ai_fields - Topics
Source: https://docs.omni.co/modeling/topics/parameters/ai-fields

Curates the fields in the topic that are provided to the Omni Agent.

Curates the fields in the topic that are provided to Omni's AI. If defined, only the specified fields will be added to the context window. Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

<Warning>
  This parameter changes what the AI is aware of, not what it has access to. All queries are run with the same permissions as the user and it's possible for the AI to make assumptions about schemas given enough context.
</Warning>

## Syntax

```yaml theme={null}
ai_fields: [ "<field_selector>", ... ]
```

## Properties

<ParamField type="string[]">
  An array of field selectors that determine which fields are provided to the Omni Agent's context window.

  Supports the following operators:

  * Wildcards (`*`)
  * Exclusions (`-`)
  * Tag-based selection (`tag:`)
  * View-specific tag filtering (`view:tag:`)
</ParamField>

## Examples

```yaml theme={null}
ai_fields: [ all_views.*, -tag:dont_use_for_AI, -distribution_centers.* ]
```

```yaml title="Exclude a view but re-include specific tagged fields from that view" theme={null}
ai_fields: [ all_views.*, -internal.*, internal:tag:safe_for_ai ]
```


# always_having_filters - Topics
Source: https://docs.omni.co/modeling/topics/parameters/always-having-filters

Applies a filter to aggregated results (measures) in a query using filter syntax.

Applies a filter to aggregated results (measures) in a query using filter syntax. This parameter is functionally identical to [`always_having_sql`](/modeling/topics/parameters/always-having-sql), but uses [filter syntax](/modeling/filters) instead of SQL.

<Note>
  This parameter must reference **measures**, not dimensions. To filter on non-aggregated fields, use [`always_where_filters`](/modeling/topics/parameters/always-where-filters) instead.
</Note>

When defined, a filter will be inserted into the `HAVING` clause of the generated SQL block of all queries in the topic. Users with the **Querier** role can't change this filter and it will be visible only in the underlying SQL of any queries. This filter is additive to any measure filters specified in the workbook.

## Syntax

```yaml theme={null}
always_having_filters:
  <field_name>:
    <filter_operator>: <value>
```

## Properties

<ParamField type="object">
  A map of measure names to filter conditions that are applied to the `HAVING` clause of all queries in the topic using filter syntax.

  <Expandable title="filter structure">
    <ParamField type="object">
      The measure to filter on, specified as `view_name.measure_name`.

      <Expandable title="filter operators">
        <ParamField type="any">
          The filter operator and value to apply. Refer to the [filter syntax documentation](/modeling/filters) for available operators like `is`, `not`, `greater_than`, `less_than`, etc.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
always_having_filters:
  users.count:
    greater_than: 5
```


# always_having_sql - Topics
Source: https://docs.omni.co/modeling/topics/parameters/always-having-sql

Applies a filter to aggregated results in a query using SQL.

Applies a filter to aggregated results in a query using SQL. This parameter is functionally identical to [`always_having_filters`](/modeling/topics/parameters/always-having-filters), but uses SQL instead of [filter syntax](/modeling/filters).

When defined, a filter will be inserted into the `HAVING` clause of the generated SQL block of all queries in the topic. Users with the **Querier** role can't change this filter and it will be visible only in the underlying SQL of any queries. This filter is additive to any measure filters specified in the workbook.

Conditions should be written using `${}` syntax to reference fields defined in Omni.

<Tip>
  You can generate a syntactically correct condition using the workbook:

  1. In a workbook, add the filter using the UI.
  2. Click the **SQL** button near the top-right corner of the page.
  3. Copy the content of the `HAVING` clause.
  4. Paste the contents into the `always_having_sql` parameter.
</Tip>

## Syntax

```yaml theme={null}
always_having_sql: "<sql_condition>"
```

## Properties

<ParamField type="string">
  A SQL condition that is applied to the `HAVING` clause of all queries in the topic. Use `${}` syntax to reference fields defined in Omni (e.g., `${view_name.measure_name}`).
</ParamField>

## Examples

```yaml theme={null}
always_having_sql: ${users.count} > 5
```


# always_where_filters - Topics
Source: https://docs.omni.co/modeling/topics/parameters/always-where-filters

Applies a filter to all rows in a query using filter syntax.

Applies a filter to all rows in a query using [filter syntax](/modeling/filters). This parameter is functionally identical to [`always_where_sql`](/modeling/topics/parameters/always-where-sql), but uses filter syntax instead of SQL.

<Note>
  When a new `always_where_filter` is defined, it will apply to all existing queries built from that topic as well as any queries created in the future.
</Note>

This parameter is useful for removing invalid data from the topic, such as deleted records or internal testing.

When defined, a filter will be inserted into the `WHERE` clause of the generated SQL block of all queries in the topic. Users with the **Querier** role can't change this filter and it will be visible only in the underlying SQL of any queries. This filter is additive to any filters specified in the workbook. For optional filter conditions, use [`default_filters`](/modeling/topics/parameters/default-filters).

## Syntax

```yaml theme={null}
always_where_filters:
  <field_name>:
    <filter_operator>: <value>
```

## Properties

<ParamField type="object">
  A map of field names to filter conditions that are applied to all queries in the topic using filter syntax.

  <Expandable title="filter structure">
    <ParamField type="object">
      The field to filter on, specified as `view_name.field_name`.

      <Expandable title="filter operators">
        <ParamField type="any">
          The filter operator and value to apply. Refer to the [filter syntax documentation](/modeling/filters) for available operators like `is`, `not`, `contains`, `greater_than`, etc.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Filter rows by a static condition

```yaml theme={null}
always_where_filters:
  users.state:
    is: California
```


# always_where_sql - Topics
Source: https://docs.omni.co/modeling/topics/parameters/always-where-sql

Applies a filter to all rows in a query using SQL.

Applies a filter to all rows in a query using SQL. This parameter is functionally identical to [`always_where_filters`](/modeling/topics/parameters/always-where-filters), but uses SQL instead of [filter syntax](/modeling/filters).

When defined, a filter will be inserted into the `WHERE` clause of the generated SQL block of all queries in the topic. Users with the **Querier** role can't change this filter and it will be visible only in the underlying SQL of any queries. This filter is additive to any filters specified in the workbook. For optional filter conditions, use [`default_filters`](/modeling/topics/parameters/default-filters).

This parameter is useful for removing invalid data from the topic, such as deleted records or internal testing.

Conditions should be written using `${}` syntax to reference fields defined in Omni.

<Tip>
  You can generate a syntactically correct condition using the workbook:

  1. In a workbook, add the filter using the UI.
  2. Click the **SQL** button near the top-right corner of the page.
  3. Copy the content of the `WHERE` clause.
  4. Paste the contents into the `always_where_sql` parameter.
</Tip>

## Syntax

```yaml theme={null}
always_where_sql: "<sql_condition>"
```

## Properties

<ParamField type="string">
  A SQL condition that is applied to all queries in the topic. Use `${}` syntax to reference fields defined in Omni (e.g., `${view_name.field_name}`).
</ParamField>

## Examples

### Filter rows by a static condition

```yaml theme={null}
always_where_sql: ${order_items.sale_price} != 0
```

### Filter rows using user attributes

You can reference [user attributes](/administration/users/attributes) with `{{omni_attributes.<name>}}` to enforce per-user row-level filtering.

Filter rows to the current user's brand:

```yaml theme={null}
always_where_sql: ${products.brand} = '{{omni_attributes.brand_name}}'
```

Filter rows to the current user's email using the built-in `omni_user_email` attribute:

```yaml theme={null}
always_where_sql: ${orders.user_email} = '{{omni_attributes.omni_user_email}}'
```

<Warning>
  Unlike [`access_filters`](/modeling/topics/parameters/access-filters), `always_where_sql` does not fail closed when a referenced user attribute has no value for the current user. The Mustache reference is interpolated as-is, so a missing or `null` attribute value produces a comparison like `${orders.user_email} = ''`, which may silently return unintended rows depending on your database's semantics.

  If you are using `always_where_sql` for row-level security, either:

  * Use [`access_filters`](/modeling/topics/parameters/access-filters) instead — Omni requires a non-null user attribute value and errors otherwise.
  * Set a safe default on the user attribute (for example, a value that matches no rows) and never leave the attribute unset.
  * Explicitly guard against empty values in the SQL condition itself.
</Warning>


# auto_run - Topics
Source: https://docs.omni.co/modeling/topics/parameters/auto-run

Forces all queries using the topic to require a run click to return new results.

<Warning>
  If defined, this parameter will override the model-level [`auto_run`](/modeling/models/auto-run) parameter.
</Warning>

Forces all queries using the topic to require a run click to return new results. This can be useful if there are cost concerns on running queries as they are built, but it will reduce UI interactivity.

## Syntax

```yaml theme={null}
auto_run: true/false
```

## Properties

<ParamField type="boolean">
  Controls whether queries using the topic automatically run. When set to `false`, users must click a run button to execute queries. When set to `true`, queries run automatically.
</ParamField>

## Examples

```yaml theme={null}
auto_run: false
```


# base_view - Topics
Source: https://docs.omni.co/modeling/topics/parameters/base-view

Defines the base view for the topic.

<Warning>
  This parameter is required in topic files.
</Warning>

Defines the base view for the topic.

<Note>
  If a topic's `base_view` is ignored or excluded by model-level directives ([`ignored_views`](/modeling/models/ignored-views), [`ignored_schemas`](/modeling/models/ignored-schemas), [`included_views`](/modeling/models/included-views), [`included_schemas`](/modeling/models/included-schemas)) or by the view's [`ignored`](/modeling/views/parameters/ignored) parameter, it will be suppressed. This means that the topic will not appear in the topic picker or be included in model validation.
</Note>

## Syntax

```yaml theme={null}
base_view: <view_name>

# Use <schema>__<view> to specify a schema
base_view: <schema>__<view_name>
```

## Properties

<ParamField type="string">
  The base view for the topic. Use `<schema>__<view>` format to specify a schema. Values should be unquoted; quotes will be removed/ignored upon saving.
</ParamField>

## Examples

```yaml title="View only" theme={null}
base_view: users
```

```yaml title="Schema and view" theme={null}
base_view: main__users
```


# base_view_label - Topics
Source: https://docs.omni.co/modeling/topics/parameters/base-view-label

Defines the display name of the table in the workbook when it is accessed from the topic.

Defines the display name of the topic's base view when it is accessed in the workbook from the topic. This can be helpful for conveying the table's meaning in a specific context.

For example, the `order_items` view can be referred to as `Sold Items` in a financial context, which could help a Finance team understand that the table contains sale records.

## Syntax

```yaml theme={null}
base_view_label: <label>
```

## Properties

<ParamField type="string">
  The display name for the base view when accessed from the topic. Values should be unquoted.
</ParamField>

## Examples

```yaml theme={null}
base_view: order_items
base_view_label: Sold Items
```


# cache_policy - Topics
Source: https://docs.omni.co/modeling/topics/parameters/cache-policy

Defines the cache policy for the topic.

Defines the cache policy for the topic. Cache policies are defined at the model level using the [`cache_policies`](/modeling/models/cache-policies) parameter.

## Syntax

```yaml theme={null}
cache_policy: <policy_name>
```

## Properties

<ParamField type="string">
  The name of a cache policy defined in the model file. Must reference a policy from the model's [`cache_policies`](/modeling/models/cache-policies) configuration.
</ParamField>

## Examples

```yaml theme={null}
cache_policy: daily_cache_policy
```


# default_filters - Topics
Source: https://docs.omni.co/modeling/topics/parameters/default-filters

Applies a filter to all rows in a topic.

Applies a filter to all rows in a topic. Filters created using this parameter are visible in workbooks and can be removed by users. For required filter conditions, use [`always_where_sql`](/modeling/topics/parameters/always-where-sql).

<Note>
  When a new `default_filter` is defined, it will only apply to new queries. The filter will not be added to existing queries.
</Note>

Refer to the [Filters documentation](/modeling/filters) for filter examples and syntax details.

## Syntax

```yaml theme={null}
default_filters:
  <view_name>.<field_name>:
    <filter_operator>: <value>
```

## Properties

<ParamField type="object">
  A map of field names to filter conditions. Each key is a field in the format `view_name.field_name`, and the value is an object containing filter operators and values. Refer to the [Filters documentation](/modeling/filters) for available operators and syntax.
</ParamField>

## Examples

```yaml theme={null}
default_filters:
  users.state:
    is: California
```


# default_row_limit - Topics
Source: https://docs.omni.co/modeling/topics/parameters/default-row-limit

Sets the default row limit for new queries using the topic.

Sets the default row limit for new queries using the topic. When set, the default row limit will be applied to queries that are created **after** the limit is defined.

If a model-level default row limit isn't defined, the system default of 1,000 will be used instead.

<Warning>
  If defined, this parameter will override the model-level [`default_row_limit`](/modeling/models/default-row-limit) parameter.
</Warning>

## Syntax

```yaml theme={null}
default_row_limit: number
```

## Properties

<ParamField type="integer">
  The default number of rows to return for new queries using this topic. Must be between 1 and 50,000.
</ParamField>

## Examples

```yaml title="Set default row limit to 2,000" theme={null}
default_row_limit: 2000
```


# description - Topics
Source: https://docs.omni.co/modeling/topics/parameters/description

Free text that describes the topic.

Free text that describes the topic. Descriptions are visible in the workbook, specifically in the topic switcher of the **Fields & Topics** panel.

For example, you could add copy that describes the type of analyses users can create using the topic.

## Syntax

```yaml theme={null}
# Single line description
description: <description_text>

# Multi-line description
description: |
  <multiline_description_text>
```

## Properties

<ParamField type="string">
  Free text that describes the topic. For multiline descriptions or descriptions containing special characters like colons, use the pipe (`|`) syntax. Values should be unquoted.
</ParamField>

## Examples

```yaml title="Single line description" theme={null}
description: All transactions related to orders from the online store.
```

```yaml title="Multi-line description" theme={null}
description: |
  Transactions from: California, Washington, and Oregon
```


# display_order - Topics
Source: https://docs.omni.co/modeling/topics/parameters/display-order

Defines the order that topics display in the field picker.

Defines the order that topics display in the field picker. By default, topics are sorted alphabetically. Defining a `display_order` will override this default for the topic.

## Syntax

```yaml theme={null}
display_order: <number>
```

## Properties

<ParamField type="integer">
  The display order of the topic in the field picker. Must be a whole number. Topics with lower numbers appear first.
</ParamField>

## Examples

```yaml theme={null}
display_order: 3
```


# extends - Topics
Source: https://docs.omni.co/modeling/topics/parameters/extends

Allows for inheriting and overriding another topic inside of Omni.

Allows for inheriting and overriding another topic inside of Omni. The extended topic will inherit the attributes of the base or template topic.

Additional attributes - such as joins or filters - can be added to the extended topic and will be scoped only to the extended topic.

If attributes included in the extended topic are also defined in the base topic, the values in the extended topic will override the values in the base topic.

## Syntax

```yaml theme={null}
extends: [<topic_name>]
# topic_name is the file name of the topic. If file name is "User Orders" in 
# model IDE then reference as user_orders
```

## Properties

<ParamField type="string[]">
  An array containing the name of the topic to extend. The current topic will inherit all attributes from the specified topic, with the ability to override or add additional attributes.
</ParamField>

## Examples

```yaml base_topic theme={null}
default_filters:
  state:
    is: California
```

```yaml extended_topic theme={null}
extends: [base_topic]

# Default filters for extended_topic will be 
# `New York` instead of base_topic's `California`
default_filters:
  state:
    is: New York
```


# fields - Topics
Source: https://docs.omni.co/modeling/topics/parameters/fields

Restricts which fields can be queried in the topic.

Restricts which fields can be queried in the topic. By default, all fields from the base view and joined views are included.

## Behavior

The `fields` directive enforces restrictions at query runtime, not just in the field browser. Queries attempting to use fields excluded by this directive (or fields that depend on excluded fields) will return an error.

## Syntax

```yaml theme={null}
fields: [<field_selector>, ...]
```

## Properties

<ParamField type="string[]">
  An array of field selectors that determine which fields are available in the topic. Supports the following operators:

  | Operator           | Description                                              | Order of operations |
  | ------------------ | -------------------------------------------------------- | ------------------- |
  | `all_views.*`      | Targets all fields from all views in the topic           | 1                   |
  | `view.*`           | Targets all fields in a view                             | 2                   |
  | `tag:<value>`      | Targets fields and views with the specified tag          | 3                   |
  | `view:tag:<value>` | Targets fields with the specified tag in a specific view | 4                   |
  | `view.field`       | Targets a specific field                                 | 5                   |

  Omni will evaluate the operators according to the **Order of operations** value in the above table. This means `all_views` is evaluated first, then specific views, and so on. This allows you to exclude views and then add specific fields back in.

  <Tip>
    To exclude a view, tag, or field, prefix the clause with a `-`. For example: `-users.*`
  </Tip>
</ParamField>

## Examples

```yaml title="Only include the users view" theme={null}
fields: [users.*]
```

```yaml title="Exclude the users view" theme={null}
fields: [all_views.*, -users.*]
```

```yaml title="Exclude only the users.id field" theme={null}
fields: [all_views.*, -users.id]
```

```yaml title="Exclude fields with the pii tag" theme={null}
fields: [all_views.*, -tag:pii]
```

```yaml title="Add the user_facts.lifetime_value back in after excluding the user_facts view" theme={null}
fields: [all_views.*, -user_facts.*, user_facts.lifetime_value]
```

```yaml title="Remove the users.acquisition_cost field from the fields targeted by the marketing tag" theme={null}
fields: [-all_views.*, tag:marketing, -users.acquisition_cost]
```

```yaml title="Include only marketing-tagged fields from the internal__workspaces view" theme={null}
fields: [internal__workspaces:tag:marketing]
```

```yaml title="Exclude PII-tagged fields from the users view" theme={null}
fields: [all_views.*, -users:tag:pii]
```

```yaml title="Exclude an entire view but re-include specific tagged fields from that view" theme={null}
fields: [all_views.*, -internal__workspaces.*, internal__workspaces:tag:marketing]
```


# group_label - Topics
Source: https://docs.omni.co/modeling/topics/parameters/group-label

Defines the group the topic belongs to.

Defines the group the topic belongs to. This is useful for improving the organization and navigation of topics in workbooks or the IDE. For example, you could group topics together by dataset (`Salesforce`), team (`Marketing`), or analytical area (`Product usage`).

Topics without a `group_label` will display as 'ungrouped' below topic groups in the topic switcher.

## Syntax

```yaml theme={null}
group_label: <group_name>
```

## Properties

<ParamField type="string">
  The name of the group this topic belongs to. Values should be unquoted.
</ParamField>

## Examples

```yaml theme={null}
group_label: Marketing
```


# hidden - Topics
Source: https://docs.omni.co/modeling/topics/parameters/hidden

Removes the topic from the workbook.

Removes the topic from the workbook. The topic can still be referenced in the model.

## Syntax

```yaml theme={null}
hidden: true/false
```

## Properties

<ParamField type="boolean">
  Controls whether the topic is visible in the workbook. When set to `true`, the topic is hidden from users but can still be referenced in the model.
</ParamField>

## Examples

```yaml theme={null}
hidden: true
```


# Topic file parameters
Source: https://docs.omni.co/modeling/topics/parameters/index

Topic files are used to define configuration for individual topics.

| Parameter                                                                      | Description                                                                                                                                                                             |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [access\_filters](/modeling/topics/parameters/access-filters)                  | Limits access to rows in a dataset based on user attributes.                                                                                                                            |
| [ai\_context](/modeling/topics/parameters/ai-context)                          | Free text that can provide context about a topic to the Omni Agent.                                                                                                                     |
| [ai\_fields](/modeling/topics/parameters/ai-fields)                            | Curates the fields in the topic that are provided to the Omni Agent.                                                                                                                    |
| [always\_having\_filters](/modeling/topics/parameters/always-having-filters)   | Applies a filter to aggregated results (measures) in a query using filter syntax.                                                                                                       |
| [always\_having\_sql](/modeling/topics/parameters/always-having-sql)           | Applies a filter to aggregated results in a query using SQL.                                                                                                                            |
| [always\_where\_filters](/modeling/topics/parameters/always-where-filters)     | Applies a filter to all rows in a query using filter syntax.                                                                                                                            |
| [always\_where\_sql](/modeling/topics/parameters/always-where-sql)             | Applies a filter to all rows in a query using SQL.                                                                                                                                      |
| [auto\_run](/modeling/topics/parameters/auto-run)                              | Forces all queries using the topic to require a run click to return new results.                                                                                                        |
| [base\_view](/modeling/topics/parameters/base-view)                            | **Required**. Defines the base view for the topic.                                                                                                                                      |
| [base\_view\_label](/modeling/topics/parameters/base-view-label)               | Defines the display name of the table in the workbook when it is accessed from the topic.                                                                                               |
| [cache\_policy](/modeling/topics/parameters/cache-policy)                      | Defines the cache policy for the topic.                                                                                                                                                 |
| [default\_filters](/modeling/topics/parameters/default-filters)                | Applies a filter to all rows in a topic. Filters created using this parameter are visible in workbooks and can be removed by users.                                                     |
| [default\_row\_limit](/modeling/topics/parameters/default-row-limit)           | Sets the default row limit for new queries using the topic. Overrides the model-level setting.                                                                                          |
| [description](/modeling/topics/parameters/description)                         | Free text that describes the table.                                                                                                                                                     |
| [display\_order](/modeling/topics/parameters/display-order)                    | Defines the order that topics display in the field picker.                                                                                                                              |
| [extends](/modeling/topics/parameters/extends)                                 | Allows for inheriting and overriding another topic inside of Omni.                                                                                                                      |
| [fields](/modeling/topics/parameters/fields)                                   | Restricts which fields can be queried in the topic.                                                                                                                                     |
| [group\_label](/modeling/topics/parameters/group-label)                        | Defines the group the topic belongs to.                                                                                                                                                 |
| [hidden](/modeling/topics/parameters/hidden)                                   | Removes the topic from the workbook.                                                                                                                                                    |
| [joins](/modeling/topics/parameters/joins)                                     | Declares other views as part of the topic.                                                                                                                                              |
| [label](/modeling/topics/parameters/label)                                     | Defines a display name for the topic.                                                                                                                                                   |
| [owners](/modeling/topics/parameters/owners)                                   | A list of email addresses indicating who the owners of the topic are.                                                                                                                   |
| [relationships](/modeling/topics/parameters/relationships)                     | Defines a list of topic-level joins.                                                                                                                                                    |
| [required\_access\_grants](/modeling/topics/parameters/required-access-grants) | Defines a list of access grants for the topic, which are used to control access.                                                                                                        |
| [sample\_queries](/modeling/topics/parameters/sample-queries)                  | Defines a list of sample queries that could be performed on the topic.                                                                                                                  |
| [skills](/modeling/topics/parameters/skills)                                   | Defines a set of instructions for the Omni AI that users can trigger with a button click. **Scheduled to be deprecated in favor of [skills](/ai/skills) created from the Skills page**. |
| [tags](/modeling/topics/parameters/tags)                                       | Organizes topics by category.                                                                                                                                                           |
| [template](/modeling/topics/parameters/template)                               | Marks a topic as a template only accessible through `extends` and disables model validation.                                                                                            |
| [views](/modeling/topics/parameters/views)                                     | Allows customization of views only in the context of the topic.                                                                                                                         |
| [warehouse\_override](/modeling/topics/parameters/warehouse-override)          | Specifies a different warehouse to use for queries using this topic.                                                                                                                    |
| [week\_start\_day](/modeling/topics/parameters/week-start-day)                 | Overrides the model-level week start day for queries scoped to the topic.                                                                                                               |


# joins - Topics
Source: https://docs.omni.co/modeling/topics/parameters/joins

Declares other views as part of the topic.

<Note>
  Topics created from [data input tables or uploaded CSV/XLSX files](/analyze-explore/data-input-csvs) can't be joined to other data.
</Note>

Declares other views as part of the topic. To include multiple tables, nest the table under the table it joins through.

<Tip>
  The final table in each node - specifically, those without children - requires an empty bracket pair `{}`
</Tip>

## Syntax

```yaml theme={null}
joins:
  <view_name>:
    <nested_view_name>: {}
  <another_view_name>: {}
```

## Properties

<ParamField type="object">
  A nested object structure that declares which views to include in the topic. Views are nested under the views they join through. Final views in each branch must end with an empty object `{}`.
</ParamField>

## Examples

```yaml theme={null}
joins:
  inventory_items:                  # Includes inventory_items in the topic
    products:                       # Joins products to inventory_items
      distribution_centers: {}      # Joins distribution_centers to products
  users: {}                         # Includes users in the topic
```


# label - Topics
Source: https://docs.omni.co/modeling/topics/parameters/label

Defines a display name for the topic.

Defines a display name for the topic. This will override the topic's name as it displays in the workbook.

## Syntax

```yaml theme={null}
label: <display_name>
```

## Properties

<ParamField type="string">
  The display name for the topic that appears in the workbook. Values should be unquoted.
</ParamField>

## Examples

```yaml theme={null}
label: California
```


# owners - Topics
Source: https://docs.omni.co/modeling/topics/parameters/owners

A list of email addresses indicating who owns the topic.

A list of email addresses indicating who owns the topic.

This information can be used as context by the AI to determine who is the best person to answer questions about a query or its results.

## Syntax

```yaml theme={null}
owners: [<email>, ...]
```

## Properties

<ParamField type="string[]">
  An array of email addresses for the topic owners. This information is used by the AI to identify subject matter experts for questions about queries or results.
</ParamField>

## Examples

```yaml theme={null}
owners: [blobby@blobsrus.com, blob.ross@blobsrus.com]
```


# relationships - Topics
Source: https://docs.omni.co/modeling/topics/parameters/relationships

Defines a list of topic-level joins.

<Note>
  Views representing a [data input table or uploaded CSV/XLSX files](/analyze-explore/data-input-csvs#limitations) can't be used in a join unless the table has been uploaded to a database.
</Note>

Defines a list of topic-level joins. Joins defined using this parameter will only be available to the topic where they are declared. This can be useful for one-off use cases, rare aliasing, or utilizing different join organization schemes. Refer to the [Relationships & Joins documentation](/modeling/relationships) for more information about top-level and global relationships.

User attributes (`{{ omni_attributes.<user_attribute> }}`) can be used in joins to create access filtered joins, which can be useful when you want to keep all rows in the dataset but limit access to the metadata.

## Syntax

```yaml theme={null}
relationships:
  - join_from_view: <view_name>
    join_to_view: <view_name>
    join_to_view_as: <alias>
    join_type: <join_type>
    on_sql: <join_condition>
    relationship_type: <relationship_type>
```

## Properties

<ParamField type="object[]">
  An array of relationship objects that define topic-level joins. These joins are only available within the topic where they are declared.

  <Expandable title="relationships properties">
    <ParamField type="string">
      The view to join from.
    </ParamField>

    <ParamField type="string">
      The view to join to.
    </ParamField>

    <ParamField type="string">
      An alias for the joined view, useful for creating multiple joins to the same table.
    </ParamField>

    <ParamField type="string">
      The type of join (e.g., `always_left`, `always_inner`, `left`, `inner`).
    </ParamField>

    <ParamField type="string">
      The SQL condition for the join. Can include user attributes using `{{ omni_attributes.<user_attribute> }}` syntax.
    </ParamField>

    <ParamField type="string">
      The relationship cardinality (e.g., `many_to_one`, `one_to_many`, `one_to_one`, `many_to_many`).
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Join order_items to buyers" theme={null}
relationships:
  - join_from_view: order_items
    join_to_view: users
    join_to_view_as: buyers
    join_type: always_left
    on_sql: ${buyers.id} = ${order_items.buyer_id}
    relationship_type: many_to_one
```

```yaml title="Filtered join using user attributes" theme={null}
relationships:
  - join_from_view: order_items
    join_to_view: users
    join_to_view_as: sellers
    join_type: always_left
    on_sql: ${sellers.id} = ${order_items.seller_id} AND ${sellers.organization_id} = {{ omni_attributes.seller_org_id }}
    relationship_type: many_to_one
```


# required_access_grants - Topics
Source: https://docs.omni.co/modeling/topics/parameters/required-access-grants

Defines a list of access grants for the topic, which are used to control access.

Defines a list of access grants for the topic, which are used to control access. The values of this parameter must match the name of an access grant in the model file's [`access_grants`](/modeling/models/access-grants) parameter.

You can also conditionally allow access by using pipes (`|`) and ampersands (`&`) to create `OR` and `AND` conditions.

Refer to the [Controlling data access guide](/modeling/develop/data-access-control) for more information and examples.

## Syntax

```yaml theme={null}
required_access_grants: [<grant_name>]

# OR condition
required_access_grants: [<grant_one>|<grant_two>]

# AND/OR conditions
required_access_grants: [<grant_one>|<grant_two>&<grant_three>]
```

## Properties

<ParamField type="string[]">
  An array of access grant names that control access to the topic. Each value must match an access grant defined in the model file. Use `|` for `OR` conditions and `&` for `AND` conditions within the same array element.
</ParamField>

## Examples

```yaml title="Define one required access grant" theme={null}
required_access_grants: [marketing]
```

```yaml title="Grant access if conditions are met for either access grant" theme={null}
required_access_grants: [marketing|sales]
```

```yaml title="Grant access if conditions are met for marketing OR sales AND product" theme={null}
required_access_grants: [marketing|sales&product]
```


# sample_queries - Topics
Source: https://docs.omni.co/modeling/topics/parameters/sample-queries

Defines a list of sample queries that could be performed on the topic.

Defines a list of sample queries that could be performed on the topic, which is used:

* **To present example queries** when a topic is selected in the workbook or using the [Omni Agent](/ai/chat).

  To hide the query, set the `hidden` parameter to `true`.
* [**By the Omni Agent to improve results.**](/ai/chat) To exclude the query from the topic's AI context, set the `exclude_from_ai_context` to `true`.

You can add a workbook query to this parameter using one of the following methods:

* **From the Model menu**: Click **Model > Save as sample query to topic** in the workbook.
* **From the inspector**: Click the <Icon icon="bug" /> near the bottom left corner of the page to open the [workbook inspector](/analyze-explore/workbook-inspector). Click **Copy query and visualization YAML** in the inspector header to copy the query and visualization configuration in the sample query format, then paste it into your topic file in the model IDE.

## Syntax

```yaml theme={null}
sample_queries:
  <query_name>:
    query:
      fields: [ "<field_one>", "<field_two>", ... ]
      base_view: "<base_view_name>"
      calculations:
        <calculation_name>:
          sql: "<sql_expression>"
      limit: <number>
      sorts:
        - field: "<field_name>"
          desc: true/false
      topic: "<topic_name>"
    description: "<query_description>"
    hidden: true/false
    prompt: "<natural_language_prompt>"
    ai_context: "<ai_context_description>"
    exclude_from_ai_context: true/false
```

## Properties

<ParamField type="object">
  A map of queries, where each key is the name of a sample query.

  <Expandable title="sample_queries properties">
    <ParamField type="object">
      The name of the sample query (e.g., "Summary Stats"). Each query is defined as a key in the `sample_queries` object.

      <Expandable title="query properties">
        <ParamField type="object">
          The query definition object containing the structure of the query to be executed.

          <Expandable title="query properties">
            <ParamField type="string[]">
              List of fields to include in the query.
            </ParamField>

            <ParamField type="string">
              The base view or topic to query from.
            </ParamField>

            <ParamField type="object">
              Optional calculations to include in the query. Each calculation is defined with a name and SQL expression.

              <Expandable title="calculation properties">
                <ParamField type="string">
                  The SQL expression for the calculation.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="number">
              Maximum number of rows to return.
            </ParamField>

            <ParamField type="object[]">
              List of fields to sort the results by.

              <Expandable title="sort properties">
                <ParamField type="string">
                  The field name to sort by.
                </ParamField>

                <ParamField type="boolean">
                  When set to `true`, sorts the field in descending order. Omit or set to `false` to sort in ascending order.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="string">
              The name of the topic used in the query, if applicable.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField type="string">
          A human-readable description of what the query does or what insights it provides.
        </ParamField>

        <ParamField type="boolean">
          When set to `true`, hides the query from being presented as an example query in the workbook or embedded Omni Agent.
        </ParamField>

        <ParamField type="string">
          A natural language prompt that represents how a user might ask for this query. Used by the Omni Agent.
        </ParamField>

        <ParamField type="string">
          Additional context to help the Omni Agent understand how to use this query or what it demonstrates.
        </ParamField>

        <ParamField type="boolean">
          When set to `true`, excludes this query from the topic's AI context, preventing the AI from using it as a reference.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
sample_queries:
  Summary Stats:
    query:
      fields: [ order_items.sale_price_sum, users.count, calc_1 ]
      base_view: order_items
      calculations:
        calc_1:
          sql: OMNI_FX_SAFE_DIVIDE(${order_items.sale_price_sum}, ${users.count})
      limit: 1000
      sorts:
        - field: order_items.sale_price_sum
          desc: true
      topic: order_items
    description: Total Revenue, Users and Revenue per User
    hidden: false
    prompt: show me total revenue, count of users and revenue per user
    ai_context: uses a calculation to compute avg. revenue per user
    exclude_from_ai_context: false
```


# skills - Topics
Source: https://docs.omni.co/modeling/topics/parameters/skills

Defines a set of instructions for the Omni Agent that users can trigger with a button click.

<Note>
  Model-defined skills (skills defined with this parameter) will be deprecated in the near future. Skills defined using this parameter will continue to work, but going forward, create skills using the Omni Agent or **Skills** page instead. See [AI skills](/ai/skills) for more information.
</Note>

Defines a set of instructions for the Omni Agent that users can trigger with a button click.

When triggered, the AI follows those instructions — querying data, summarizing results, interacting with the user, or walking through a multi-step process — all without the user needing to write a prompt. Each defined skill will display as a button in the [Omni Agent](/ai/chat).

See the [Skills guide](/ai/skills) for more information about this feature, including use cases and best practices.

## Syntax

```yaml theme={null}
skills:
  <skill_id>:
    label: <string>
    input: |
      <string>
    description: |
      <string>
    required_access_grants: [ <access_grant_name> ]
```

## Properties

<ParamField type="object">
  A map of skills, each defined with a unique `skill_id`.

  <Expandable title="skill properties">
    <ParamField type="string">
      A unique name for the skill. Use underscores for spaces.

      <Expandable title="skill_id properties">
        <ParamField type="string">
          The display name shown on the skill button. Keep this short — aim for 2-4 words that clearly describe the task.
        </ParamField>

        <ParamField type="string">
          An opening message that sets the initial interaction. This is sent to the AI before the `description` and is useful for:

          * Greeting the user and explaining what the skill does
          * Asking the user for input before proceeding (e.g., an account name or date range)

          When `input` is set, the AI will typically respond to the `input` first, then use the `description` as its instructions for the rest of the conversation.
        </ParamField>

        <ParamField type="string">
          The instructions sent to the AI when the skill is triggered. This can range from a single sentence to a detailed, multi-step prompt with specific output formats, decision logic, and references to topics.

          Write this as if you're instructing an analyst: be specific about which data to query, how to structure the output, and what steps to follow.
        </ParamField>

        <ParamField type="string[]">
          Controls skill visibility based on user access grants. Skills with this parameter will only appear to users who hold the required access grants.

          Values must match [`access_grants`](/modeling/models/access-grants) defined in the model file. Supports conditional grant expressions using `|` for OR and `&` for AND conditions.

          **Note**: This controls visibility only. Actual data access at execution time is still enforced by access grants on the underlying topics, fields, and views the skill touches.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<Tip>
  See the [Agent Skills guide](/ai/skills) for additional examples.
</Tip>

```yaml title="Topic-level skill" theme={null}
skills:
  top_customers_in_region:
    label: Top Customers
    description: >
      Find the top 20 customers by total lifetime revenue in this region.
      Include customer name, total revenue, order count,
      and date of most recent order. Sort by revenue descending.
```

```yaml title="Skill with required access grants" theme={null}
skills:
  finance_summary:
    label: Finance Summary
    description: >
      Generate a financial summary including revenue, costs, and margins.
    required_access_grants: [ finance ]
```

```yaml title="Skill with conditional access grants" theme={null}
skills:
  regional_analysis:
    label: Regional Analysis
    description: >
      Analyze performance metrics for the user's assigned region.
    required_access_grants: [ northwest_region|southwest_region ]
```


# tags - Topics
Source: https://docs.omni.co/modeling/topics/parameters/tags

Organizes topics by category.

Organizes topics by category, enabling you to group and filter topics by category and make it easier to organize your semantic model. They can be used to organize topics by domain, audience, data sensitivity, or any other categorization scheme that fits your organization's needs.

## Syntax

```yaml theme={null}
tags: [<tag>, ...]
```

## Properties

<ParamField type="string[]">
  A comma-delimited list of strings used to organize and group topics.
</ParamField>

## Examples

```yaml title="Categorizing by audience and domain" theme={null}
topics:
  orders:
    base_view: orders
    tags: [customer_facing, revenue]
```

```yaml title="Multiple categorization dimensions" theme={null}
topics:
  employee_data:
    base_view: employees
    tags: [internal, hr, sensitive]
```

```yaml title="Single tag" theme={null}
topics:
  marketing_campaigns:
    base_view: campaigns
    tags: [marketing]
```


# template - Topics
Source: https://docs.omni.co/modeling/topics/parameters/template

Marks a topic as a template only accessible through `extends` and disables model validation.

Marks a topic as an abstract template. Template topics cannot be used directly — they must be extended by another topic using the [`extends`](/modeling/topics/parameters/extends) property. This enables reusable topic patterns and inheritance.

Template topics have relaxed model validation, meaning missing tables or columns will not cause errors. This allows you to define abstract structures that are completed by the extending topic. Refer to this [community article](https://community.omni.co/t/how-can-i-share-logic-across-multiple-models-hub-and-spoke/150) for more information.

When a non-template topic extends a template topic, it inherits all of the template's attributes and can override or add to them.

## Syntax

```yaml theme={null}
template: true/false
```

## Properties

<ParamField type="boolean">
  Controls whether the topic is treated as an abstract template. When set to `true`, the topic cannot be used directly and must be extended by another topic. Omni will also disable model validation for the topic.
</ParamField>

## Examples

```yaml title="template_topic" theme={null}
base_view: users
template: true

default_filters:
  status:
    is: active
```

```yaml title="extended_topic" theme={null}
base_view: users
extends: [template_topic]

# Inherits default_filters from template_topic
# Can override or add additional attributes
joins:
  orders: {}
```


# views - Topics
Source: https://docs.omni.co/modeling/topics/parameters/views

Allows customization of views only in the context of the topic.

Allows customization of views only in the context of the topic. For example, you can use this parameter to:

* Create aliases for joins between tables in the topic. When aliasing a join for a specific topic, often topic-specific relationships are the best way to model. Field names may also be adjusted, renamed, or relabeled (see above).
* Define topic-specific drilling
* Define topic-specific aggregate awareness

## Syntax

```yaml theme={null}
views:
  <view_name>:
    <property>: <value>
```

## Properties

<ParamField type="object">
  A map of view configurations, where each key is a view name and the value is an object containing topic-specific customizations for that view. Common properties include `display_order`, `extends`, `dimensions`, and `measures`.
</ParamField>

## Examples

```yaml title="Defines the order in which views in the topic display" theme={null}
views:
  order_items:
    display_order: 1
  users:
    display_order: 2
  products:
    display_order: 3
```

The following example customizes the `opp_line_item_daily_facts` view to analyze metrics at different points in a contract's lifecycle (start, now, end).

Custom, context-specific names are applied to the `drr_sum` and `arr_sum` measures to analyze the metric at each point in the life cycle. For example, `Starting ARR` and `Current ARR`.

Then, topic-specific [`joins`](/modeling/topics/parameters/joins) are used to apply different dates - such as a contract start or end date - and create views specific to each point of the contract lifecycle.

```yaml theme={null}
views:
  # First extension; focuses on contract start
  opp_line_item_start_facts:
    extends: [ opp_line_item_daily_facts ]
    dimensions:
      drr_sum:
        label: Starting DRR      # Topic-specific name for the drr_sum base metric
      arr_sum:
        label: Starting ARR      # Topic-specific name for the arr_sum base metric
    measures:                    # Creates a Starting ARR Sum measure
      arr_sum_sum:
        sql: ${opp_line_item_start_facts.arr_sum}
        label: Starting ARR Sum
        aggregate_type: sum

  # Second extension; focuses on current contract state
  opp_line_item_current_facts:
    extends: [ opp_line_item_daily_facts ]
    dimensions:
      drr_sum:
        label: Current DRR
      arr_sum:
        label: Current ARR
    measures:
      arr_sum_sum:
        sql: ${opp_line_item_current_facts.arr_sum}
        label: Current ARR Sum
        aggregate_type: sum

# Third extension; focuses on contract end
  opp_line_item_end_facts:
    extends: [ opp_line_item_daily_facts ]
    dimensions:
      drr_sum:
        label: Ending DRR
      arr_sum:
        label: Ending ARR
    measures:
      arr_sum_sum:
        sql: ${opp_line_item_end_facts.arr_sum}
        label: Ending ARR Sum
        format: USDCURRENCY_0
        aggregate_type: sum

### Topic-specific joins of the same fact table but with different dates
### to understand ARR at different points of the contract lifecycle (start, now, end)
relationships:
  - join_from_view: opp_line_item_facts
    join_to_view: opp_line_item_start_facts
    join_type: always_left
    on_sql: ${salesforce__opportunity.id} = ${opp_line_item_start_facts.opp_id} AND
      ${opp_line_item_start_facts.date} =
      ${opp_line_item_facts.oli_first_date}
    relationship_type: one_to_one
  - join_from_view: opp_line_item_facts
    join_to_view: opp_line_item_end_facts
    join_type: always_left
    on_sql: ${salesforce__opportunity.id} = ${opp_line_item_end_facts.opp_id} AND
      DATEADD(day, 1, ${opp_line_item_end_facts.date}) =
      ${opp_line_item_facts.oli_last_date}
    relationship_type: one_to_one
  - join_from_view: opp_line_item_facts
    join_to_view: opp_line_item_current_facts
    join_type: always_left
    on_sql: ${salesforce__opportunity.id} = ${opp_line_item_current_facts.opp_id}
      AND ${opp_line_item_current_facts.date[date]} = CURRENT_DATE()
    relationship_type: one_to_one
```


# warehouse_override - Topics
Source: https://docs.omni.co/modeling/topics/parameters/warehouse-override

Specifies a different warehouse to use for a specific topic.

<Note>
  Supported only for Snowflake and Databricks connections.
</Note>

Specifies a different warehouse to use for queries using this topic. This is useful for improving the performance of specific topics by providing more compute or isolating them from load on the default database.

If other compute routing mechanisms - such as `compute_routing` or `sql_preamble` - are defined in the model, Omni resolves them in a specific order. See [Resolution precedence](/modeling/models/compute-routing#resolution) for more information.

## Syntax

```yaml theme={null}
warehouse_override: "<warehouse_name>"
```

## Properties

<ParamField type="string">
  The name of an alternate warehouse to use for queries in this topic (e.g., `OMNI_WH`).
</ParamField>

## Examples

```yaml theme={null}
warehouse_override: "OMNI_WH"
```


# week_start_day - Topics
Source: https://docs.omni.co/modeling/topics/parameters/week-start-day

Defines the day that weeks start on for queries scoped to the topic.

Defines the day that weeks start on for queries scoped to the topic. This parameter can be set dynamically using a [user attribute](/administration/users/attributes), just like the model-level setting. See the [**Examples**](#dynamic-value-using-user-attributes) section for an example.

For composite topics, Omni uses the day that all member topics agree on. If the member topics don't agree, Omni falls back to the model-level setting and raises a validation warning.

<Note>
  `week_start_day` can also be set at the [model](/modeling/models/week-start-day) and [dimension levels](/modeling/dimensions/parameters/week-start-day). When set at more than one level, the most specific setting is applied: dimension overrides topic, and topic overrides model.
</Note>

## Syntax

```yaml theme={null}
week_start_day: <day_of_week>
```

## Properties

<ParamField type="string">
  The day of the week that weeks start on for queries scoped to this topic. Valid values are: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`.

  Can be set dynamically using [user attributes](/administration/users/attributes).
</ParamField>

## Examples

### Static value

```yaml theme={null}
week_start_day: Sunday
```

### Dynamic value using user attributes

This example assumes your Omni instance has an existing user attribute called `week_start` and that users have been assigned appropriate day values, such as `Sunday` for US users or `Monday` for European users.

```yaml title="Set week start day based on user's region" theme={null}
week_start_day: {{ omni_attributes.week_start }}
```


# Creating topics with AI quickstart
Source: https://docs.omni.co/modeling/topics/quickstart

Use AI to create your first topic by describing your business questions. Omni generates a complete topic with joins, fields, and context.

The Omni Agent's quickstart is a guided skill that helps you create your first topic. Instead of manually configuring a topic from scratch, you describe the business questions you want to answer and the Omni Agent builds a complete topic for you.

<Tip>
  For manual topic creation, see [Creating topics](/modeling/topics/setup).
</Tip>

## Requirements

To use the Omni Agent's quickstart skill you must have:

* **Querier**, **Modeler**, or **Connection Admin** permissions
* [AI features](/ai/settings/features) enabled for your organization
* A database connection with a schema available

## Creating a topic with quickstart

<Steps>
  <Step title="Start the quickstart skill">
    You can access the AI quickstart skill from several places in Omni:

    * **New connection setup** — The skill is offered after connecting a new database
    * **Home page** — A prompt to build your first topic appears on the home page
    * **Chat page** — The quickstart option appears when you open the AI chat
    * **New workbook tab** — Click the **Build a topic** button in the bottom right of a new workbook tab

    For models with no existing topics, the quickstart dialog also appears automatically when you open a workbook.

    Skipping the dialog will dismiss the prompt from appearing in these locations, but you can always access the quickstart skill by clicking **Build a topic** from a new workbook tab.
  </Step>

  <Step title="Describe your business questions">
    The Omni Agent will ask: *What business questions do you want to answer?*

    Focus on popular or common business questions in the same related area (for example, sales pipeline or customer retention) that a specific grouping of tables can answer. We recommend starting with 5-10 questions. For example:

    * "What is our monthly revenue trend?"
    * "Which products have the highest return rate?"
    * "How does customer retention vary by acquisition channel?"

    The more specific your questions, the better the Omni Agent can tailor the topic to your needs.
  </Step>

  <Step title="Provide context">
    <Tip>
      This step is not required, but sharing context helps the Omni Agent generate a more accurate and relevant topic. Think of this as how you would get a new employee up to speed who had never seen this data before — the more context you provide, the faster the Omni Agent can orient itself and produce useful results.
    </Tip>

    The Omni Agent will ask for any supporting context that helps it understand your data. You can provide text or upload files:

    * Table or schema names to use as a starting point
    * Existing dashboards or SQL queries (as text or uploaded files)
    * Data dictionaries or metric definitions
    * Transcripts or recordings of stakeholder interviews
    * dbt models or other documentation
    * PDFs of dashboards, reports, or onboarding materials

    If you don't have documentation to upload, that's okay — even listing the key tables or schemas you want the topic to focus on is a helpful starting point.

    For file upload guidelines, see [Uploading files](/ai/chat#uploading-files).
  </Step>

  <Step title="Review the generated topic">
    The Omni Agent creates a single topic based on your input, including:

    * **Base view** - the primary table for the topic
    * **Joins** - relationships to related tables needed to answer your questions
    * **Fields** - relevant dimensions and measures
    * **AI context** - a description that helps the Omni Agent understand the topic for future queries
    * **Descriptions** - human-readable labels and descriptions for the topic and its fields

    Review the proposed modeling changes and click **Accept** to apply them. Accepting moves the topic into your workbook, but it is not yet in the shared model — you'll need to [promote it to shared](/modeling/develop/promotion) or go through your organization's [git promotion flow](/integrations/git) to make it available to others.

    To make more detailed adjustments, click **Open in IDE** to edit the topic with the [Modeling Agent](/ai/model-assistant). When you navigate back to the workbook, click **Refresh** to pull your IDE changes through.
  </Step>

  <Step title="Choose how to explore">
    After accepting the topic, the Omni Agent will ask how you'd like to proceed:

    * **Work through questions together** — the Omni Agent generates a query for each business question you provided in the first step, walking through them one at a time
    * **Explore on your own** — start using the new topic immediately in your workbook
  </Step>
</Steps>

## Next steps

The generated topic is a starting point. As you and your team use it, you'll likely want to refine and expand it:

* **Build sample queries** — As you work through your business questions, save the queries as [sample queries](/modeling/topics/parameters/sample-queries). This reinforces the Omni Agent's understanding of the topic and improves future query accuracy. Building sample queries as you explore helps build more AI context and enhance the topic over time.
* **Create additional topics** — Use the quickstart skill again from a new workbook tab to build out more topics for different areas of your business. Each topic gives you a starting point to review and refine.
* [Edit the topic](/modeling/topics/setup) to add or remove fields, adjust joins, or update metadata
* Review [topic best practices](/modeling/topics/best-practices) for recommendations on topic design
* Use the [Workbook Agent](/ai/queries) to explore your new topic with natural language questions


# Creating topics
Source: https://docs.omni.co/modeling/topics/setup

Omni offers two ways to develop topics: visually (in workbooks) or using code (in the model IDE).

In this guide, each step of the topic development process will show you how to complete the step using either the workbook or the model IDE.

<Tip>
  Looking for a faster way to get started? Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to generate a topic from your business questions.
</Tip>

## Requirements

To follow the steps in this guide, you'll need:

* **Querier, Modeler,** or **Connection Admin** permissions to create the topic. **Note**: Queriers can only create topics in workbooks.
* **Connection Admin** or **Modeler** permissions to promote the topic to the shared model
* **Optional: Familiarity with [Omni branches](/content/develop/branch-mode)**. While not required, this is recommended if your organization uses branch-based workflows for Omni development.

<Tip>
  Use the [topic design best practices](/modeling/topics/best-practices) to create efficient, approachable topics.
</Tip>

## Before you begin

You can use the workbook-based topic editor, the model IDE, or both to develop your topics. However, keep the following in mind before you begin:

* **Queriers** can only create topics in workbooks, as they don't have access to the IDE
* **Changes made outside a branch in the IDE directly edit the shared model**. This means that changes are automatically promoted when a file is saved in the IDE. You can revert changes in the IDE using the [model history panel](/modeling/develop/history).

<Steps>
  <Step title="Create the topic">
    First, you'll start by creating the topic in the workbook or the model IDE.

    <AccordionGroup>
      <Accordion title="In the workbook" icon="book">
        <Tip>
          If you know the model you'll be working with is connected to git, we recommend [creating a branch](/content/develop/branch-mode) before continuing. This can save you a few steps when you're ready to promote the topic to the shared model.

          If you're unsure, that's okay! We'll show you what to do to promote the topic, if needed.
        </Tip>

        1. Open or create a workbook.
        2. In a query tab, navigate to **All views & fields** in the field browser.
        3. Hover over a view and click the <Icon icon="ellipsis-vertical" type="solid" /> (three dots icon), then **Modeling > Make topic**.

        This will open the topic editor:

        <img alt="The Overview tab of the topic editor in a workbook" />

        In this editor, you can:

        * Save the changes and use **Use in query** to use the topic in a new query, or
        * Further curate your topic by following the remaining **optional** steps in this guide
      </Accordion>

      <Accordion title="In the IDE" icon="code">
        <Tip>
          If your model is connected to git, you'll need to [create a branch](/content/develop/branch-mode) before making changes in the IDE.
        </Tip>

        1. In the **Files** panel of the modeling IDE, click the <Icon icon="plus" type="solid" /> (plus sign) button in the **Topics** section.

           <img alt="The plus sign button used to create a new topic in the Topics section of the model IDE Files panel" />

        2. You'll be prompted to enter a name for the topic. Currently, Omni will use this name to automatically set the topic's base view. If the name doesn't match an existing view, the IDE will display an error.

        To resolve this, enter the desired name for the topic and use the [`base_view`](/modeling/topics/parameters/base-view) parameter to define the base view:

        ```yaml title="Topic base view" theme={null}
        base_view: ecomm__order_items
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Design the topic">
    <Note>
      The steps in this section are **optional**. You can add metadata, fields, joins, etc. to topics at any time.

      **Want to work with an existing topic in the topic editor?** Open the topic in a workbook and click **Model > Edit topic**, or right-click the topic switcher in the field browser and select **Edit topic**.
    </Note>

    In this section, we'll cover how you can further curate your topic by adding metadata like descriptions and labels, AI context, joins, and fields.

    <Steps>
      <Step title="Add metadata and AI context">
        You'll start designing the topic by adding optional metadata and AI context.

        <AccordionGroup>
          <Accordion title="In the workbook" icon="book">
            The **Overview** tab contains a preview of the topic and allows you to do some quick curation like renaming the topic (label), adding it to a topic group (a folder of related topics) adding a description, or providing AI context.

            Making changes here will, by default, be added to the workbook model. To propagate these changes to the shared model, ensure you promote them.

            <Tip>
              While AI context is optional, Omni recommends using it if you plan to use any AI features. Refer to the [Optimizing models for AI guide](/modeling/develop/ai-optimization) for more information.
            </Tip>

            <img alt="The Overview tab of the topic editor, showing label, group, description, and AI context fields" />
          </Accordion>

          <Accordion title="In the IDE" icon="code">
            After you create the topic file, you can start designing the topic with [topic parameters](/modeling/topics/parameters).

            Define the following parameters, which will also display in the **Overview** tab of the workbook-based topic editor:

            * [`label`](/modeling/topics/parameters/label) - A user-friendly display name
            * [`group_label`](/modeling/topics/parameters/group-label) - The group that the topic belongs to, which is useful for improving workbook navigation for your end users
            * [`ai_context`](/modeling/topics/parameters/ai-context) - Additional information for the AI, which can help improve results

            ```yaml title="Topic description, label, group, and AI context" theme={null}
            base_view: ecomm__order_items
            label: Order Transactions
            group_label: Orders & Fulfillment
            ai_context: |
              You are an expert data analyst, who has a vast amount of experience analyzing ecommerce data to find useful insights and trends.
              Our data has information about 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.
            ```
          </Accordion>
        </AccordionGroup>
      </Step>

      <Step title="Add joins">
        By default, Omni adds all joinable non-fanout tables to newly-created topics — specifically those with `many-to-one` or `one-to-one` relationships to other tables. The list of joinable tables can also be curated, either to remove joins generated by default or to add in tables that would fan out the base table, such as `many-to-many` or `one-to-many` joins.

        Joins added to the model's [relationships file](/modeling/relationships) can also be added to topics.

        <AccordionGroup>
          <Accordion title="In the workbook" icon="book">
            The **Joins** tab will display the joins that are available for the dataset:

            <img alt="The Joins tab of the topic editor, showing joins available for the dataset" />

            The view browser allows you to search for and select views to include in the topic.

            To add a brand new join - that is, one that is not already defined in your model's [relationships file](/modeling/relationships) - click the **+ New** button. You'll then be prompted to define and save the join.
          </Accordion>

          <Accordion title="In the IDE" icon="code">
            <Tip>
              **Don't lose your work!** Click the **Save changes** button located near the top-right corner of the IDE before navigating to a different file.
            </Tip>

            To add joins to a topic in the model IDE, use the [`joins`](/modeling/topics/parameters/joins) parameter in the topic file:

            ```yaml title="Topic-level join" highlight={2,5} theme={null}
            joins:
              ecomm__users: {}
              ecomm__inventory_items:
                ecomm__products:
                  ecomm__distribution_centers: {}
            ```

            **Note**: The last table in each 'node' - specifically, tables that don't have children nested under them - must have an empty bracket pair: `{}`.

            The joins you define will also display in the **Joins** tab of the workbook-based topic editor:

            <img alt="The Joins tab of the topic editor displaying the joins defined in the topic YAML" />
          </Accordion>
        </AccordionGroup>

        <Tip>
          After adding joins to your topic, you can visualize the join structure in the topic editor's **Diagram** tab. Refer to [Review and save](#review-save) for more information.
        </Tip>
      </Step>

      <Step title="Add fields">
        By default, all fields from the topic's base view and any [joined views](#add-joins) will be accessible in the topic. In this step, we'll show you how to curate the fields in the topic.

        <AccordionGroup>
          <Accordion title="In the workbook" icon="book">
            The **Fields** tab displays all the fields that are visible in the topic.

            **To exclude a field**, deselect the checkbox next to the field:

            <img alt="The Fields tab of the topic editor with checkboxes used to include or exclude fields" />
          </Accordion>

          <Accordion title="In the IDE" icon="code">
            <Tip>
              **Don't lose your work!** Click the **Save changes** button located near the top-right corner of the IDE before navigating to a different file.
            </Tip>

            You can include and exclude fields in the model IDE by using the [`fields`](/modeling/topics/parameters/fields) parameter in the topic file.

            For example, the following definition would make all fields accessible **except** the `email`, `first_name`, and `last_name` fields in the `ecomm__users` view:

            ```yaml title="Topic field curation" theme={null}
            fields: [
              all_views.*,
              -ecomm__users.email,
              -ecomm__users.first_name,
              -ecomm__users.last_name
            ]
            ```

            If you viewed this topic's **Fields** tab in the workbook topic editor, the excluded fields would be **unchecked**:

            <img alt="The Fields tab of the topic editor showing excluded fields as unchecked" />
          </Accordion>
        </AccordionGroup>
      </Step>

      <Step title="Curate views and fields">
        Adding context to a topic can be helpful for both your end users and Omni's AI. In this step, we'll show you how to further curate your topic by adding information to included views and fields.

        <AccordionGroup>
          <Accordion title="In the workbook" icon="book">
            The **Curate** tab allows you to bulk-add information - such as labels, descriptions, and AI context - to views and fields in the topic.

            While working in a workbook query, you can also access these options for individual fields by right-clicking on a field and selecting **Edit**.

            <img alt="The Curate tab of the topic editor, used to bulk-add labels, descriptions, and AI context to views and fields" />
          </Accordion>

          <Accordion title="In the IDE" icon="code">
            <Tip>
              **Don't lose your work!** Click the **Save changes** button located near the top-right corner of the IDE before navigating to a different file.
            </Tip>

            Unlike the workbook-based topic editor, there isn't a way to bulk-add information to views and fields in the model IDE. Adding curation must currently be accomplished by opening and editing the view file for views included in the topic.

            To get started, locate and click the view in the **Schema** browser. You can then add information to the view and its fields.

            In the following example, we added:

            * A view-level `description`
            * A [`description`](/modeling/dimensions/parameters/description) and [`ai_context`](/modeling/dimensions/parameters/ai-context) to each of the view's [`dimensions`](/modeling/dimensions)

            ```yaml wrap title="Curating the distribution_centers view" theme={null}
            # Reference this view as ecomm__distribution_centers
            description: |
              This is a dimension table containing information about distribution centers,
              including a unique identifier, their name, which is actually their location in
              the form of city name, and where they are located with regards to latitude and longitude
            schema: ECOMM
            table_name: DISTRIBUTION_CENTERS
            dimensions:
              id:
                sql: '"ID"'
                format: ID
                description: Unique identifier for each distribution center
                primary_key: true
                ai_context: |
                  Often users will not pull this into a query directly and we should not include it
                  unless specifically requested.
              name:
                sql: '"NAME"'
                description: Name of the distribution center
                ai_context: This is the name of the city where the distribution center is located.
              latitude:
                sql: '"LATITUDE"'
                description: Geographical latitude of the distribution center location
                ai_context: will often be used in tandem with longitude for mapping purposes
              longitude:
                sql: '"LONGITUDE"'
                description: Geographical longitude of the distribution center location
                ai_context: will often be used in tandem with longitude for mapping purposes
            measures:
              count:
                aggregate_type: count
            ```

            If you opened this view in the topic's **Curate** tab in the workbook topic editor, it would look like the following image:

            <img alt="The Curate tab of the topic editor displaying the distribution_centers view with its descriptions and AI context" />

            Refer to the [Database view](/modeling/views), [Dimension](/modeling/dimensions), and [Measure references](/modeling/measures) for more information about all supported parameters.
          </Accordion>
        </AccordionGroup>
      </Step>
    </Steps>
  </Step>

  <Step title="Review and save">
    Next, you'll review and save the changes you made to the topic.

    <AccordionGroup>
      <Accordion title="In the workbook" icon="book">
        There are two ways to review topics in the workbook:

        * The **Diagram** tab, which contains a visual representation of the topic's structure, and
        * The **YAML** tab, which contains the topic's underlying YAML code

        You can use one or both of these tabs to review your work.

        <Steps>
          <Step title="Visually review the topic with the Diagram tab">
            The **Diagram** tab displays a visual representation of the topic's structure — including its views, joins, dimensions, and measures — making it easier to confirm the topic looks the way you expect before saving.

            <img alt="The Diagram tab of the topic editor, showing a visual representation of the topic's views, joins, dimensions, and measures" />

            <Warning>
              To maintain performance and readability, the **Diagram** tab won't render for topics with more than **20 tables** or more than **50 join relationships**. If your topic exceeds either limit, consider breaking it into smaller, more focused topics.
            </Warning>
          </Step>

          <Step title="Review and save the YAML">
            The **YAML** tab automatically generates the YAML definition for the topic based on what you built in the other topic editor tabs. When finished, click **Save changes**.

            In this tab, you can also:

            * After saving, click **Use in query** to create a new workbook query based on the topic
            * Click **Edit in IDE** to directly edit the topic's YAML configuration

              <img alt="The YAML tab of the topic editor showing the auto-generated YAML definition for the topic" />

            <Note>
              **Some parameters can only be added using the model IDE**. Refer to the [Topic parameter reference](/modeling/topics/parameters) for a list of all available topic parameters.
            </Note>
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="In the IDE" icon="code">
        <Note>
          If not using a branch, changes will be automatically promoted to the shared model after every save. Use the [model history panel](/modeling/develop/history) to revert changes, if needed.
        </Note>

        At this point, the example Orders Transactions (`ecomm__order_items`) topic file looks like this:

        ```yaml title="Example Order Transactions topic" wrap theme={null}
        base_view: ecomm__order_items
        label: Order Transactions
        group_label: Orders & Fulfillment
        ai_context: |
          You are an expert data analyst, who has a vast amount of experience analyzing ecommerce data to find useful insights and trends.
          Our data has information about 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.
        joins:
          ecomm__users: {}
          ecomm__inventory_items:
            ecomm__products:
              ecomm__distribution_centers: {}
        fields: [
          all_views.*,
          -ecomm__users.email,
          -ecomm__users.first_name,
          -ecomm__users.last_name
        ]
        ```

        When you're finished making changes to the topic, click the **Save changes** button located near the top-right corner of the IDE.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Promote to shared">
    <Note>
      This step requires **Connection Admin** or **Modeler** permissions.
    </Note>

    The last step is to promote the topic to the shared model. This makes the topic accessible in [new and existing workbooks](/analyze-explore/queries/topics) that are built off the underlying model.

    How you promote the topic depends on whether you used a branch:

    <AccordionGroup>
      <Accordion title="I didn't use a branch" icon="square-xmark">
        If you didn't use a branch and you created the topic:

        * **In a workbook** - While in a **published** workbook, navigate to [**Model > View & promote**](/modeling/develop/promotion).

          * **If you see a `Use branch to promote` message**:

            * **And you're in a draft**, click **File > Move to branch**. This will move the changes to a branch.
            * **Otherwise**, click **Model > Branch > Create branch** to create a new branch in the workbook with the changes.

          * **Otherwise**, click **Promote to shared**.

        * **In the IDE** - Your changes were promoted to the shared model when you clicked **Save changes**. You're all done!
      </Accordion>

      <Accordion title="I used a branch" icon="code-branch">
        [Promotion from a branch to shared](/content/develop/branch-mode) depends on whether the model is connected to git and pull requests are required:

        * **If git isn't enabled or pull requests aren't required**, click the **Merge** button in the green branch header at the top of the page. Follow the prompts to merge the branch.
        * **Otherwise,** click the **Create pull request** button in the green branch header at the top of the page. This will open the connected git repository, where you'll be prompted to create the pull request. The changes in the branch will be applied to the shared model once the pull request is merged.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Next steps

* Design efficient, approachable topics using our [topic best practices](/modeling/topics/best-practices)
* Explore all available configuration options in the [Topic parameter reference](/modeling/topics/parameters)
* Use your topic to [build queries in a workbook](/analyze-explore/queries/topics)


# Aliasing views
Source: https://docs.omni.co/modeling/views/alias

Alias views to handle database table renames or to create duplicate views for joins.

Aliasing lets you reference a view by an additional name. This is useful for handling database table renames and for creating duplicate views needed in join logic.

<Tip>
  Aliased views are best paired with [topics](/modeling/topics) and may not appear as views in **All Views and Fields** in the workbook. Additionally, aliased views can't be extended.
</Tip>

## Handling table name changes

If the name of view's base table changes in the database, it can cause content in Omni to break. Use the [`aliases`](/modeling/views/parameters/aliases) parameter to add the table's original name(s), which will allow Omni to find the correct table in the database.

## Duplicating views with aliases

In some cases, you may need to duplicate a view - for example, a `users` view that contains both **buyers** and **sellers**. Aliased views are automatically created when you define them as joins in the model's [Relationships file](/modeling/relationships).

The following example demonstrates how to alias the `users` view to create `buyers` and `sellers` views. Note that the names of the aliased views are used to declare the joins:

```yaml title="relationships.yaml" highlight={2,5,9,12} theme={null}
- join_to_view: users
  join_to_view_as: buyers
  join_type: always_left
  relationship_type: many_to_one
  on_sql: ${order_items.user_id} = ${buyers.id}
  reversible: false

- join_to_view: users
  join_to_view_as: sellers
  join_type: always_left
  relationship_type: many_to_one
  on_sql: ${order_items.user_id} = ${sellers.id}
  reversible: false
```

## Alias scope

An alias created by [`join_to_view_as`](/modeling/relationships/parameters/join-to-view-as) or [`join_from_view_as`](/modeling/relationships/parameters/join-from-view-as) only exists within:

* The `on_sql` of the relationship that creates it
* The [`joins`](/modeling/topics/parameters/joins) parameter of a topic, to bring the alias into that topic
* Custom field or dimension SQL defined in the topic's [`views`](/modeling/topics/parameters/views) parameter, since that SQL is evaluated in the context of the topic where the alias is already joined in

It isn't a full view, so it can't be referenced from a view file's own field or dimension SQL, or used as a join target in a different relationship — Omni can't resolve it as a table outside the contexts above.

### Giving an alias its own fields, label, or display order

To customize an alias further — set its `display_order` or `label` in a topic, or add fields to it that other topic-level SQL can reference — extend the original view under the alias's name instead of using `join_to_view_as`/`join_from_view_as`:

```yaml title="Topic file" highlight={2-3,11} theme={null}
views:
  buyers:
    extends: [ users ]
    dimensions:
      buyer_tier:
        sql: ${TABLE}.tier
    display_order: 2

relationships:
  - join_from_view: order_items
    join_to_view: buyers
    join_type: always_left
    on_sql: ${order_items.user_id} = ${buyers.id}
    relationship_type: many_to_one
```

The relationship now joins directly to `buyers` with [`join_to_view`](/modeling/relationships/parameters/join-to-view) rather than aliasing `users` with `join_to_view_as`. Once `buyers` is declared this way it's a real view: it can hold its own fields, take a `display_order` and `label` in the topic's `views` parameter, and be used as a join target in other relationships — none of which a `join_to_view_as`/`join_from_view_as` alias supports.

<Warning>
  Don't declare both a `join_to_view_as`/`join_from_view_as` alias and a `views` entry with the same name in the same topic. Omni will see two definitions claiming the same name and raise a `Relationship alias duplicates view name` error. Pick one: alias for `on_sql` disambiguation only, or an extended view for everything else.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Relationship alias duplicates view name / Table not found">
    This happens when a `join_to_view_as` or `join_from_view_as` alias is declared in a topic's `views` parameter without an `extends` parameter — Omni can't resolve the alias as a table on its own.

    Add `extends: [ <original_view> ]` to the `views` entry, and change the relationship to join directly to the alias's name with `join_to_view` (or `join_from_view`) instead of aliasing the original view. See [Giving an alias its own fields, label, or display order](#giving-an-alias-its-own-fields-label-or-display-order) above.
  </Accordion>

  <Accordion title="View is not joined into topic">
    This happens when a view file's own field or dimension SQL references a `join_to_view_as`/`join_from_view_as` alias (for example, `${my_alias.field}`). View files are evaluated independently of any topic, so they have no way to know the alias will exist at query time.

    Move the field definition into the topic's `views` parameter instead, under the alias's name — SQL defined there can see aliases already joined into that topic.
  </Accordion>
</AccordionGroup>


# Editing database views
Source: https://docs.omni.co/modeling/views/edit

Update metadata and edit fields for database views from either the workbook or the modeling IDE.

<Note>
  **Looking for query views?** See [Editing query views](/modeling/query-views/edit).
</Note>

You can update a database view's metadata and edit its fields from either a workbook or the modeling IDE. For an overview of how views fit into the model, see [Working with views](/modeling/views).

## Requirements

To edit views, you'll need:

* **Querier, Modeler,** or **Connection Admin** permissions
* **Connection Admin** or **Modeler** permissions to promote the changes to the shared model

## Editing metadata

You can update a view's label, description, tags, visibility, and AI context from the workbook or the model IDE. Note that some view metadata — such as [`aliases`](/modeling/views/parameters/aliases) — may only be editable from the IDE.

<AccordionGroup>
  <Accordion title="In the workbook" icon="book">
    1. In a workbook query, hover over a view in the field browser.
    2. Click the **<Icon icon="ellipsis-vertical" /> icon** next to the view name.
    3. Select **Edit** from the context menu.

    The **Edit view** drawer opens with the following editable properties:

    * **View label** — The display name for the view
    * **Description** — A description of the view's purpose or contents
    * **Tags** — Tags to organize and categorize the view
    * **Hidden** — Toggle to hide or show the view in the field browser
    * **AI context** — Additional context to help Omni AI understand and work with the view

    Make your changes and click **Update** to save. The **Update** button is disabled until you change a field.
  </Accordion>

  <Accordion title="In the IDE" icon="code">
    1. Navigate to the model IDE.
    2. In the **Schemas** section, locate the view you want to work with.
    3. Click the file to open it and then edit the corresponding parameters:

    * [`label`](/modeling/views/parameters/label)
    * [`description`](/modeling/views/parameters/description)
    * [`ai_context`](/modeling/views/parameters/ai-context)
    * [`tags`](/modeling/views/parameters/tags)
    * [`hidden`](/modeling/views/parameters/hidden)

    You can also add or edit any of the other supported [view parameters](/modeling/views/parameters).

    4. Click **Save changes** in the IDE to apply your changes.
  </Accordion>
</AccordionGroup>

## Editing fields

You can edit field properties — label, description, AI context, visibility, and more — from either the workbook or the model IDE.

<AccordionGroup>
  <Accordion title="In the workbook" icon="book">
    Open the [Edit view drawer](#editing-metadata). The drawer lists every field in the view, including hidden ones:

    * **Visible fields** — Click a field row to open the **Edit field** panel, or click the <Icon icon="ellipsis-vertical" /> icon for additional options.
    * **Hidden fields** — Appear greyed out. Click the <Icon icon="eye" /> icon next to a hidden field to unhide it, then click it to edit its properties:

      <img alt="Hidden field with eye icon in Fields section of view editor" />
  </Accordion>

  <Accordion title="In the IDE" icon="code">
    Open the view file and locate the field under `dimensions` or `measures`. From there, you can update any of the field's parameters.

    For example, hide a field from the workbook field browser by setting `hidden: true`:

    ```yaml theme={null}
    dimensions:
      internal_notes:
        sql: '"INTERNAL_NOTES"'
        hidden: true
    ```

    Click **Save changes** when you're done. See the [Dimension](/modeling/dimensions) and [Measure](/modeling/measures) references for all available parameters.
  </Accordion>
</AccordionGroup>

## Promoting changes

If you want your changes to be accessible in new and existing workbooks built on the underlying model, you'll need to promote them. See [Promoting changes to the shared model](/modeling/develop/promotion) for more information.

## Limitations

[Join-aliased views](/modeling/views/alias#duplicating-views-with-aliases) and topic-scoped views can only be edited in the model IDE.

## Next steps

* [View parameter reference](/modeling/views/parameters)
* [Aliasing views](/modeling/views/alias)
* [Editing query views](/modeling/query-views/edit)
* [Promoting changes to the shared model](/modeling/develop/promotion)


# Working with views
Source: https://docs.omni.co/modeling/views/index

Views are the building blocks of queries in Omni. Get an overview of how views work, how to create and edit them, and how to keep them in sync with your database.

Views are the building blocks of queries in Omni — every dimension and measure in the workbook's field browser belongs to a view. Each view represents a database table and defines the fields, labels, and metadata available for querying.

## View basics

<AccordionGroup>
  <Accordion title="How do views work?">
    Views are auto-generated from tables in your database and represent the data available for querying in Omni.

    In a view file, you define the fields available for querying along with metadata like labels, descriptions, [access grants](/modeling/views/parameters/required-access-grants), [UI visibility](/modeling/views/parameters/hidden), and [AI context](/modeling/views/parameters/ai-context).
  </Accordion>

  <Accordion title="How are views and topics different?">
    A view is a single object **in** your data model, whereas [topics](/modeling/topics) sit **on top** of the data model and reshape it into business-friendly groupings for easier exploration. Topics can include multiple views, which can be curated ahead of time for self-service.

    Think of views as the objects that make up topics, and topics as the presentation layer you tailor for quick insights. Topics effectively translate your database model into reusable logic for building dashboards and workbooks.
  </Accordion>

  <Accordion title="How do I keep Omni views in sync with my database?">
    When tables, columns, or schemas change in your warehouse, run a schema refresh to update the corresponding view files in Omni. See [Schema refreshes](/modeling/develop/schema-refreshes) for more information.
  </Accordion>

  <Accordion title="Can I save a query as a view?">
    Yes. A **query view** is a workbook query saved as a view. Query views can be built from a [point-and-click query](/analyze-explore/point-click-queries) or a [SQL query](/analyze-explore/sql) — the latter are sometimes called **SQL-backed query views**.

    Once saved, query views are queryable like any other view, but they're stored as `.query.view` files with their own parameter set. See [Query views](/modeling/query-views) and [Save queries as views](/analyze-explore/saved-views) for more information.
  </Accordion>

  <Accordion title="Can I alias a view?">
    Yes. Aliasing lets you reference a view by an additional name — useful for handling database table renames or for creating duplicate views needed in join logic. See [Aliasing views](/modeling/views/alias) for details.
  </Accordion>
</AccordionGroup>

## Creating views

Database views are auto-generated when a model is created — you don't need to create them manually.

If you do want to create a view file from scratch — for example, as a [template](/modeling/views/parameters/template) — click **File > New view** in the model IDE. Omni will prompt you to enter a name and then create a new view file.

Refer to the [View parameter reference](/modeling/views/parameters) to learn more about configuring views.

## Editing views

Views can be edited in a workbook or in the model IDE. See [Editing views](/modeling/views/edit) for more information.

## Next steps

* [Editing views](/modeling/views/edit)
* [Aliasing views](/modeling/views/alias)
* [Save queries as views](/analyze-explore/saved-views)
* [View parameter reference](/modeling/views/parameters)


# ai_context - Views
Source: https://docs.omni.co/modeling/views/parameters/ai-context

Free text that can provide context about a view to the Omni Agent.

Free text that can provide context to the [Omni Agent](/ai/chat). Context could include behavioral prompting or example queries and structured Omni results.

Refer to the [Optimizing models for AI](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml theme={null}
ai_context: "<context_text>"
```

Or for multiline context:

```yaml theme={null}
ai_context: |
  <multiline_context_text>
```

## Properties

<ParamField type="string">
  Free text that provides context to the Omni Agent. Can include behavioral prompting, instructions for tone, or other guidance to .

  The following references are supported for this field:

  * [**User attributes**](/administration/users/attributes), referenced with `{{omni_attributes.<attribute_name>}}`. This allows you to personalize the context for each user.
  * **Model [`constants`](/modeling/models/constants)**, referenced using `@{constant_name}` syntax. This allows you to maintain reusable instruction blocks such as tone, privacy guidance, and domain context instead of duplicating them.
  * **`omni_llm` namespace,** which allows you to tailor context to specific AI model tiers:

    * `{{ omni_llm.model }}` — Substitutes the active model's family name, which will be one of: `smartest`, `standard`, or `fastest`
    * `{{# omni_llm.<family> }}...{{/ omni_llm.<family> }}` — Conditional sections for specific model tiers. `<family>` must be one of `smartest`, `standard`, or `fastest`
    * `{{^ omni_llm.<family> }}...{{/ omni_llm.<family> }}` — Inverse sections, which apply when the specified tier is **not** used. `<family>` must be one of `smartest`, `standard`, or `fastest`

    See the [Examples section](#model-specific) for more information.
  * **`omni_agent` namespace,** which allows you to scope context to specific AI agents:

    * `{{ omni_agent.name }}` — Substitutes the active agent's name, which will be one of: `analyze`, `build`, or `simple_summarize`
    * `{{# omni_agent.<agent> }}...{{/ omni_agent.<agent> }}` — Conditional sections for specific agents. `<agent>` must be one of `analyze`, `build`, or `simple_summarize`
    * `{{^ omni_agent.<agent> }}...{{/ omni_agent.<agent> }}` — Inverse sections, which apply when the specified agent is **not** used. `<agent>` must be one of `analyze`, `build`, or `simple_summarize`

    See the [Examples section](#agent-specific) for more information.
</ParamField>

## Examples

### Personalized context using user attributes

```yaml title="Personalized context using user attributes" theme={null}
ai_context: |
  This view contains data for the {{omni_attributes.region}} region only.
```

### Model-specific query preferences

The following context will apply when the model tier is `smartest`.

```yaml title="Applies when the model tier is smartest" wrap theme={null}
ai_context: |
  {{# omni_llm.fastest }}
  Prefer queries using pre-aggregated fields when available.

  You are running on {{ omni_llm.model }}.
  {{/ omni_llm.fastest }}
```

The following context will apply when the model tier is **not** `smartest`.

```yaml title="Applies when the model tier is not smartest" wrap theme={null}
  {{^ omni_llm.fastest }}
  You may compute aggregations on-the-fly if needed for accuracy.

  You are running on {{ omni_llm.model }}.
  {{/ omni_llm.fastest }}
```

### Agent-specific context

The following context provides different guidance to different agents based on view-level concerns.

```yaml title="Agent-specific view guidance" wrap theme={null}
ai_context: |
  This view contains pre-aggregated sales metrics.

  {{# omni_agent.analyze }}
  When querying this view, you can use the pre-calculated total_revenue field directly rather than summing line items.
  {{/ omni_agent.analyze }}

  {{# omni_agent.simple_summarize }}
  This view is optimized for dashboard summaries. All measures are pre-aggregated.
  {{/ omni_agent.simple_summarize }}

  {{# omni_agent.build }}
  This view aggregates data at the daily level. The grain is date + product_id.
  {{/ omni_agent.build }}
```

### Using constant references

Reference [`constants`](/modeling/models/constants) to combine reusable context blocks with view-specific guidance:

```yaml title="View file with constant references" theme={null}
ai_context: |
  @{tone} @{privacy_high}
  This view contains customer transaction data.
```

The `constant` references will be substituted with the values defined in the model file.

### Behavioral prompting

```yaml title="Behavioral prompting" wrap theme={null}
ai_context: |
  you are the head of finance. you are concerned with the status of customer payments. you often need to project into the future how many invoices are due and for how much. you also need to know if any invoices are late so you can reach out to those customers.
```

### Structured query

```yaml title="Structured query" expandable theme={null}
ai_context: |
  question: which customers are behind due on payment?
    answer:
    {
    "limit": 1000,
    "sorts": [
      {
        "column_name": "share_rillet_omni_omni__invoices.due_date",
        "sort_descending": true,
        "is_column_sort": false,
        "null_sort": "OMNI_DEFAULT"
      }
    ],
    "table": "share_rillet_omni_omni__invoices",
    "fields": [
      "share_rillet_omni_omni__invoices.customer_id",
      "share_rillet_omni_omni__invoices.customer_name",
      "share_rillet_omni_omni__invoices.invoice_number",
      "share_rillet_omni_omni__invoices.due_date",
      "share_rillet_omni_omni__invoices.total_amount"
    ],
    "pivots": [],
    "dbtMode": false,
    "filters": {
      "share_rillet_omni_omni__invoices.due_date": {
        "is_negative": false,
        "kind": "BEFORE",
        "right_side": "today",
        "type": "date",
        "ui_type": "BEFORE"
      },
      "share_rillet_omni_omni__invoices.status": {
        "type": "string",
        "kind": "EQUALS",
        "values": [
          "unpaid"
        ],
        "is_negative": false,
        "case_insensitive": true
      }
    },
    "modelId": "aeb6f3f4-b0e5-4abb-97eb-eaeb42a16944",
    "version": 5,
    "rewriteSql": true,
    "row_totals": {},
    "fill_fields": [],
    "calculations": [],
    "column_limit": 50,
    "join_via_map": {},
    "column_totals": {},
    "userEditedSQL": "",
    "dimensionIndex": 0,
    "default_group_by": true,
    "join_paths_from_topic_name": "invoices"
  }
```


# aliases - Views
Source: https://docs.omni.co/modeling/views/parameters/aliases

Maps old table names to updated table names to preserve content.

Maps old table names to updated table names to preserve content. This allows you to ensure Omni content that uses the table doesn't break when the table is renamed.

## Syntax

```yaml theme={null}
aliases: [ OLD_TABLE_NAME ]
```

## Properties

<ParamField type="array">
  An array of old table names that should map to this view.
</ParamField>

## Examples

In this example, the `OLD_ORDER_ITEMS_NAME` table was renamed to `ORDER_ITEMS` in the database. Adding the original table name to the `aliases` parameter in the `ORDER_ITEMS.view` file in Omni prevents broken content and model validation errors.

```yaml title="ORDER_ITEMS.view file" theme={null}
schema: PUBLIC
table_name: ORDER_ITEMS
primary_key_sql: [ "${order_items.id}" ]
aliases: [OLD_ORDER_ITEMS_NAME]
```


# catalog - Views
Source: https://docs.omni.co/modeling/views/parameters/catalog

Specifies the database catalog (or database name) for a table.

<Note>
  This parameter is primarily used when working with connections that have multiple databases configured. For most use cases, you won't need to set this manually.
</Note>

Specifies which database a table belongs to when a connection includes multiple databases. This is particularly useful for:

* **Multi-database PostgreSQL connections** where tables from different databases need to be modeled in a single connection
* **Other database types** that support catalog-level organization (BigQuery, Snowflake, MotherDuck, Databricks, Trino, Athena)

When you configure a connection with additional databases using **Include Other Databases**, Omni automatically sets the catalog for views from non-default databases. Queries are then automatically routed to the correct database at query time.

## Limitations

Cross-database `JOINs` are not supported for PostgreSQL. Each query can only access tables from a single database.

## Syntax

```yaml theme={null}
catalog: <catalog_name>
```

## Properties

<ParamField type="string">
  The name of the database catalog containing the table. This is typically set automatically when using the **Include Other Databases** connection setting.
</ParamField>

## Examples

```yaml title="Table from a secondary PostgreSQL database" theme={null}
catalog: secondary_db
schema: public
table_name: categories
```

```yaml title="Table from the default database (catalog not needed)" theme={null}
schema: public
table_name: orders
```

## Related

* [Connecting PostgreSQL to Omni](/connect-data/setup/postgres)
* [schema](/modeling/views/parameters/schema)
* [table\_name](/modeling/views/parameters/table-name)


# custom_compound_primary_key_sql - Views
Source: https://docs.omni.co/modeling/views/parameters/custom-compound-primary-key-sql

Defines an array of field names that make up a view's compound primary key.

Defines an array of field names that make up a view's compound primary key.

<Tip>
  A better alternative to this parameter is to create a concatenated field that contains those fields, and then define the dimension-level parameter of `primary_key: true` for that field. This increases readability and potentially simplifies debugging primary key-related errors.

  ```yaml theme={null}
  primary_key_field:
    sql: concat(${field_1},'-',${field_2})
    primary_key: true
    hidden: true
  ```
</Tip>

## Syntax

```yaml theme={null}
custom_compound_primary_key_sql: [ field1, field2, ... ]
```

## Properties

<ParamField type="array">
  An array of field names that match the dimension names in your view definition. **Note**: When the view is saved, Omni will automatically format field references according to your database type:

  * **Snowflake** - Field names are automatically converted to uppercase and wrapped in double quotes. For example,`[ id, created_at_month ]` will become `[ '"ID"', '"CREATED_AT_MONTH"' ]`
  * **Google BigQuery** - Field names remain as entered without additional quotes. For example, `[ id, created_at_month ]` will remain as-is.
</ParamField>

## Examples

```yaml title="Compound primary key of id & created month" theme={null}
custom_compound_primary_key_sql: [ id, created_at_month ]
```


# default_drill_fields - Views
Source: https://docs.omni.co/modeling/views/parameters/default-drill-fields

Sets the default drill set for all measures in a view.

Sets the default drill set for all measures in a view. If a field has [`drill_fields`](/modeling/measures/parameters/drill-fields), this parameter will be overridden.

## Syntax

```yaml theme={null}
default_drill_fields: [ field1, field2, ... ]
```

## Properties

<ParamField type="array">
  An array of field names to include in the default drill set. Can be an empty array to remove drill.

  To remove drilling, add this parameter to the view but leave the value empty: `[]`
</ParamField>

## Examples

```yaml title="Default drill fields for order_items" theme={null}
default_drill_fields:
  [
    id,
    user_id,
    users.full_name,
    inventory_items.product_name,
    sale_price,
    margin,
    "order_items.created_at[date]",
    status
  ]
```

```yaml title="Remove drilling" theme={null}
default_drill_fields: []
```


# default_drill_query - Views
Source: https://docs.omni.co/modeling/views/parameters/default-drill-query

Sets the default drill query for all measures in a view.

Sets the default drill query for all measures in a view. Refer to the [Measure documentation](/modeling/measures/parameters/drill-queries) for more information.

## Syntax

```yaml theme={null}
default_drill_query:
  fields: [ <field1>, <field2> ... ]
  base_view: <view_name>
  limit: number
  sorts: [ <view>.<field>, ... ]
```

## Properties

<ParamField type="object">
  An object containing maps that describe how to build the default drill query.

  <Expandable title="default_drill_query properties">
    <ParamField type="array">
      An array of fields to include in the drill query.
    </ParamField>

    <ParamField type="string">
      The table that will act as the `FROM` clause of the query.
    </ParamField>

    <ParamField type="number">
      The number of rows to return in the drill query.
    </ParamField>

    <ParamField type="array">
      An array of fields used to sort the query, specified as `view_name.field_name`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Default drill query configuration for orders" theme={null}
default_drill_query:
  fields: [ sale_price, margin ]
  base_view: orders
  limit: 10
  sorts: [ orders.user_id ]
```


# description - Views
Source: https://docs.omni.co/modeling/views/parameters/description

Free text that describes the view.

Free text that describes the view. Descriptions are visible in the workbook, specifically in the **All views and fields** panel in the workbook.

For example, you could add copy that describes the type of analyses users can create using the view.

## Syntax

```yaml theme={null}
# Single line description
description: <description_text>

# Multi-line description
description: |
  <multiline_description_text>
```

## Properties

<ParamField type="string">
  Free text that describes the view. For multiline descriptions or descriptions containing special characters like colons, use the pipe (`|`) syntax. Values should be unquoted.
</ParamField>

## Examples

```yaml title="Single line description" theme={null}
description: Transactions from our online store.
```

```yaml title="Multi-line description" theme={null}
description: |
  Transactions from all online subsidiaries.
```


# display_order - Views
Source: https://docs.omni.co/modeling/views/parameters/display-order

Overrides the sort order for views in the field browser.

Overrides the sort order for views in the field browser. Defining this parameter will supersede Omni's default alphabetical sorting.

For example, if only one view has `display_order: 1`, it will display at the top of the list of views in the field browser. Other views will be sorted and displayed alphabetically.

## Syntax

```yaml theme={null}
display_order: <number>
```

## Properties

<ParamField type="number">
  A number that determines the view's position in the field browser.
</ParamField>

## Examples

```yaml title="Display view first" theme={null}
display_order: 1
```


# extends - Views
Source: https://docs.omni.co/modeling/views/parameters/extends

Inherit attributes from another view inside of Omni.

The extended view will inherit the attributes of the base or template view. Additional attributes can be added to the extended view, scoping them only to the extended view.

If attributes included in the extended view are also defined in the base view, the values in the extended view will override the values in the base view.

<Accordion icon="video" title="Click for video walkthrough">
  <iframe title="Navigating the Omni platform" />
</Accordion>

## Syntax

```yaml theme={null}
extends: [ <view_name> ]
```

## Properties

<ParamField type="array">
  The name of the view to extend.
</ParamField>

## Examples

```yaml title="base_view" theme={null}
description: This is a base view
```

In this example, we're extending `base_view` to create a new view, `extended_view`:

```yaml title="extended_view" wrap theme={null}
extends: [ base_view ]
description: This is an extended view from the base view
```

The `description` for `extended_view` will be `This is an extended view from the base view` instead of `base_view`'s `This is a base view`.


# fill_fields - Views
Source: https://docs.omni.co/modeling/views/parameters/fill-fields

Fills an enumerated list to ensure all values are represented in the dataset.

Fills an enumerated list to ensure all values are represented in the dataset. This parameter is useful when you want to use a [query view](/analyze-explore/saved-views) as a base table for other date objects and want to ensure all dates are represented in the data set, avoiding any ad hoc date series building.

<Note>
  To fill, Omni requires knowledge of the beginning and end of the fill set (e.g., `last 200 days`). If the date series is unbounded on either side, Omni will not fill the dimension.
</Note>

## Syntax

```yaml theme={null}
fill_fields: [ <view_name>.<field_name>, ... ]
```

## Properties

<ParamField type="array">
  A list of dimensions, specified as `view_name.field_name`.
</ParamField>

## Examples

```yaml title="Fill date dimension in query view" highlight={8} theme={null}
query:
  fields:
    [ "lead.created_date[week]", lead.count ]
  base_view: lead
  filters:
    lead.created_date:
      time_for_duration: [ 30 weeks ago, 30 weeks ]
  fill_fields: [ "lead.created_date[week]" ]
  sorts:
    - field: lead.created_date[week]
```


# folder - Views
Source: https://docs.omni.co/modeling/views/parameters/folder

Nests views in a folder in the model IDE for better organization.

Nests views in a folder in the model IDE for better organization. This parameter is useful for organizing schemas with large numbers of views.

## Syntax

```yaml theme={null}
folder: <schema_name>/<folder_name>
```

## Properties

<ParamField type="string">
  A path in the format `<schema_name>/<folder_name>` that determines where the view appears in the model IDE. The `schema_name` must be the name of the schema containing the view.

  Additionally, note that:

  * Only views in the same schema can be in the same folder. For example, views in `schema_one` and `schema_two` can't be in the same folder, even if specified.
  * This parameter only affects the model IDE. Defining a `folder` will not affect the appearance of the **All views & fields** view in the workbook.
</ParamField>

## Examples

```yaml title="Create customers folder in ecommerce schema" theme={null}
folder: ecommerce/customers
```


# hidden - Views
Source: https://docs.omni.co/modeling/views/parameters/hidden

Removes a view from the workbook UI while keeping it referenceable in the model.

Removes a view from the workbook UI while keeping it referenceable in the model. **Note**: Views are not removed from the model itself and will still be accessible via SQL. To "soft delete" a view instead, use the [`ignored`](/modeling/views/parameters/ignored) parameter.

## Syntax

```yaml theme={null}
hidden: true
```

## Properties

<ParamField type="boolean">
  If `true`, the view will be hidden in the UI.
</ParamField>

## Examples

```yaml title="Hide view in UI" theme={null}
hidden: true
```


# ignored - Views
Source: https://docs.omni.co/modeling/views/parameters/ignored

Soft-deletes a view in the model.

Soft-deletes a view in the model. This effectively removes the view from the model, which can be useful for hiding undesirable schema tables. When using this parameter, note that:

* When applied, references to the view will break, resulting in model validation errors
* Views are not removed from the schema and will still be accessible via SQL
* Any topics using this view as their `base_view` will be automatically hidden in workbooks and excluded from model validation

To instead hide a view from the workbook UI, use the [`hidden`](/modeling/views/parameters/hidden) parameter.

<Note>
  Topics with missing or non-existent base views will still surface validation errors.
</Note>

## Syntax

```yaml theme={null}
ignored: true
```

## Properties

<ParamField type="boolean">
  If `true`, the view will be ignored.
</ParamField>

## Examples

```yaml title="Ignore a view" theme={null}
ignored: true
```


# All View file parameters
Source: https://docs.omni.co/modeling/views/parameters/index

View files are used to define configuration, fields, and relationships for individual views.

| Parameter                                                                                         | Description                                                                                 |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [ai\_context](/modeling/views/parameters/ai-context)                                              | Free text that can provide context about a view to the Omni Agent.                          |
| [aliases](/modeling/views/parameters/aliases)                                                     | Map old table names to updated table names to preserve content.                             |
| [catalog](/modeling/views/parameters/catalog)                                                     | Specifies which database a table belongs to when a connection includes multiple databases.  |
| [custom\_compound\_primary\_key\_sql](/modeling/views/parameters/custom-compound-primary-key-sql) | Defines an array of field names that make up a view's compound primary key.                 |
| [default\_drill\_fields](/modeling/views/parameters/default-drill-fields)                         | Sets the default drill set for all measures in a view.                                      |
| [default\_drill\_query](/modeling/views/parameters/default-drill-query)                           | Set the default drill query for all measures in a view.                                     |
| [description](/modeling/views/parameters/description)                                             | Free text that describes the view.                                                          |
| [display\_order](/modeling/views/parameters/display-order)                                        | Overrides the sort order for views in the field browser.                                    |
| [extends](/modeling/views/parameters/extends)                                                     | Inherit attributes from another view inside of Omni.                                        |
| [fill\_fields](/modeling/views/parameters/fill-fields)                                            | Fills an enumerated list to ensure all values are represented in the dataset.               |
| [folder](/modeling/views/parameters/folder)                                                       | Nest views in a folder in the model IDE for better organization.                            |
| [hidden](/modeling/views/parameters/hidden)                                                       | Removes a view from the workbook UI while keeping it referenceable in the model.            |
| [ignored](/modeling/views/parameters/ignored)                                                     | Soft-deletes a view in the model.                                                           |
| [label](/modeling/views/parameters/label)                                                         | Overrides the name of the view in the UI.                                                   |
| [materialized\_query](/modeling/views/parameters/materialized-query)                              | Configures aggregate awareness between two views.                                           |
| [name](/modeling/views/parameters/name)                                                           | Reference name for the view, implicit in the file name.                                     |
| [query](/modeling/views/parameters/query)                                                         | Defines a view from a workbook query.                                                       |
| [required\_access\_grants](/modeling/views/parameters/required-access-grants)                     | Limits a user's ability to query a view based on assigned user attributes.                  |
| [schema](/modeling/views/parameters/schema)                                                       | Specifies the database schema for a table.                                                  |
| [schema\_label](/modeling/views/parameters/schema-label)                                          | Defines a display label for the database schema.                                            |
| [sql](/modeling/views/parameters/sql)                                                             | Defines a view from a SQL query.                                                            |
| [table\_name](/modeling/views/parameters/table-name)                                              | Specifies the database table name underlying the view.                                      |
| [tags](/modeling/views/parameters/tags)                                                           | Curates view and field groups for organizing and grouping views in the UI.                  |
| [template](/modeling/views/parameters/template)                                                   | Marks a view as a template only accessible through `extends` and disables model validation. |
| [uploaded\_table\_name](/modeling/views/parameters/uploaded-table-name)                           | Unique identifier for views created from uploaded CSV/XLSX files.                           |


# label - Views
Source: https://docs.omni.co/modeling/views/parameters/label

Defines a display name for the view.

Defines a display name for the view. This will override the view's name as it displays in the workbook.

## Syntax

```yaml theme={null}
label: <display name>
```

## Properties

<ParamField type="string">
  The display name that will appear in the UI instead of the view name.
</ParamField>

## Examples

```yaml title="View will display as Users With Orders in the UI" theme={null}
schema: Ecomm
table: Users
label: Users With Orders
```


# materialized_query - Views
Source: https://docs.omni.co/modeling/views/parameters/materialized-query

Configures aggregate awareness between two views.

Configures aggregate awareness between two views. This parameter should be used on the **aggregated view**, which will allow Omni to match the aggregated table to the underlying views it aggregates.

<Tip>
  Check out the [Aggregate awareness guide](/analyze-explore/performance/aggregate-awareness) for a comprehensive look at implementing aggregate awareness.
</Tip>

## Syntax

The `fields` parameter accepts two formats: an object (recommended) or an array.

<Tabs>
  <Tab title="Object (recommended)">
    ```yaml theme={null}
    materialized_query:
      fields:
        <view_name>.<field_name>: <aggregate_table_column_name>
        ...
      base_view: <view_name>
    ```
  </Tab>

  <Tab title="Array">
    ```yaml theme={null}
    materialized_query:
      fields: [ <view_name>.<field_name>, ... ]
      base_view: <view_name>
    ```
  </Tab>
</Tabs>

## Properties

<ParamField type="object | array">
  Maps field names from the base table to columns in the aggregated view, specified as `view_name.field_name`.

  * **Object format (recommended)**: Each key is a field from the base view and each value is the corresponding column name in the aggregate table. This format is more explicit and easier to maintain.
  * **Array format**: A positional array of field names that correspond to columns in the aggregated view in the order they appear in the view's `sql` statement.

    <Warning>
      When using the array format, field order matters! Make sure the fields listed match the column order in the view's `sql` statement.
    </Warning>

  Time dimensions must include a timeframe qualifier that matches the grain of the aggregate table, specified as `view_name.field_name[timeframe]` — for example, `order_items.created_at[month]` for a monthly table. In the object format, quote the key, because the brackets are otherwise not valid YAML.

  When the base view is used in a topic with joins to other tables, you must include the join keys to those dimension tables in the `fields` mapping for aggregate awareness to work across those joins. Without the join keys, Omni cannot optimize queries that involve joins.
</ParamField>

<ParamField type="string">
  The name of the base view that this aggregated view summarizes.
</ParamField>

## Examples

### Mapping fields to an aggregate table

In this example, you have an `order_items` table that contains a few metrics. Using aggregate awareness, you can create a `user_facts` table that rolls up these metrics.

Let's take a look at how the fields in the underlying views will map to the fields in the aggregated `user_facts` view:

| Underlying view fields          |         | Aggregated `user_facts` fields |
| ------------------------------- | ------- | ------------------------------ |
| `users.id`                      | becomes | `user_id`                      |
| `order_items.created_at[month]` | becomes | `month`                        |
| `order_items.count `            | becomes | `count`                        |
| `order_items.total_sale_price`  | becomes | `total_sale_price`             |

To create this view in Omni, the `user_facts.view` file would look like this:

<Tabs>
  <Tab title="Object (recommended)">
    ```yaml title="user_facts.view file" wrap theme={null}
    name: user_facts
    sql: |
      SELECT user_id, month, count, total_sale_price
      FROM user_facts
    dimensions:
      user_id: {}
      month: {}
      count: {}
      total_sale_price: {}
    materialized_query:
      fields:
        users.id: user_id
        "order_items.created_at[month]": month
        order_items.count: count
        order_items.total_sale_price: total_sale_price
      base_view: order_items
    ```
  </Tab>

  <Tab title="Array">
    ```yaml title="user_facts.view file" wrap theme={null}
    name: user_facts
    sql: |
      SELECT user_id, month, count, total_sale_price
      FROM user_facts
    dimensions:
      user_id: {}
      month: {}
      count: {}
      total_sale_price: {}
    materialized_query:
      fields:
        [
          users.id,
          "order_items.created_at[month]",
          order_items.count,
          order_items.total_sale_price
        ]
      base_view: order_items
    ```
  </Tab>
</Tabs>

Notice that `users.id` is included in the `fields` mapping. This is the join key between `order_items` and `users`, which enables aggregate awareness to work across joins in topics. When a query joins these tables, Omni can use the `user_facts` materialized view and perform the join against the pre-aggregated table rather than the full `order_items` table.

Without aggregate awareness, a query requesting these fields would join the underlying tables and aggregate at query time:

```sql title="Query without aggregate awareness" theme={null}
SELECT users.id as user_id,
       order_items.created_at[month] as month,
       COUNT(order_items.id) as count,
       SUM(order_items.sale_price) as total_sale_price
FROM order_items
JOIN users ON users.id = order_items.user_id
GROUP BY 1,2
```

With `materialized_query` configured, Omni recognizes that `user_facts` already contains these results and rewrites the query to hit the aggregate table directly, eliminating the join:

```sql title="Query with aggregate awareness" theme={null}
SELECT user_id, month, count, total_sale_price
FROM user_facts
```

### Using sketch-based approximate aggregates

You can also materialize and map sketch-based approximate aggregates, such as HyperLogLog (HLL). A sketch is a compact binary summary of a column that Omni can roll up from a finer grain to a coarser one.

Sketches need two measures in the base view. In this Snowflake example, the base `order_items` view builds the sketch in one measure and derives the estimate in another:

```yaml title="order_items.view file" wrap theme={null}
measures:
  # Builds the sketch. Hidden because sketches are binary and unreadable in results.
  user_sketch:
    sql: HLL_ACCUMULATE(${user_id})
    hidden: true

  # Derives the estimate from the sketch. This is the measure users query.
  user_approx_distinct_count:
    sql: HLL_ESTIMATE(${user_sketch})
```

The aggregated view maps the **sketch** measure to the sketch column:

```yaml title="daily_user_sketches.view file" wrap theme={null}
name: daily_user_sketches
sql: |
  SELECT date, user_sketch
  FROM daily_user_sketches
dimensions:
  date: {}
  user_sketch: {}
materialized_query:
  fields:
    "order_items.created_at[date]": date
    order_items.user_sketch: user_sketch
  base_view: order_items
```

The sketch column is a stored value in the aggregate table, so declare it as a dimension in the aggregated view even though it maps to a measure in the base view.

When you query `order_items.user_approx_distinct_count`, Omni routes the query to the materialized sketch in `daily_user_sketches` instead of the base table.

<Warning>
  Map the sketch measure, not the estimate measure. If one measure contains the full expression, such as `HLL_ESTIMATE(HLL_ACCUMULATE(${user_id}))`, and you map that measure in `fields`, Omni can't route the query.
</Warning>

The [Aggregate awareness guide](/analyze-explore/performance/aggregate-awareness#using-sketch-based-approximate-aggregates) covers the supported sketch functions for Snowflake, BigQuery, and Databricks, and [when a Snowflake sketch needs `HLL_IMPORT`](/analyze-explore/performance/aggregate-awareness#importing-snowflake-sketches).


# name - Views
Source: https://docs.omni.co/modeling/views/parameters/name

Reference name for the view, implicit in the file name.

Reference name for the view, implicit in the file name. This parameter is how the view and the fields it contains are referenced, independent of the labels applied.

<Note>
  View names are automatically generated from database table names. The naming convention can be affected by your connection's [**Always Scope View Names**](/connect-data/view-name-generation) setting, which controls whether catalog and schema prefixes are included.
</Note>

## Syntax

```yaml theme={null}
# Reference this view as view_file_name
```

## Properties

<ParamField type="string">
  The name used to reference the view, derived from the file name. Cannot be explicitly set in the file.
</ParamField>

## Examples

In this example, if the file is named `ecomm__users.view`, the view will be referenced as `ecomm__users`, regardless of the `label` parameter.

```yaml title="View name from file name" theme={null}
# Reference this view as ecomm__users
schema: Ecomm
table: Users
label: Users With Orders
```


# query - Views
Source: https://docs.omni.co/modeling/views/parameters/query

Defines a view from a workbook query.

Defines a view from a workbook query.

<Tip>
  For an easier building experience, build your [query view using the workbook](/analyze-explore/saved-views) and then promote it to the shared model.
</Tip>

## Syntax

```yaml theme={null}
query:
  fields:
    <view_name>.<field_name>
    <view_name>.<field_name>: <optional_alias>
  base_view: <view_name>
  filters: [ ... ]
```

## Properties

<ParamField type="object">
  An object containing query sub-parameters.

  <Expandable title="query properties">
    <ParamField type="array">
      Fields to include in the query, specified as `view_name.field_name`. To alias fields, specify as `view_name.field_name: alias`.
    </ParamField>

    <ParamField type="string">
      The view to use as the base for the query.
    </ParamField>

    <ParamField type="object">
      Filters to apply to the query, specified using [filter syntax](/modeling/filters).
    </ParamField>
  </Expandable>
</ParamField>

## Examples

In this example, `query.fields` contains aliased fields - that is, the string **after** the colon defines the alias. For example, `created_at`.

The `dimensions.sales` field is an example of a field that was **not** aliased.

```yaml title="Example with aliased fields" theme={null}
query:
  fields:
    order_items.created_at[date]: created_at
    order_items.user_id: user_id
    order_items.total_sales
  filters:
    orders.amount_returns:
      not: 0
  base_view: order_items

dimensions:
  created_at:
    timeframes: [date]
    sql: created_at
  user_id:
    sql: user_id
  sales:
    sql: order_items__total_sales
```


# required_access_grants - Views
Source: https://docs.omni.co/modeling/views/parameters/required-access-grants

Limits a user's ability to query a view based on assigned user attributes.

Limits a user's ability to query a view based on assigned user attributes. `AND` and `OR` conditions are supported.

Refer to the [Controlling data access guide](/modeling/develop/data-access-control) for more information.

## Syntax

```yaml theme={null}
required_access_grants: [ grant_name ]
```

## Properties

<ParamField type="array">
  An array of access grant names, which must already exist in the [model file](/modeling/models/access-grants).

  Use `|` for `OR` conditions and `&` for `AND` conditions.
</ParamField>

## Examples

```yaml title="Single access grant" theme={null}
required_access_grants: [ grant_one ]
```

```yaml title="Grant access if conditions are met for either access grant" theme={null}
required_access_grants: [ grant_one|grant_two ]
```

```yaml title="Grant access if grant_one OR (grant_two & grant_three) are met" theme={null}
required_access_grants: [ grant_one|grant_two&grant_three ]
```


# schema - Views
Source: https://docs.omni.co/modeling/views/parameters/schema

Specifies the database schema for a view.

Specifies the database schema for a view.

<Warning>
  **Views are required to have this parameter**, otherwise model validation issues will surface in the model IDE.
</Warning>

## Syntax

```yaml theme={null}
schema: <schema_name>
```

## Properties

<ParamField type="string">
  The name of the database schema containing the table.
</ParamField>

## Examples

```yaml title="Github schema with asset table" theme={null}
schema: GITHUB
table_name: ASSET
```


# schema_label - Views
Source: https://docs.omni.co/modeling/views/parameters/schema-label

Defines a display label for the database schema.

Defines a display label for the database schema.

## Syntax

```yaml theme={null}
schema_label: <Schema display name>
```

## Properties

<ParamField type="string">
  The display label for the database schema.
</ParamField>

## Examples

```yaml title="Schema label for Github schema" theme={null}
schema_label: Github Schema
table_name: ASSET
```


# sql - Views
Source: https://docs.omni.co/modeling/views/parameters/sql

Defines a view from a SQL query.

Defines a view from a SQL query.

<Tip>
  For an easier building experience, build your [SQL view using the workbook](/analyze-explore/sql) and then promote it to the shared model.
</Tip>

## Syntax

```yaml theme={null}
sql: |
  SELECT <statement>
```

## Properties

<ParamField type="string">
  A raw SQL query that defines the view.
</ParamField>

## Examples

```yaml title="SQL view with primary key" theme={null}
sql: |
  SELECT *
  FROM users
  LIMIT 10

dimensions:
  id:
    sql: id
    primary_key: true
  first_name:
    sql: first_name
```


# table_name - Views
Source: https://docs.omni.co/modeling/views/parameters/table-name

Specifies the database table name underlying the view.

Specifies the database table name underlying the view. If not defined, Omni will infer `table_name: {view_name}`.

## Syntax

```yaml theme={null}
table_name: <table_name>
```

## Properties

<ParamField type="string">
  The name of the database table underlying the view. If not specified, defaults to the view file name.
</ParamField>

## Examples

```yaml title="orders table in ecomm schema" theme={null}
schema: ecomm
table_name: orders
```


# tags - Views
Source: https://docs.omni.co/modeling/views/parameters/tags

Curates view and field groups for organizing and grouping views in the UI.

Curates view and field groups for organizing and grouping views in the UI.

## Syntax

```yaml theme={null}
tags: [<tag1>, <tag2>, ...]
```

or

```yaml theme={null}
tags:
  - <tag1>
  - <tag2>
  - ...
```

## Properties

<ParamField type="array">
  A comma-delimited array of strings used for organizing and grouping views.

  If using [Databricks Unity Catalog](/connect-data/databricks-unity-catalog-integration), schema refreshes automatically populate this parameter from the table's Unity Catalog `TABLE_TAGS`. A tag with a value renders as `name: value`, and a tag without a value renders as a bare `name`. This doesn't apply to legacy `hive_metastore` catalogs, which don't have Unity Catalog tag data. If you edit `tags` in the shared model, your changes are preserved on later refreshes.
</ParamField>

## Examples

```yaml theme={null}
tags: [ sales ]
```

```yaml Databricks Unity Catalog tag with a value theme={null}
tags: [ "pii: A"]
```

```yaml Databricks Unity Catalog tag without a value theme={null}
tags: [ pii ]
```


# template - Views
Source: https://docs.omni.co/modeling/views/parameters/template

Marks a view as a template only accessible through `extends` and disables model validation.

Marks a view as an abstract template. Template views cannot be used directly — they must be extended by another view using the [`extends`](/modeling/views/parameters/extends) property. This enables reusable view patterns and inheritance.

Template views have relaxed model validation, meaning missing columns will not cause errors. This allows you to define abstract structures that are completed by the extending view. Refer to this [community article](https://community.omni.co/t/how-can-i-share-logic-across-multiple-models-hub-and-spoke/150) for more information.

When a non-template view extends a template view, it inherits all of the template's attributes and can override or add to them.

## Syntax

```yaml theme={null}
template: true/false
```

## Properties

<ParamField type="boolean">
  Controls whether the view is treated as an abstract template. When set to `true`, the view cannot be used directly and must be extended by another view. Omni will also disable model validation for the view.
</ParamField>

## Examples

```yaml title="template_view" theme={null}
template: true

required_access_grants: [ marketing ]
```

```yaml title="extended_view" theme={null}
extends: [template_view]

# Inherits required_access_grants from template_view
# Can override or add additional attributes
required_access_grants: [ sales ]
```


# uploaded_table_name - Views
Source: https://docs.omni.co/modeling/views/parameters/uploaded-table-name

Unique identifier for views created from uploaded CSV/XLSX files.

Unique identifier for views created from uploaded CSV/XLSX files. This parameter is not modifiable.

<Tip>
  Check out the [Uploading CSVs guide](/analyze-explore/data-input-csvs) for more information about file uploads & data input tables.
</Tip>

## Syntax

```yaml theme={null}
uploaded_table_name: filename::uuid
```

## Properties

<ParamField type="string">
  A unique identifier in the format `filename::uuid`, used by Omni to identify the uploaded table in Omni storage.
</ParamField>

## Examples

```yaml title="Uploaded products CSV" theme={null}
uploaded_table_name: products.csv::1a3497f5-cba8-47c0-bab9-b2df84d1b141
```


# Delivering Omni content to Amazon S3
Source: https://docs.omni.co/share/deliveries/amazon-s3

Deliver scheduled reports and dashboards to an Amazon S3 bucket using cross-account IAM role assumption.

Omni delivers content to Amazon S3 using cross-account IAM role assumption. No long-lived AWS credentials are stored — Omni obtains temporary credentials via AWS STS at delivery time.

## Requirements

To set up an Amazon S3 delivery, you'll need:

* An AWS account with permissions to create IAM roles
* An S3 bucket to deliver content to (or permissions to create one)

## Setup

<Steps>
  <Step title="Retrieve Omni's AWS information">
    1. Navigate to a **published** dashboard.
    2. Click **File > Deliveries & Alerts**. The delivery options will display on the left side of the page.
    3. Click **New** to create a new delivery.
    4. For **Destination**, select **Amazon S3**.
    5. Click the **Amazon S3 tab**.

    At the top of the form, note the following values — you'll need them to create an IAM role in the next step:

    * **Omni Deliverer Role ARN** — The identity Omni uses to access your S3 bucket. Copy this value.
    * **External ID** — Your organization's unique identifier. This value is the same for all Amazon S3 deliveries in your organization — you only need to configure your IAM trust policy once. Copy this value.
  </Step>

  <Step title="Create an IAM permissions policy in AWS">
    In this step, you'll create a policy that defines the permissions the Omni IAM role will have to your S3 bucket. You'll attach this policy to the Omni role in the next step.

    1. Open a new tab in your browser and navigate to the AWS console.
    2. In the AWS Console, navigate to **IAM > Policies**.
    3. Click **Create policy**.
    4. In the **Policy editor** section, click the **JSON** toggle.
    5. Paste in the following, replacing `YOUR-BUCKET-NAME` with the name of your S3 bucket:

       ```json title="Omni S3 policy" highlight={13} theme={null}
       {
         "Version": "2012-10-17",
         "Statement": [
           {
             "Effect": "Allow",
             "Action": [
               "s3:PutObject",
               "s3:CreateMultipartUpload",
               "s3:UploadPart",
               "s3:CompleteMultipartUpload",
               "s3:AbortMultipartUpload"
             ],
             "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
           }
         ]
       }
       ```

       <Tip>
         To restrict uploads to a specific folder in your bucket, change the permission policy resource to `arn:aws:s3:::YOUR-BUCKET-NAME/some/prefix/*`.
       </Tip>
    6. Click **Next**.
    7. Enter a name for the policy, such as `OmniDeliveryPolicy`.
    8. Click **Create policy**.
  </Step>

  <Step title="Create an IAM role in AWS">
    In this step, you'll create an IAM role for Omni. This will associate the role with Omni's AWS identity and the permissions policy you created in the previous step, giving Omni access to write to the S3 bucket.

    1. In the AWS Console, navigate to **IAM > Roles**.

    2. Click **Create role**.

    3. Select **Custom trust policy** and paste in the following, replacing the placeholder values with the **Omni Deliverer Role ARN** and **External ID** from [step 1](#retrieve-omnis-aws-information) of this guide:

       ```json title="Omni custom trust policy" highlight={7,12} theme={null}
       {
         "Version": "2012-10-17",
         "Statement": [
           {
             "Effect": "Allow",
             "Principal": {
               "AWS": "<Omni Deliverer Role ARN>"
             },
             "Action": "sts:AssumeRole",
             "Condition": {
               "StringEquals": {
                 "sts:ExternalId": "<External ID>"
               }
             }
           }
         ]
       }
       ```

       <Note>
         **What's the External ID for?** This prevents [confused deputy attacks](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html), ensuring that only your Omni organization can assume this role.
       </Note>

    4. Click **Next**.

    5. In the list of permissions policies, locate and select the one you created in the previous step.

    6. Click **Next**.

    7. Enter a name for the role, such as `OmniS3DeliveryRole`.

    8. Click **Create role**.

    9. Open the newly created role and copy its **ARN** — you'll enter this in Omni in a later step.
  </Step>

  <Step title="Configure delivery settings">
    1. Navigate back to the Omni tab in your browser. The delivery you started creating in [step 1](#retrieve-omnis-aws-information) should still be open.
    2. Fill in the delivery options:
       * **Delivery** - Select **Schedule** or **Alert**.
       * **Send** - Select the content you want to deliver.
       * **Destination** - This should already be set to **Amazon S3**.
       * **Name** - Enter a name for the delivery.

    **If creating an alert**, use the **Alert** tab to define the conditions that must be met to trigger the delivery. For example, you have a chart that tracks the **Total sales** for your ecommerce company. Using an alert, you can trigger a delivery when the total of your sales has changed.
  </Step>

  <Step title="Configure the delivery schedule">
    In this step, you'll define the cadence for the delivery:

    * For **schedules**, this determines when Omni will deliver the specified content to the destination
    * For **alerts**, this tells Omni when to check if the current query results meet the conditions required to send the delivery

    Schedules can be defined using the visual options or with cron:

    <AccordionGroup>
      <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
        Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

        By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
      </Accordion>

      <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
        A cron expression is a string that describes the individual details of a schedule:

        | Order | Unit         | Allowed values  | Allowed special characters |
        | ----- | ------------ | --------------- | -------------------------- |
        | 1     | minute       | 0-59            | \* , - /                   |
        | 2     | hour         | 0-23            | \* , - /                   |
        | 3     | day of month | 1-31            | \* , - / L W ?             |
        | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
        | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
        | 6     | year         | any             | \* , - /                   |

        Using cron, you can create schedules like the following:

        ```markdown title="At 9:00 AM every day" theme={null}
        0 9 ? * * *
        ```

        ```markdown title="At 6:30AM on the last day of the month" theme={null}
        30 6 L * ? *
        ```

        ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
        45 8 ? * MON-FRI *
        ```

        Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

        <Tip>
          If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every weekday at 9am" or "first Monday of each month at noon."
        </Tip>
      </Accordion>
    </AccordionGroup>

    <Tip>
      Schedule send timezone may be different than query run timezone. For example, if your **Database timezone** is `UTC` with no other timezone conversion settings and you set your schedule to send at `12:00 PM PST`, the query will execute at `8:00 PM UTC`.

      Refer to your [connection timezone settings](/connect-data/timezones) for more information.
    </Tip>
  </Step>

  <Step title="Select format and filter options">
    <Tip>
      You can use filters to customize content for different recipients! For example, set a filter to `A` in a scheduled delivery to recipient A, and in another scheduled delivery to recipient B, set a filter to `B`.
    </Tip>

    In the **Dashboard** or **Chart** tab, you can:

    * **Select the format of the content**, such as PNG, PDF, XLSX, or CSV.
    * **Lightly customize the contents and layout**, such as expanding tables to include up to 1,000 rows, hiding filter values, or arranging tiles in a single column.
    * **Select the page(s) to include in the dashboard delivery**. This is applicable only to [advanced layouts](/visualize-present/dashboards/advanced-layout) with multiple pages.

      **Note**: PNGs can only include one page. You'll need to create multiple deliveries to output a PNG for each page.
    * **Override the query timezone for the delivery** using the [timezone picker](/visualize-present/dashboards/timezone-override). The picker label changes based on whether **Personalize delivery with recipient user attributes** is enabled (**Recipient's timezone** when enabled, **Default timezone** when disabled).

      This setting affects the content of queries included in the delivery, not the timing of the delivery itself. Use the **Schedule** tab to define when content should be delivered.
    * **Set filter or control values for the delivery**. Some formats will have additional customization options. PDF formats, for example, will allow you to specify the orientation and page size for the PDF.

      For dashboard deliveries, the default filters and controls will automatically be applied upon creation. Subsequent default filter value updates will not change the filter values set for existing deliveries.
  </Step>

  <Step title="Configure Amazon S3 settings">
    Click the **Amazon S3** tab and enter the following:

    * **IAM role ARN** — **Required**. The ARN of the IAM role Omni will assume to write to your bucket. For example, `arn:aws:iam::123456789012:role/OmniS3DeliveryRole`.
    * **Bucket** — **Required**. The name of your Amazon S3 bucket.
    * **Optional path** — The folder that you want to save your data to, if any. Supports [Mustache templates](/share/deliveries/dynamic-content) like `{{currentYear}}/{{currentMonth}}/{{currentDay}}/` for date-partitioned exports. For example, `reports/weekly/` or `{{currentYear}}/{{currentMonth}}/{{currentDay}}/`.
    * **File name (without extension)** — A custom filename template. Supports [Mustache templates](/share/deliveries/dynamic-content) like `{{currentDate}}` and `{{scheduledTaskName}}`.
    * **Region** — **Required**. The Amazon services region where your S3 bucket is hosted. This must match the bucket's actual region.
  </Step>

  <Step title="Test the delivery">
    If you want to test the delivery before saving, click the **Test Now** button in the bottom left corner of the page. This will send the dashboard/chart to the destination using the current settings. For example, using **Test Now** would send the delivery to all **Recipients**.

    <Note>
      The **Test Now** button will be unavailable for alerts if the **Condition type** is `Results have changed` or `Results have stayed the same`. A workaround is to use the **Send Now** option to manually trigger the delivery, which is available once the delivery has been saved.

      Save the alert and then click the <Icon icon="ellipsis-vertical" type="solid" /> icon to display the **Send Now** option. This will initiate a check on the alert condition - if the condition isn't met, the delivery will show as successful but not send anything.
    </Note>
  </Step>

  <Step title="Save the delivery">
    When finished, click **Save** to create the delivery.
  </Step>
</Steps>

## Troubleshooting

If a delivery to Amazon S3 fails, an error email is sent to the delivery owner. The following table describes common errors and how to resolve them:

| Error                           | Resolution                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unable to assume the IAM role   | Verify the **IAM Role ARN** in Omni matches the role you created. Check that the trust policy uses the correct **Omni Deliverer Role ARN** as the Principal and the correct **External ID** in the condition. See the [Create an AWS IAM role](#create-an-iam-role-in-aws) step of this guide for the required information.                                                                     |
| Access denied writing to bucket | Verify the IAM role's permission policy includes the required S3 actions (`s3:PutObject`, `s3:CreateMultipartUpload`, `s3:UploadPart`, `s3:CompleteMultipartUpload`, `s3:AbortMultipartUpload`) and that the `Resource` ARN matches your bucket name. See the [Create an AWS IAM permissions policy](#create-an-iam-permissions-policy-in-aws) step of this guide for the required information. |
| Bucket not found                | Verify the **Bucket name** and **Region** in Omni match the actual S3 bucket. Bucket names are case-sensitive.                                                                                                                                                                                                                                                                                  |
| Could not connect to S3         | Verify the **Region** in Omni matches the AWS region where the bucket was created.                                                                                                                                                                                                                                                                                                              |


# Creating dynamic delivery content with Mustache
Source: https://docs.omni.co/share/deliveries/dynamic-content

Create dynamic content for your deliveries with Mustache syntax.

Certain configuration options in delivery destinations support using Mustache references to personalize aspects of the delivery, such as:

* An email subject
* File names, including email and SFTP
* Amazon S3 optional path
* Slack message content

This guide describes the references that are currently supported and provides some example outputs.

## User attributes

<Note>
  User attributes aren't supported for SFTP destinations.
</Note>

You can use the [default system user attributes](/administration/users/attributes#default-system-user-attributes) to personalize the delivery. For example:

```markdown wrap title="Delivery subject & body" theme={null}
Subject: Daily tasks for {{omni_user_name}}

Body: 

Hey there, {{omni_user_name}}! Here are your tasks for the day:
```

Email deliveries also support [custom-defined user attributes](/administration/users/attributes). **Note**: This is only supported for email deliveries.

## Date and time

<Note>
  **Unless noted**, all destinations support the references in this section.
</Note>

The values of these references will reflect the delivery's [schedule settings](/share/deliveries). For example, if the schedule is configured to use the `America/New_York` timezone, the values that recipients see will be in that timezone.

<ParamField>
  Current date in `YYYY-MM-DD` format

  **Example output**: `2025-07-24`
</ParamField>

<ParamField>
  Yesterday's date in `YYYY-MM-DD` format

  **Example output**: `2025-07-23`
</ParamField>

<ParamField>
  Current year

  **Example output**: `2025`
</ParamField>

<ParamField>
  Current month

  **Example output**: `07`
</ParamField>

<ParamField>
  Current day of the month

  **Example output**: `24`
</ParamField>

<ParamField>
  Current time in `HH:MM:SS AM/PM` format

  **Example output**: `1:00:00 PM`
</ParamField>

<ParamField>
  Current timezone

  **Example output**: `(America/New_York)`
</ParamField>

## Schedule details

<Note>
  **Unless noted**, all destinations support the references in this section.
</Note>

<ParamField>
  Name of the dashboard/workbook

  **Example output**: `Daily team planning`
</ParamField>

<ParamField>
  **Not supported for SFTP**. A link to the dashboard/workbook.

  **Example output**: `https://blobsrus.omni.co/dashboards/3eafe04d`
</ParamField>

<ParamField>
  The format of the delivery

  **Example output**: `png`
</ParamField>

<ParamField>
  The name of the scheduled task. Will not populate for one-off deliveries - task must be saved.

  **Example output**: `Daily Task Schedule`
</ParamField>

<ParamField>
  **Not supported for SFTP**. The description of the scheduled task. Will not populate for one-off deliveries - task must be saved.

  **Example output**: `Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays at 09:00 am EDT`
</ParamField>

## Recipients

<ParamField>
  **Email destinations only.** The recipient's email.

  **Example output**: `blobby@blobsrus.com`
</ParamField>

<ParamField>
  **Not supported for SFTP**. The number of recipients who received the delivery.

  **Example output**: `5`
</ParamField>

## Examples

```markdown title="Greeting with Omni user name attribute" theme={null}
Dear {{omni_user_name}},
```

```markdown wrap title="Link to dashboard/workbook" theme={null}
Review the {{entityName}} report here: {{entityLink}}
```

```markdown wrap title="Slack only - Clickable link to dashboard/workbook" theme={null}
Review the <{{entityLink}}|{{entityName}}> report
```

```markdown wrap title="Report generated at" theme={null}
This automated report was generated on {{currentMonth}}/{{currentDay}}/{{currentYear}} at {{currentTime}}.
```

```markdown title="Delivery recipient" theme={null}
Report delivered to: {{recipientEmail}}
```

```markdown title="SFTP file name" theme={null}
{{currentDate}}-{{entityName}}
```


# Restricting recipient email domains with allowlist
Source: https://docs.omni.co/share/deliveries/email/domain-allowlist

Restrict email deliveries to recipients at approved domains.

The domain allowlist feature allows you to restrict [email deliveries](/share/deliveries/email) to specific email domains only. When configured, Omni will only send deliveries to recipients whose email addresses match one of the allowed domains. This is especially useful for maintaining control over where organizational data can be sent.

## Requirements

**Organization Admin** permissions are required to configure the domain allowlist.

## Adding domains to the allowlist

<Note>
  You can configure up to 1,000 domains in the allowlist.
</Note>

To configure allowed email domains:

<Steps>
  <Step>
    Click **Settings > Deliveries > Email tab**.
  </Step>

  <Step>
    In the **Domain allowlist** section, enter the domains you want to allow (for example, `example.com`).

    As you add domains, Omni displays a real-time **Impact on existing schedules** preview showing which schedules would be affected by the current allowlist configuration.
  </Step>

  <Step>
    Review the impact preview. If any schedules would be blocked by the current allowlist, the **Save allowlist** button will be disabled. You'll need to either add more domains to accommodate those schedules or update the affected schedules first.
  </Step>

  <Step>
    Once all existing schedules are compatible with your allowlist, click **Save allowlist**.
  </Step>
</Steps>

## Clearing the allowlist

To remove all domain restrictions and allow deliveries to any email address:

<Steps>
  <Step>
    Click **Settings > Deliveries > Email tab**.
  </Step>

  <Step>
    In the **Domain allowlist** section, click **Clear allowlist**.
  </Step>

  <Step>
    When prompted, confirm the change.
  </Step>
</Steps>

## Next steps

* [Create an email delivery](/share/deliveries/email)
* [Whitelabel sender addresses for email deliveries](/share/deliveries/email/whitelabel)
* [Manage deliveries](/share/deliveries/manage)


# Delivering Omni content via email
Source: https://docs.omni.co/share/deliveries/email/index

With email deliveries, you can automatically schedule sending dashboards and individual tiles to your team.

## Creating an email delivery

<Steps>
  <Step title="Configure the delivery settings">
    1. Navigate to a **published** dashboard.
    2. Click **File > Deliveries & Alerts**. The delivery options will display on the left side of the page.
    3. Fill in the following:

       * **Delivery** - Select **Schedule** or **Alert**.
       * **Send** -&#x20;
       * **Destination** - Select .
       * **Name** - Enter a name for the delivery.

    **If creating an alert**, use the **Alert** tab to define the conditions that must be met to trigger the delivery. For example, you have a chart that tracks the **Total sales** for your ecommerce company. Using an alert, you can trigger a delivery when the total of your sales has changed.
  </Step>

  <Step title="Configure the delivery schedule">
    In this step, you'll define the cadence for the delivery:

    * For **schedules**, this determines when Omni will deliver the specified content to the destination
    * For **alerts**, this tells Omni when to check if the current query results meet the conditions required to send the delivery

    Schedules can be defined using the visual options or with cron:

    <AccordionGroup>
      <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
        Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

        By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
      </Accordion>

      <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
        A cron expression is a string that describes the individual details of a schedule:

        | Order | Unit         | Allowed values  | Allowed special characters |
        | ----- | ------------ | --------------- | -------------------------- |
        | 1     | minute       | 0-59            | \* , - /                   |
        | 2     | hour         | 0-23            | \* , - /                   |
        | 3     | day of month | 1-31            | \* , - / L W ?             |
        | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
        | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
        | 6     | year         | any             | \* , - /                   |

        Using cron, you can create schedules like the following:

        ```markdown title="At 9:00 AM every day" theme={null}
        0 9 ? * * *
        ```

        ```markdown title="At 6:30AM on the last day of the month" theme={null}
        30 6 L * ? *
        ```

        ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
        45 8 ? * MON-FRI *
        ```

        Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

        <Tip>
          If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every weekday at 9am" or "first Monday of each month at noon."
        </Tip>
      </Accordion>
    </AccordionGroup>

    <Tip>
      Schedule send timezone may be different than query run timezone. For example, if your **Database timezone** is `UTC` with no other timezone conversion settings and you set your schedule to send at `12:00 PM PST`, the query will execute at `8:00 PM UTC`.

      Refer to your [connection timezone settings](/connect-data/timezones) for more information.
    </Tip>
  </Step>

  <Step title="Select format and filter options">
    <Tip>
      You can use filters to customize content for different recipients! For example, set a filter to `A` in a scheduled delivery to recipient A, and in another scheduled delivery to recipient B, set a filter to `B`.
    </Tip>

    In the **Dashboard** or **Chart** tab, you can:

    * **Select the format of the content**, such as PNG, PDF, XLSX, or CSV.
    * **Lightly customize the contents and layout**, such as expanding tables to include up to 1,000 rows, hiding filter values, or arranging tiles in a single column.
    * **Select the page(s) to include in the dashboard delivery**. This is applicable only to [advanced layouts](/visualize-present/dashboards/advanced-layout) with multiple pages.

      **Note**: PNGs can only include one page. You'll need to create multiple deliveries to output a PNG for each page.
    * **Override the query timezone for the delivery** using the [timezone picker](/visualize-present/dashboards/timezone-override). The picker label changes based on whether **Personalize delivery with recipient user attributes** is enabled (**Recipient's timezone** when enabled, **Default timezone** when disabled).

      This setting affects the content of queries included in the delivery, not the timing of the delivery itself. Use the **Schedule** tab to define when content should be delivered.
    * **Set filter or control values for the delivery**. Some formats will have additional customization options. PDF formats, for example, will allow you to specify the orientation and page size for the PDF.

      For dashboard deliveries, the default filters and controls will automatically be applied upon creation. Subsequent default filter value updates will not change the filter values set for existing deliveries.

    #### PNG deliveries

    If you select the PNG (image) format, how the image is included with the email will depend on the image's size:

    <AccordionGroup>
      <Accordion title="Deliveries 2MB or less" icon="less-than">
        **If 2MB or less**, the image will be included inline in the email:

        <img alt="" />
      </Accordion>

      <Accordion title="Deliveries larger than 2MB" icon="greater-than">
        **If larger than 2MB**, the image will be included as an attachment. Omni takes this approach to prevent failed deliveries, as some email providers limit how large inline images can be.

        <img alt="" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Configure email settings">
    To finish setting up the delivery, click the **Email** tab and fill in the following:

    <AccordionGroup>
      <Accordion title="Recipients" icon="users">
        <Tip>
          Restrict email deliveries to recipients at approved domains with the [domain whitelist](/share/deliveries/email/domain-allowlist).
        </Tip>

        Add one or more recipients. Recipients can be other members of your Omni organization or non-users, such as a contractor or external stakeholder. You can also add Omni user groups as recipients.

        When adding recipients, note that:

        * **When existing Omni users are added as recipients** there are no checks on whether or not each of those users have system access (connection or content permissions) to the content being scheduled. This means users could potentially *receive* content that they do not otherwise have access to in the Omni application.
        * **When non-users are added as recipients** - that is, when a user with the recipient's email can't be matched to an Omni user - Omni creates an [**email-only user**](/administration/users/email-only). These accounts are created when a delivery is saved to allow you to monitor scheduler usage and related metadata.
        * **If a user belongs to multiple user groups**, they will only receive one delivery.
      </Accordion>

      <Accordion title="Personalize delivery with the recipient's user attributes" icon="wand-sparkles">
        If enabled, the content of the delivery will be personalized using the recipients' [user attributes](/administration/users/attributes). Otherwise, the delivery owner's user attributes will be used.

        See [Personalizing email deliveries with recipient attributes](/share/deliveries/email/personalization) for more information about personalization, including how Omni resolves delivery recipients by email.

        <Note>
          The ability to configure this per-delivery is dependent on how your organization's [**Delivery personalization** setting](/administration/content-permissions#delivery-personalization) is set and whether any connections use [per-user OAuth](/connect-data/oauth). See [Personalizing email deliveries with recipient attributes](/share/deliveries/email/personalization) for more information.
        </Note>
      </Accordion>

      <Accordion title="Subject and body" icon="envelope">
        <Tip>
          Email subjects and bodies can include [Mustache references](/share/deliveries/dynamic-content), including [user attributes](/administration/users/attributes), allowing you to create dynamic, personalized content for recipients.
        </Tip>

        Enter a **subject** and a **body** message for the email delivery.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Test the delivery">
    If you want to test the delivery before saving, click the **Test Now** button in the bottom left corner of the page. This will send the dashboard/chart to the destination using the current settings. For example, using **Test Now** would send the delivery to all **Recipients**.

    <Note>
      The **Test Now** button will be unavailable for alerts if the **Condition type** is `Results have changed` or `Results have stayed the same`. A workaround is to use the **Send Now** option to manually trigger the delivery, which is available once the delivery has been saved.

      Save the alert and then click the <Icon icon="ellipsis-vertical" type="solid" /> icon to display the **Send Now** option. This will initiate a check on the alert condition - if the condition isn't met, the delivery will show as successful but not send anything.
    </Note>
  </Step>

  <Step title="Save the delivery">
    When finished, click **Save** to create the delivery.
  </Step>
</Steps>

## Subscribing to email deliveries

If you aren't currently a recipient of an email delivery, you can subscribe if you have the ability to view the schedule. In a published dashboard, navigate to **File > Deliveries & Alerts** and then click the **Subscribe** link under the schedule:

<img alt="" />

<Note>
  In an embedded context, users with a defined embed [entity](/embed/setup/url-parameters) will only see schedules created by users in the same embed entity. Embed users that don't have a defined `entity` property will only see their schedules.
</Note>

## Next steps

* [Personalize email delivery content](/share/deliveries/email/personalization)
* [Restrict recipient email domains with an allowlist](/share/deliveries/email/domain-allowlist)
* [Whitelabel sender addresses for email deliveries](/share/deliveries/email/whitelabel)
* [Manage deliveries](/share/deliveries/manage)


# Personalizing email deliveries with recipient attributes
Source: https://docs.omni.co/share/deliveries/email/personalization

Personalize the content of email deliveries using each recipient's user attributes.

The content of [email deliveries](/share/deliveries/email) can be personalized using the recipients' [user attributes](/administration/users/attributes). For example, you could use personalization to deliver a dashboard to sales managers that only displays quarterly sales data for their region.

## How it works

By default, a delivery owner's user attributes are used when content is sent to email recipients. When personalization is enabled, Omni builds the content separately for each recipient, applying that recipient's user attribute values.

## Configuring personalization

Personalization is configured at two levels: an Organization Admin sets a **Delivery personalization** mode for the whole organization in **Settings > Content permissions**, and that mode determines whether delivery owners can make their own choice on individual deliveries.

### Defining personalization for the organization

Organization Admins can set the organization's **Delivery personalization** setting to one of the following options:

| Organization setting       | What delivery owners can do                                                                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configurable** (default) | Turn personalization on or off for each delivery, using the **Personalize delivery with the recipient's user attributes** checkbox in the delivery dialog. |
| **Always**                 | Nothing. Every email delivery is personalized. In place of the checkbox, the delivery dialog notes that deliveries are always personalized.                |
| **Never**                  | Nothing. Every email delivery uses the delivery owner's user attributes. The checkbox doesn't appear.                                                      |

See [Content permission settings](/administration/content-permissions#delivery-personalization) for details on the organization setting.

### Personalizing individual deliveries

<Tip>
  Enabling personalization doesn't impact *who* receives the delivery, only the delivery's *contents*. Make sure you add the right people to the delivery's recipients list!
</Tip>

When the [organization setting](#organization-setting) is **Configurable**, check the **Personalize delivery with the recipient's user attributes** option when you create or edit an email delivery to enable personalization.

If your organization has connections that use [per-user OAuth](/connect-data/oauth), the **Personalize delivery** option won't be available even if the organization setting is **Configurable**. In this case you'll see a notice instead of the checkbox, and all recipients will receive the same content based on the delivery owner's permissions.

Which attributes get applied to each copy of the delivery depends on how Omni matches a recipient's email address to a user account. See [Resolving delivery recipients by email](#resolve-recipients) for details.

## Resolving delivery recipients by email

When personalization is enabled, Omni uses each recipient's resolved user attributes to build the delivery's content. The resolved user depends on which type of account matches the recipient email.

Omni looks for a match in the following order, using the first match it finds:

<Steps>
  <Step title="Standard user, external user, embed SSO user, or pending invite with a matching account email">
    Omni looks at the following for an account email that matches the recipient email:

    * Standard users
    * External users
    * Embed SSO users
    * [Pending invitations](/administration/users/invite)
  </Step>

  <Step title="Embed user matched via the embed email URL parameter">
    If a match isn't found in step 1, Omni looks for an **embed user** associated with the recipient email through the [`email` URL parameter](/embed/setup/url-parameters/email). This is the typical case for non-SSO embed users whose work email is passed in at embed time.
  </Step>

  <Step title="Existing email-only user">
    If a match isn't found in step 2, Omni looks for an existing [**email-only user**](/administration/users/email-only) with that email.
  </Step>

  <Step title="New email-only user">
    If a match isn't found in step 3, Omni creates a new email-only user when the delivery is saved.

    <Tip>
      Make sure you define the user attributes for a new email-only user **before** the associated delivery runs. Otherwise, the user will inherit the default attribute value, which may return an error, no rows at all, or potentially unfiltered data. See [Email-only users](/administration/users/email-only#user-attributes) for more information.
    </Tip>
  </Step>
</Steps>

## Using personalization in embedded Omni

If you're using Omni in an [embedded context](/embed):

* Never mix internal (standard) and embed user emails. If you must reuse the same email, use the `+` modifier — for example, `blob@example.com` for the internal user and `blob+omniembed@example.com` for the embed user.
* Never reuse emails across `externalId`s for embed users.


# Whitelabeling sender addresses for email deliveries
Source: https://docs.omni.co/share/deliveries/email/whitelabel

Customize the sender name and address on delivery emails with a vanity domain.

<Note>
  Reach out to Omni support to have this feature enabled.
</Note>

By default, [delivery emails](/share/deliveries/email) are sent from an Omni email address. Omni's **Custom email sender** feature - also known as a vanity domain - allows you to customize delivery emails' sender information, such as the sender's name and email address. This is especially useful for instances where you need to whitelabel Omni emails, such as using Omni in an [embedded context](/embed).

## Requirements

**Organization Admin** permissions are required to configure email whitelabeling.

## Enabling email whitelabeling

To enable email whitelabeling:

<Steps>
  <Step>
    Click **Settings >Deliveries > Email tab**.
  </Step>

  <Step>
    Toggle **Custom email sender** to **On**.
  </Step>

  <Step>
    Fill in the **Sender Name** and **Sender Email** fields.
  </Step>
</Steps>

When finished, you can send a test (**Send test**) or **Save changes**.

## Disabling email whitelabeling

Disabling email whitelabeling reverts emails back to the default Omni domain, which may be visible to end users in embedded contexts.

<Steps>
  <Step>
    Click **Settings >Deliveries > Email tab**.
  </Step>

  <Step>
    Toggle **Custom email sender** to **Off**.
  </Step>

  <Step>
    When prompted, confirm the change.
  </Step>
</Steps>

## Next steps

* [Create an email delivery](/share/deliveries/email)
* [Restrict recipient email domains with an allowlist](/share/deliveries/email/domain-allowlist)
* [Embed Omni in your application](/embed)


# Delivering Omni content to Google Sheets
Source: https://docs.omni.co/share/deliveries/google-sheets

With Google Sheets deliveries, you can automatically schedule sending individual tiles to Google Sheets.

## Limitations

* Only single tile deliveries are supported
* Cannot be used with an [embedded Omni instance](/embed)

## Creating a Google Sheets delivery

<Note>
  To use Google Sheets as a destination, you'll need an existing Google Sheet workbook that you have write access to. **This sheet should be blank** as Omni includes column headers in the delivery.
</Note>

<Steps>
  <Step title="Configure the delivery settings">
    1. Navigate to a **published** dashboard.
    2. Click **File > Deliveries & Alerts**. The delivery options will display on the left side of the page.
    3. Fill in the following:

       * **Delivery** - Select **Schedule** or **Alert**.
       * **Send** -&#x20;
       * **Destination** - Select .
       * **Name** - Enter a name for the delivery.

    **If creating an alert**, use the **Alert** tab to define the conditions that must be met to trigger the delivery. For example, you have a chart that tracks the **Total sales** for your ecommerce company. Using an alert, you can trigger a delivery when the total of your sales has changed.
  </Step>

  <Step title="Configure the delivery schedule">
    In this step, you'll define the cadence for the delivery:

    * For **schedules**, this determines when Omni will deliver the specified content to the destination
    * For **alerts**, this tells Omni when to check if the current query results meet the conditions required to send the delivery

    Schedules can be defined using the visual options or with cron:

    <AccordionGroup>
      <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
        Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

        By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
      </Accordion>

      <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
        A cron expression is a string that describes the individual details of a schedule:

        | Order | Unit         | Allowed values  | Allowed special characters |
        | ----- | ------------ | --------------- | -------------------------- |
        | 1     | minute       | 0-59            | \* , - /                   |
        | 2     | hour         | 0-23            | \* , - /                   |
        | 3     | day of month | 1-31            | \* , - / L W ?             |
        | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
        | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
        | 6     | year         | any             | \* , - /                   |

        Using cron, you can create schedules like the following:

        ```markdown title="At 9:00 AM every day" theme={null}
        0 9 ? * * *
        ```

        ```markdown title="At 6:30AM on the last day of the month" theme={null}
        30 6 L * ? *
        ```

        ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
        45 8 ? * MON-FRI *
        ```

        Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

        <Tip>
          If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every weekday at 9am" or "first Monday of each month at noon."
        </Tip>
      </Accordion>
    </AccordionGroup>

    <Tip>
      Schedule send timezone may be different than query run timezone. For example, if your **Database timezone** is `UTC` with no other timezone conversion settings and you set your schedule to send at `12:00 PM PST`, the query will execute at `8:00 PM UTC`.

      Refer to your [connection timezone settings](/connect-data/timezones) for more information.
    </Tip>
  </Step>

  <Step title="Select format and filter options">
    The **Chart** tab allows you to specify format and filter options for the delivery:

    * **Apply data formatting** - Preserves number, date, currency, and other formatting in the delivery
    * **Exclude hidden columns**
    * **Send all possible results**, which will ignore any limits applied to the underlying query
    * **Set filter or control values for the delivery**. Some formats will have additional customization options. PDF formats, for example, will allow you to specify the orientation and page size for the PDF.

    <Tip>
      You can use filters to customize content for different recipients! For example, set a filter to `A` in a scheduled delivery to recipient A, and in another scheduled delivery to recipient B, set a filter to `B`.
    </Tip>
  </Step>

  <Step title="Connect your Google Drive account">
    <Note>
      This step is only required the first time a Google Sheets delivery is created in your Omni instance.
    </Note>

    1. Click the **Google Sheets** tab.
    2. Connect your Google Drive account. **Grant Omni all requested permissions or deliveries may not succeed.**

       When you connect your Google account, you grant Omni permission to deliver data to Sheets on your behalf. You will not see Omni listed as a collaborator in the Sheets share modal. To review or revoke this access, refer to [your Google account connections](https://myaccount.google.com/connections).
    3. Use the link in the **Spreadsheet** section to browse for and select the Google Sheet workbook to send the delivery to.
    4. In Omni, select a **Write mode** for the delivery:
       * **Overwrite the data on a sheet** - Data in the sheet is overwritten on each successful delivery, including column headers
       * **Create a new sheet for each delivery** - Creates a new sheet in the workbook for each successful delivery
       * **Append the data on a sheet** - On every successful delivery, new results are added to the specified sheet starting with the first empty row.

    <Note>
      Write mode options have a few considerations if you're working with pivoted data:

      * **If creating a new schedule** and Omni detects pivoted data in the query, the **Append** option will be unavailable
      * **If editing a schedule** and Omni detects that the query has changed to include pivoted data, it will change the write mode to **Overwrite**

      Refer to the [Delivering pivoted data section](#delivering-pivoted-data) for more information.
    </Note>

    5. Lastly, define the sheet name. The field that displays depends on the **Write mode** you selected:
       * **Overwrite or append** - Enter the name of the sheet Omni should write data to in the **Sheet name** field. If Omni can't find a sheet with this exact name, it will create a sheet.
       * **New sheet for each delivery** - Enter a prefix for the sheet name in the **New sheet name prefix** field. A Unix timestamp of the delivery time will be appended to create the full sheet name: `{prefix}_{unixtimestamp}`
  </Step>

  <Step title="Test the delivery">
    If you want to test the delivery before saving, click the **Test Now** button in the bottom left corner of the page. This will send the dashboard/chart to the destination using the current settings. For example, using **Test Now** would send the delivery to all **Recipients**.

    <Note>
      The **Test Now** button will be unavailable for alerts if the **Condition type** is `Results have changed` or `Results have stayed the same`. A workaround is to use the **Send Now** option to manually trigger the delivery, which is available once the delivery has been saved.

      Save the alert and then click the <Icon icon="ellipsis-vertical" type="solid" /> icon to display the **Send Now** option. This will initiate a check on the alert condition - if the condition isn't met, the delivery will show as successful but not send anything.
    </Note>
  </Step>

  <Step title="Save the delivery">
    When finished, click **Save** to create the delivery.
  </Step>
</Steps>

## Delivering pivoted data

If your query contains pivoted data, there are a few things to consider when configuring a delivery to Google Sheets.

In a typical table, column order doesn't usually have to be strictly maintained to retain the accuracy of the data. In pivoted data, however, the data's column structure is directly tied to the position of its pivot dimensions.

To ensure the data that Omni delivers is accurate, only the **Overwrite** and **Create new sheet** options are supported for delivering pivoted data:

* **If creating a new schedule** and Omni detects pivoted data in the query, the **Append** option will be unavailable
* **If editing a schedule** and Omni detects that the query has changed to include pivoted data, it will change the write mode to **Overwrite**


# Sharing content with schedules & alerts
Source: https://docs.omni.co/share/deliveries/index

Keep your team informed by automating the delivery of dashboards and tiles.

Omni offers two ways to automate sharing content, which can be delivered to platforms like Slack or webhooks:

* **Schedules**, which deliver content at specified frequencies
* **Alerts**, which deliver content only if specific conditions are met

Embedded Omni instances [also support this functionality](/embed/customization/deliveries).

<Tip>
  Check out our [Alerts for operational workflows](https://omni.co/blog/using-alerts-for-operational-workflows-in-omni) blog post to see how some Omni customers use alerts!
</Tip>

## Destinations

<Note>
  **A delivery can only have one destination.** To deliver to multiple destinations, you'll need to create a delivery for each destination. For example, to deliver a dashboard to email and Slack, you'll need to create two deliveries.
</Note>

A **destination** is the channel or service Omni will send deliveries to. Omni currently supports the following delivery destinations:

| Destination   | How it works                                                                                                                                                                                                                                       |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email         | Sends an email to one or more recipients. Recipients can be other users in your Omni organization or non-users, such as an external stakeholder. Supports customizing sender options, such as email domain. [Learn more](/share/deliveries/email). |
| Google Sheets | Delivers the contents of a single tile to an existing Google Sheets workbook. [Learn more](/share/deliveries/google-sheets).                                                                                                                       |
| Amazon S3     | Delivers content to an Amazon S3 bucket using cross-account IAM role assumption. AWS IAM setup is required prior to use. [Learn more](/share/deliveries/amazon-s3).                                                                                |
| SFTP          | Delivers content to an existing SFTP server. [Learn more](/share/deliveries/sftp).                                                                                                                                                                 |
| Slack         | Delivers content to individual Slack users, public channels, and private channels. Set up in Slack is required prior to use in Omni. [Learn more](/share/deliveries/slack).                                                                        |
| Webhook       | Sends a request to a webhook URL, such as a Zapier webhook. Recipients are determined by the webhook's configuration. [Learn more](/share/deliveries/webhooks).                                                                                    |

## Schedule delivery times

Schedules deliver content at specified times. Note that delivery times are approximate and will happen within 15 minutes of the specified time.

## Alert condition types

When you create an alert, you choose a small **Results to check** query. On each scheduled run, Omni runs that query and evaluates a condition against its results.

If the condition is met, the full delivery is sent. If not, the run is recorded as a successful "condition unmet" outcome and nothing is delivered.

You'll select one of the following condition types when configuring an alert:

| Condition type                   | Triggers the delivery when...                                         |
| -------------------------------- | --------------------------------------------------------------------- |
| **Results have changed**         | The **Results to check** query's results differ from the previous run |
| **Results have stayed the same** | The **Results to check** query's results match the previous run       |
| **No results are returned**      | No rows are returned                                                  |
| **Any results are returned**     | At least one row is returned                                          |

<Note>
  **First-run behavior for "Results have changed" and "Results have stayed the same":** On the very first run, there's no previous result to compare against, so the condition evaluates to false and no delivery is sent. The first run establishes a baseline; alerts can fire starting on the second run.
</Note>

## Delivery access

The ability to create deliveries can be controlled through instance and document-level settings:

* **Instance** - In **Settings > General > Content permissions**, Organization Admins can [select the default abilities for documents](/administration/content-permissions).
* **Document** - In a saved document that has a Dashboard, navigate from the Dashboard to **File > Document Settings** to [select the abilities other users can have when accessing the document](/share#controlling-document-interactivity).

**Note:** for external embed it's possible an environmental variable has been added to disable scheduling for embed users. If you have checked the Instance and Document level settings to ensure they allow Scheduled Deliveries and still do not see the option for embed users to access the Schedule settings panel please reach out to support.

## Data and permissions in deliveries

All queries in a delivery run using the **schedule creator's** identity and user attributes at the time the delivery runs. Every recipient receives the same content — the data the creator can access, shaped by the creator's [user attributes](/administration/users/attributes) and any [access filters](/modeling/develop/data-access-control) applied to their account at that time.

Email deliveries support a **Personalize delivery with the recipient's user attributes** option. When enabled, each recipient receives content filtered by their own user attributes at the time the delivery runs, instead of the creator's. For setup details, see [email delivery personalization](/share/deliveries/email#email-settings).

## Delivery cache

By default, deliveries skip existing cached results and run fresh queries so recipients see the latest data. Once a delivery's query completes, Omni creates or updates a cache entry from that run, which is why deliveries are useful for preemptively [warming the cache](/analyze-explore/performance/caching#cache-warming-preemptively-caching-data) for later interactive users.

### Use cached results if available

You can override the default and let a delivery return cached results instead of always querying the warehouse. On the delivery form's **Dashboard** tab (or **Chart** tab, for single-tile deliveries), enable **Use cached results if available**. When this option is on, the delivery follows the model's [cache policy](/modeling/models/cache-policies) — if a matching, non-expired cache entry exists, Omni returns it instead of running a fresh query.


# Delivering Omni content to an SFTP server
Source: https://docs.omni.co/share/deliveries/sftp

Omni supports delivery data through SFTP as a robust and secure method for transferring files.

<Steps>
  <Step title="Configure the delivery settings">
    1. Navigate to a **published** dashboard.
    2. Click **File > Deliveries & Alerts**. The delivery options will display on the left side of the page.
    3. Fill in the following:

       * **Delivery** - Select **Schedule** or **Alert**.
       * **Send** -&#x20;
       * **Destination** - Select .
       * **Name** - Enter a name for the delivery.

    **If creating an alert**, use the **Alert** tab to define the conditions that must be met to trigger the delivery. For example, you have a chart that tracks the **Total sales** for your ecommerce company. Using an alert, you can trigger a delivery when the total of your sales has changed.
  </Step>

  <Step title="Configure the delivery schedule">
    In this step, you'll define the cadence for the delivery:

    * For **schedules**, this determines when Omni will deliver the specified content to the destination
    * For **alerts**, this tells Omni when to check if the current query results meet the conditions required to send the delivery

    Schedules can be defined using the visual options or with cron:

    <AccordionGroup>
      <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
        Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

        By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
      </Accordion>

      <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
        A cron expression is a string that describes the individual details of a schedule:

        | Order | Unit         | Allowed values  | Allowed special characters |
        | ----- | ------------ | --------------- | -------------------------- |
        | 1     | minute       | 0-59            | \* , - /                   |
        | 2     | hour         | 0-23            | \* , - /                   |
        | 3     | day of month | 1-31            | \* , - / L W ?             |
        | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
        | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
        | 6     | year         | any             | \* , - /                   |

        Using cron, you can create schedules like the following:

        ```markdown title="At 9:00 AM every day" theme={null}
        0 9 ? * * *
        ```

        ```markdown title="At 6:30AM on the last day of the month" theme={null}
        30 6 L * ? *
        ```

        ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
        45 8 ? * MON-FRI *
        ```

        Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

        <Tip>
          If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every weekday at 9am" or "first Monday of each month at noon."
        </Tip>
      </Accordion>
    </AccordionGroup>

    <Tip>
      Schedule send timezone may be different than query run timezone. For example, if your **Database timezone** is `UTC` with no other timezone conversion settings and you set your schedule to send at `12:00 PM PST`, the query will execute at `8:00 PM UTC`.

      Refer to your [connection timezone settings](/connect-data/timezones) for more information.
    </Tip>
  </Step>

  <Step title="Select format and filter options">
    <Tip>
      You can use filters to customize content for different recipients! For example, set a filter to `A` in a scheduled delivery to recipient A, and in another scheduled delivery to recipient B, set a filter to `B`.
    </Tip>

    In the **Dashboard** or **Chart** tab, you can:

    * **Select the format of the content**, such as PNG, PDF, XLSX, or CSV.
    * **Lightly customize the contents and layout**, such as expanding tables to include up to 1,000 rows, hiding filter values, or arranging tiles in a single column.
    * **Select the page(s) to include in the dashboard delivery**. This is applicable only to [advanced layouts](/visualize-present/dashboards/advanced-layout) with multiple pages.

      **Note**: PNGs can only include one page. You'll need to create multiple deliveries to output a PNG for each page.
    * **Override the query timezone for the delivery** using the [timezone picker](/visualize-present/dashboards/timezone-override). The picker label changes based on whether **Personalize delivery with recipient user attributes** is enabled (**Recipient's timezone** when enabled, **Default timezone** when disabled).

      This setting affects the content of queries included in the delivery, not the timing of the delivery itself. Use the **Schedule** tab to define when content should be delivered.
    * **Set filter or control values for the delivery**. Some formats will have additional customization options. PDF formats, for example, will allow you to specify the orientation and page size for the PDF.

      For dashboard deliveries, the default filters and controls will automatically be applied upon creation. Subsequent default filter value updates will not change the filter values set for existing deliveries.
  </Step>

  <Step title="Configure SFTP settings">
    To finish setting up the delivery, click the **SFTP** tab and enter the following:

    * The **Address** of your SFTP server in the format `sftp://hostname/optional/path` — for example, `sftp://ftp.example.com/incoming/`. The address must start with `sftp://`. Do not include the port or username in the address; enter those in the **Port** and **Username** fields below.
    * The **Port** of your SFTP server
    * The **File name** you want the delivery to have, without an extension. [Mustache references](/share/deliveries/dynamic-content) are supported.
    * An SFTP user's **Username** and **Password**. Omni will automatically encrypt the password after the delivery is saved.
  </Step>

  <Step title="Test the delivery">
    If you want to test the delivery before saving, click the **Test Now** button in the bottom left corner of the page. This will send the dashboard/chart to the destination using the current settings. For example, using **Test Now** would send the delivery to all **Recipients**.

    <Note>
      The **Test Now** button will be unavailable for alerts if the **Condition type** is `Results have changed` or `Results have stayed the same`. A workaround is to use the **Send Now** option to manually trigger the delivery, which is available once the delivery has been saved.

      Save the alert and then click the <Icon icon="ellipsis-vertical" type="solid" /> icon to display the **Send Now** option. This will initiate a check on the alert condition - if the condition isn't met, the delivery will show as successful but not send anything.
    </Note>
  </Step>

  <Step title="Save the delivery">
    When finished, click **Save** to create the delivery.
  </Step>
</Steps>


# Delivering Omni content to Slack
Source: https://docs.omni.co/share/deliveries/slack

With Slack deliveries, you can automatically schedule sending dashboards and individual tiles to your team as channel or direct messages.

<Tip>
  Looking to ask data questions interactively in Slack? See [Omni Slack Agent](/integrations/omni-slack-agent).
</Tip>

## Requirements

To connect Slack to Omni, you'll need [**Organization Admin** permissions](/administration/users/permissions).

## Common questions

<AccordionGroup>
  <Accordion title="What permissions does Omni need?">
    Omni is installed as a single Slack app, so deliveries use the same OAuth scopes as the rest of the integration. Some scopes are optional and can be deselected by your Slack workspace admin at Slack's authorization screen — `channels:join`, `files:read`, and `files:write` are the ones that most affect deliveries.

    For the full list of scopes, what they're used for, and the impact of opting out, see [Slack permissions](/integrations/omni-slack-agent#optional-scopes).

    <Note>
      **Removing a scope after install requires a Slack admin to uninstall and reinstall the Omni Slack app.** Slack OAuth scopes are additive within a single installation, so a previously granted scope can't be dropped any other way. Follow the [Changing scopes after install](/integrations/omni-slack-agent#changing-scopes-after-install) procedure — it preserves your scheduled deliveries. **Do not** click **Disconnect** in Omni for this purpose, as it deletes all scheduled Slack deliveries.
    </Note>
  </Accordion>

  <Accordion title="Who can be the recipient of a Slack delivery?">
    Omni's Slack integration supports sending deliveries to channels (public and private) and individual users via a direct message (DM).

    Slackbot cannot receive Omni Slack deliveries.
  </Accordion>

  <Accordion title="Can I create dynamic content in Slack deliveries?">
    Yes! See the [Dynamic content deliveries with Mustache guide](/share/deliveries/dynamic-content) for more information.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Connect your Slack workspace">
    Before Omni can send deliveries to Slack, you'll need to connect your Slack workspace. This is done on the **Integrations** page:

    1. In Omni, click **Settings > Integrations**.
    2. Click **Connect to Slack** and complete the Slack authorization flow.

    You'll be redirected back to Omni once the connection is established. For more details, refer to the [Omni Slack Agent setup guide](/integrations/omni-slack-agent#setting-up-the-omni-slack-agent).
  </Step>

  <Step title="Configure delivery settings">
    1. Navigate to a **published** dashboard.
    2. Click **File > Deliveries & Alerts**. The delivery options will display on the left side of the page.
    3. Fill in the following:

       * **Delivery** - Select **Schedule** or **Alert**.
       * **Send** -&#x20;
       * **Destination** - Select .
       * **Name** - Enter a name for the delivery.

    **If creating an alert**, use the **Alert** tab to define the conditions that must be met to trigger the delivery. For example, you have a chart that tracks the **Total sales** for your ecommerce company. Using an alert, you can trigger a delivery when the total of your sales has changed.
  </Step>

  <Step title="Configure the delivery schedule">
    In this step, you'll define the cadence for the delivery:

    * For **schedules**, this determines when Omni will deliver the specified content to the destination
    * For **alerts**, this tells Omni when to check if the current query results meet the conditions required to send the delivery

    Schedules can be defined using the visual options or with cron:

    <AccordionGroup>
      <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
        Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

        By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
      </Accordion>

      <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
        A cron expression is a string that describes the individual details of a schedule:

        | Order | Unit         | Allowed values  | Allowed special characters |
        | ----- | ------------ | --------------- | -------------------------- |
        | 1     | minute       | 0-59            | \* , - /                   |
        | 2     | hour         | 0-23            | \* , - /                   |
        | 3     | day of month | 1-31            | \* , - / L W ?             |
        | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
        | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
        | 6     | year         | any             | \* , - /                   |

        Using cron, you can create schedules like the following:

        ```markdown title="At 9:00 AM every day" theme={null}
        0 9 ? * * *
        ```

        ```markdown title="At 6:30AM on the last day of the month" theme={null}
        30 6 L * ? *
        ```

        ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
        45 8 ? * MON-FRI *
        ```

        Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

        <Tip>
          If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every weekday at 9am" or "first Monday of each month at noon."
        </Tip>
      </Accordion>
    </AccordionGroup>

    <Tip>
      Schedule send timezone may be different than query run timezone. For example, if your **Database timezone** is `UTC` with no other timezone conversion settings and you set your schedule to send at `12:00 PM PST`, the query will execute at `8:00 PM UTC`.

      Refer to your [connection timezone settings](/connect-data/timezones) for more information.
    </Tip>
  </Step>

  <Step title="Select format and filter options">
    <Tip>
      You can use filters to customize content for different recipients! For example, set a filter to `A` in a scheduled delivery to recipient A, and in another scheduled delivery to recipient B, set a filter to `B`.
    </Tip>

    In the **Dashboard** or **Chart** tab, you can:

    * **Select the format of the content**, such as PNG, PDF, XLSX, or CSV.
    * **Lightly customize the contents and layout**, such as expanding tables to include up to 1,000 rows, hiding filter values, or arranging tiles in a single column.
    * **Select the page(s) to include in the dashboard delivery**. This is applicable only to [advanced layouts](/visualize-present/dashboards/advanced-layout) with multiple pages.

      **Note**: PNGs can only include one page. You'll need to create multiple deliveries to output a PNG for each page.
    * **Override the query timezone for the delivery** using the [timezone picker](/visualize-present/dashboards/timezone-override). The picker label changes based on whether **Personalize delivery with recipient user attributes** is enabled (**Recipient's timezone** when enabled, **Default timezone** when disabled).

      This setting affects the content of queries included in the delivery, not the timing of the delivery itself. Use the **Schedule** tab to define when content should be delivered.
    * **Set filter or control values for the delivery**. Some formats will have additional customization options. PDF formats, for example, will allow you to specify the orientation and page size for the PDF.

      For dashboard deliveries, the default filters and controls will automatically be applied upon creation. Subsequent default filter value updates will not change the filter values set for existing deliveries.

    <Note>
      If your organization's Slack app doesn't have [`files:write` permissions](/integrations/omni-slack-agent#optional-scopes), Omni will send file-based deliveries (e.g., PNG) as a secure link instead of a file attachment. The link expires after 7 days. Deliveries using **Link back to dashboard** are unaffected.
    </Note>
  </Step>

  <Step title="Select a channel and add a message">
    The last step is to configure the Slack settings for the delivery:

    1. **Select a channel or direct message**. Public and private channels are supported.

       **To deliver content to a private channel**, you'll also need to add the Omni app (`@omni`) to the private channel.

       If you don't see the private channel in the **Channel** dropdown, click the **Add channel** link. Use the modal to enter the ID of the channel.
    2. **Add a message**. Messages can include [Mustache references](/share/deliveries/dynamic-content) for dynamic, personalized content and be formatted using [Slack markup](https://api.slack.com/reference/surfaces/formatting#basic-formatting).
  </Step>

  <Step title="Test the delivery">
    If you want to test the delivery before saving, click the **Test Now** button in the bottom left corner of the page. This will send the dashboard/chart to the destination using the current settings. For example, using **Test Now** would send the delivery to all **Recipients**.

    <Note>
      The **Test Now** button will be unavailable for alerts if the **Condition type** is `Results have changed` or `Results have stayed the same`. A workaround is to use the **Send Now** option to manually trigger the delivery, which is available once the delivery has been saved.

      Save the alert and then click the <Icon icon="ellipsis-vertical" type="solid" /> icon to display the **Send Now** option. This will initiate a check on the alert condition - if the condition isn't met, the delivery will show as successful but not send anything.
    </Note>
  </Step>

  <Step title="Save the delivery">
    When finished, click **Save** to create the delivery.
  </Step>
</Steps>

## Viewing all Slack deliveries

<Note>
  Viewing Slack deliveries requires [**Organization Admin** permissions](/administration/users/permissions).
</Note>

Looking to see all of your Slack deliveries in one place?

1. In Omni, click **Settings > Deliveries**.
2. Click the **Slack tab**.
3. Click the link under **Connected to Omni**. You'll be redirected to a filtered view of the **All Deliveries** tab, which will display all the deliveries currently sent to Slack.


# Troubleshooting failed deliveries
Source: https://docs.omni.co/share/deliveries/troubleshooting

Monitor the status of the deliveries in your instance and learn how to investigate failures.

You can monitor the status of the deliveries in your Omni instance - and view detailed information in the event of a failure - in the **Settings > Deliveries** page:

<img alt="" />

## Failed delivery notifications

When a delivery fails, it will be marked as **Failed** in the **Deliveries** page. Additionally, the **creator of the delivery** will receive an email notification about the failure.

## Retrying failed deliveries

Omni attempts each scheduled delivery once per occurrence and does not automatically retry a failed delivery. Omni will automatically attempt the next scheduled delivery at its normal interval.

## External destinations

Scheduled deliveries and alerts in Omni depend on both Omni’s internal scheduling service and, in some cases, external systems such as connected APIs, CRMs, or email endpoints.

When a delivery to an external destination fails, start by following these steps:

1. Verify that the external credentials, tokens, or permissions are valid
2. Check that the external system is reachable and not under maintenance
3. After verifying your credentials and the system's status, manually retry the delivery from the **Deliveries** page in Omni

If the issue persists, contact [Omni support](#contacting-support).

### Email domain restrictions

If an email delivery fails or is blocked, the recipient's email domain may not be included in your organization's domain allowlist. When a domain allowlist is configured, Omni only sends deliveries to recipients whose email addresses match one of the allowed domains.

To resolve this issue:

1. Check if domain restrictions are in place by navigating to **Settings > Deliveries > Email tab > Domain allowlist**
2. Either add the recipient's domain to the allowlist (up to 1,000 domains can be configured), or click **Clear allowlist** to remove all domain restrictions

See [Restricting recipient email domains with allowlist](/share/deliveries/email/domain-allowlist) for more information.

### SFTP address errors

If a delivery to an SFTP server fails with an **Invalid SFTP address** error, verify the following:

* The address starts with `sftp://` — for example, `sftp://ftp.example.com/incoming/`
* The port is entered in the **Port** field, not embedded in the address (for example, `sftp://host:8022/path` is invalid)
* The username is entered in the **Username** field, not embedded in the address (for example, `sftp://user@host/path` is invalid)

See [Delivering Omni content to an SFTP server](/share/deliveries/sftp#sftp-settings) for the full configuration reference.

## Contacting support

When contacting Omni support, include the following:

* The delivery ID
* The timestamp of the delivery

You can retrieve this information from the **Settings > Deliveries** page in Omni.


# Webhook deliveries
Source: https://docs.omni.co/share/deliveries/webhooks

Customize your Omni deliveries with webhooks.

If you want to customize your Omni deliveries, webhooks may be a good fit. While you can specify some things - like the email sender for email deliveries or the channel message for Slack deliveries - webhooks give you the ability to create context-specific workflows.

For example, you could use a platform like [Zapier](https://www.zapier.com) to catch Omni webhooks and perform different actions based on data values, such as those for CSV-formatted deliveries.

## Requirements

To successfully use Omni webhook deliveries, your webhook must return an HTTP `200` status response upon delivery. A different status could cause delivery retries or failures.

## Creating a webhook delivery

<Steps>
  <Step title="Create a webhook URL">
    Prior to using webhooks as a delivery destination, you'll need to create a webhook URL for Omni to send requests to. For example, using Zapier's webhook trigger in a Zap will create a webhook URL for you to use.

    <Note>
      If access to your webhook server is restricted, you'll need to whitelist Omni's IP addresses to ensure deliveries are successful.

      Omni's IP addresses can be found on any database connection's page, accessed by navigating to **Settings > Connections** and clicking a connection. **All IP addresses on this page must be included in the allowlist.**
    </Note>
  </Step>

  <Step title="Configure the delivery settings">
    1. Navigate to a **published** dashboard.
    2. Click **File > Deliveries & Alerts**. The delivery options will display on the left side of the page.
    3. Fill in the following:

       * **Delivery** - Select **Schedule** or **Alert**.
       * **Send** -&#x20;
       * **Destination** - Select .
       * **Name** - Enter a name for the delivery.

    **If creating an alert**, use the **Alert** tab to define the conditions that must be met to trigger the delivery. For example, you have a chart that tracks the **Total sales** for your ecommerce company. Using an alert, you can trigger a delivery when the total of your sales has changed.
  </Step>

  <Step title="Configure the delivery schedule">
    In this step, you'll define the cadence for the delivery:

    * For **schedules**, this determines when Omni will deliver the specified content to the destination
    * For **alerts**, this tells Omni when to check if the current query results meet the conditions required to send the delivery

    Schedules can be defined using the visual options or with cron:

    <AccordionGroup>
      <Accordion title="Visual schedule builder" icon="calendar" description="Easy point-and-click schedule builder">
        Use the UI options (**Daily**, **Weekly**, etc.) to select a time period.

        By default, schedules are set to send in the local timezone of the delivery creator's computer. Use the **Times are in** drop down to change the timezone.
      </Accordion>

      <Accordion title="Custom cron schedule (Advanced)" icon="asterisk" description="Code-based granular timing control">
        A cron expression is a string that describes the individual details of a schedule:

        | Order | Unit         | Allowed values  | Allowed special characters |
        | ----- | ------------ | --------------- | -------------------------- |
        | 1     | minute       | 0-59            | \* , - /                   |
        | 2     | hour         | 0-23            | \* , - /                   |
        | 3     | day of month | 1-31            | \* , - / L W ?             |
        | 4     | month        | 1-12 or JAN-DEC | \* , - /                   |
        | 5     | day of week  | 1-7 or SUN-SAT  | \* , - / L W ?             |
        | 6     | year         | any             | \* , - /                   |

        Using cron, you can create schedules like the following:

        ```markdown title="At 9:00 AM every day" theme={null}
        0 9 ? * * *
        ```

        ```markdown title="At 6:30AM on the last day of the month" theme={null}
        30 6 L * ? *
        ```

        ```markdown title="At 8:45 AM every day, Monday through Friday" theme={null}
        45 8 ? * MON-FRI *
        ```

        Omni uses Amazon Web Services' (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information. By default, the most frequent you can configure a schedule is hourly.

        <Tip>
          If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every weekday at 9am" or "first Monday of each month at noon."
        </Tip>
      </Accordion>
    </AccordionGroup>

    <Tip>
      Schedule send timezone may be different than query run timezone. For example, if your **Database timezone** is `UTC` with no other timezone conversion settings and you set your schedule to send at `12:00 PM PST`, the query will execute at `8:00 PM UTC`.

      Refer to your [connection timezone settings](/connect-data/timezones) for more information.
    </Tip>
  </Step>

  <Step title="Select format and filter options">
    <Tip>
      You can use filters to customize content for different recipients! For example, set a filter to `A` in a scheduled delivery to recipient A, and in another scheduled delivery to recipient B, set a filter to `B`.
    </Tip>

    In the **Dashboard** or **Chart** tab, you can:

    * **Select the format of the content**, such as PNG, PDF, XLSX, or CSV.
    * **Lightly customize the contents and layout**, such as expanding tables to include up to 1,000 rows, hiding filter values, or arranging tiles in a single column.
    * **Select the page(s) to include in the dashboard delivery**. This is applicable only to [advanced layouts](/visualize-present/dashboards/advanced-layout) with multiple pages.

      **Note**: PNGs can only include one page. You'll need to create multiple deliveries to output a PNG for each page.
    * **Override the query timezone for the delivery** using the [timezone picker](/visualize-present/dashboards/timezone-override). The picker label changes based on whether **Personalize delivery with recipient user attributes** is enabled (**Recipient's timezone** when enabled, **Default timezone** when disabled).

      This setting affects the content of queries included in the delivery, not the timing of the delivery itself. Use the **Schedule** tab to define when content should be delivered.
    * **Set filter or control values for the delivery**. Some formats will have additional customization options. PDF formats, for example, will allow you to specify the orientation and page size for the PDF.

      For dashboard deliveries, the default filters and controls will automatically be applied upon creation. Subsequent default filter value updates will not change the filter values set for existing deliveries.
  </Step>

  <Step title="Configure webhook settings">
    The last step is to configure the webhook settings. Click the **Webhook** tab and fill in the following:

    * **URL** - Enter the webhook URL you created in [step 1 of this guide](/share/deliveries/webhooks#webhook-url).
    * **File Name (Without extension)** - Optionally specify a file name for the delivery, leaving out a file extension like `.png`. [Mustache references](/share/deliveries/dynamic-content) are supported.
  </Step>

  <Step title="Test the delivery">
    If you want to test the delivery before saving, click the **Test Now** button in the bottom left corner of the page. This will send the dashboard/chart to the destination using the current settings. For example, using **Test Now** would send the delivery to all **Recipients**.

    <Note>
      The **Test Now** button will be unavailable for alerts if the **Condition type** is `Results have changed` or `Results have stayed the same`. A workaround is to use the **Send Now** option to manually trigger the delivery, which is available once the delivery has been saved.

      Save the alert and then click the <Icon icon="ellipsis-vertical" type="solid" /> icon to display the **Send Now** option. This will initiate a check on the alert condition - if the condition isn't met, the delivery will show as successful but not send anything.
    </Note>
  </Step>

  <Step title="Save the delivery">
    When finished, click **Save** to create the delivery.
  </Step>
</Steps>

## Request formats

The type of delivery Omni sends determines the format the request body will take:

### Link-only

Omni will send a `POST` request with a JSON object in the body that contains:

```json title="Webhook delivery request body" theme={null}
{
  "url": "<dashboard_url>"
}
```

### All file formats

Omni will send a `POST` request with the file content directly in the body using streaming delivery:

* **Headers**:
  * `Content-Type` - Appropriate MIME type (`text/csv`, `application/json`, `application/pdf`, `image/png`, etc.)
  * `Content-Length` - Size of the file in bytes (when available)
  * `X-Filename` - Original filename for reference
* **Body**: Raw file content streamed directly

<Note>
  For dashboard deliveries with multiple queries, CSV content will be delivered as a ZIP file with `Content-Type: application/zip`.
</Note>


# Content sharing
Source: https://docs.omni.co/share/index

Share Omni dashboards and workbooks with your team using links, folder permissions, and access controls for governed collaboration.

Sharing content with your team makes it easier to collaborate, improves decision-making across teams, and keeps everyone on the same page. It also saves time by ensuring stakeholders have access to key insights without constantly recreating or requesting the same reports.

**Note**: Publishing a document using the draft/publish workflow doesn't inherently grant document access. The document's folder location and document-level permissions determine who can access it. Refer to the [Editing & publishing guide](/content/develop) for more information.

## Content access permissions

Content access is determined by a user's assigned content access role. Roles can be assigned at the content level, but **Organization Admins** can also assign default content access roles for the entire [organization](#organization).

### Document permissions

Users can be assigned the following roles on individual documents.

<Note>
  The **Owner** role can only be granted to individual users. It cannot be granted to user groups or used as the organization default. Documents can have more than one owner, but at least one owner is required at all times.
</Note>

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Ability</th>
      <th>No Access</th>
      <th>Viewer</th>
      <th>Editor</th>
      <th>Manager</th>
      <th>Owner</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>View dashboards</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>View & explore workbooks</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Update dashboards & workbooks</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Delete folders they created</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Manage permissions on content</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Receive access requests</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>
  </tbody>
</table>

### Folder permissions

Content access roles on folders work differently than on individual documents. When you share a folder, permissions cascade to all documents and subfolders inside. Additionally, folder-level roles grant the ability to add and remove content from the folder, not just view or edit individual documents.

<Note>
  The **Owner** role can only be granted to individual users. It cannot be granted to user groups or used as the organization default. Folders can have more than one owner, but at least one owner is required at all times.
</Note>

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Ability</th>
      <th>No Access</th>
      <th>Viewer</th>
      <th>Editor</th>
      <th>Manager</th>
      <th>Owner</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Search for the folder & its contents</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>View folder contents</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>View dashboards & explore workbooks</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Edit content in the folder</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Add new content to the folder</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Delete folder content</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Manage folder and content permissions</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>

    <tr>
      <td>Receive access requests</td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <XCircleIcon />
      </td>

      <td>
        <CheckIcon />
      </td>
    </tr>
  </tbody>
</table>

Generally, it's considered best practice to assign the least permissive role that satisfies a user's needs. Refer to the [permissions scenarios](/administration/users/permissions-scenarios) for more information and examples of different permissioning implementations.

## Assigning access roles to content

To grant content access, start by clicking the **Share** icon near the top right corner of any folder or document:

<img alt="" />

### Users and user groups

To share content with individual users and [user groups](/administration/users/groups):

1. Click the **Share with users or groups** field.
2. Use the dropdown to select the users and groups you want to share the content with.
3. Use the access role dropdown (next to the **Share** button) to assign the user or group an access role.
4. Click **Share**.

### Organization

Use the access role dropdown in the **Organization** row to share the content with your entire organization. This role will be applied to users when they access the content unless they have explicitly been assigned a different role. Changes will be saved automatically.

The access role you select applies to personal content you share from **My Documents** or content you move to your organization's **Shared** hub. When you grant an organization role to personal content, it is shared organization-wide while remaining in your **My Documents** folder. As the owner, you retain archive and restore rights on the content even after it has been shared with the organization.

<img alt="" />

<Check>
  A few settings can affect how you share content with your organization:

  * **Content organization** - When enabled, users can add content to the organization's **Shared** hub. Otherwise, users can only add content to folders that they have been granted access to.
  * **Default content access role** - Applies the selected role as the organization default when content is saved in the organization's **Shared** hub.

  For more information about these settings, refer to the [Organization settings reference](/administration/settings).
</Check>

### Managing ownership

The **Owner** content role grants the user full content management permissions to the content; they will also receive [access requests](#requesting-document-access).

Documents and folders can have multiple owners, but a piece of content must have at least one owner at all times. In this case, a new owner must be assigned before you can change the current owner's content role or remove their access entirely.

<Frame>
  <img alt="Disabled Remove access and content role options in the access role dropdown with a tooltip reading 'Personal space owner', showing the user's access can't be changed as they are the only owner" />
</Frame>

## Inheriting access roles

<Note>
  When users create subfolders within existing parent folders, the creator of the original parent folder maintains [ownership](#ownership) of the newly created subfolders. However, users who create the subfolders retain full ownership rights over any documents they place within the subfolders they created.
</Note>

The contents of a folder will inherit the [access role](#content-access-permissions) of the parent folder. Documents and subfolders may be assigned more permissive roles than the parent folder, but they can't have a less permissive role.

For example, `Folder 1` requires an **Editor** access role or higher:

<Tree>
  <Tree.Folder name="Folder 1 - Editor or higher">
    <Tree.File name="Document A -  Editor or Manager" />

    <Tree.Folder name="Subfolder 1 -  Editor or Manager">
      <Tree.File name="Document B - Inherits from Subfolder 1" />

      <Tree.Folder name="Subfolder 2 - Inherits from Subfolder 1" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

Since **Editor** access has been applied to `Folder 1`, this means that any documents or subfolders it contains can only be assigned **Editor** or **Manager** access roles.

Let's take a look at an example where `Folder 1` is assigned **No access**. With this implementation, the documents and subfolders it contains can be assigned any more permissive access role:

<Tree>
  <Tree.Folder name="Folder 1 - No access">
    <Tree.File name="Document A -  Viewer or higher" />

    <Tree.Folder name="Subfolder 1 -  Viewer or higher">
      <Tree.File name="Document B - Inherits from Subfolder 1" />

      <Tree.Folder name="Subfolder 2 - Inherits from Subfolder 1" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

This approach allows for more granular access control as permission levels can be **increased** for nested content, but they can't be decreased. In this last example, the content with the most permissions (**Manager**) is the most deeply nested:

<Tree>
  <Tree.Folder name="Folder 1 - No access">
    <Tree.File name="Document A -  Viewer or higher" />

    <Tree.Folder name="Subfolder 1 -  No access">
      <Tree.File name="Document B - Editor or higher" />

      <Tree.Folder name="Subfolder 2 - Manager" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

### What can users see?

When organizing content and assigning access, assume that folder names will always be visible. If a folder contains content that a user has access to, the user will be able to see the folder. The user will only be able to see the content they have access to within the folder, however.

For example, `Folder 1` has a **No access** role, but it contains a document that the entire organization has access to. Users will be able to see the folder and the document.

## Requesting document access

Users can request access to dashboards and the document owner will receive an email notification to approve or review the request.

<Frame>
  <img alt="" />
</Frame>

The owner and any document managers can see and approve or deny outstanding requests from the document's **Share** dialog:

<Frame>
  <img alt="" />
</Frame>

<Note>
  Keep the following in mind when using this feature:

  * AccessBoost cannot be requested, only standard Viewer/Editor/Manager content roles. Model level roles still dictate what level of content access a user can have.
  * Users must be Restricted Querier or higher to request Editor or Manager access to a document.
  * Not available in embed
</Note>

## Controlling document interactivity

<Note>
  A **Manager** or higher content role is required to access document settings.
</Note>

You can also choose what users who access your content can do by enabling or disabling different abilities, like scheduling and duplication. You can access these settings by:

* Clicking **Settings** in the **Share** modal, or
* Clicking **File > Document Settings** in a dashboard or workbook

Admins can control the available abilities for all documents in the organization using the [**Document abilities setting**](/administration/content-permissions). If an ability isn't available in a document, it may be disabled at the organization level.

## Changing document URLs and identifiers

Changing a document's identifier can make its URL more readable and easier to remember. This could also be used for updates to an embedded dashboard without requiring an engineer to point from one identifier to another by instead pointing to a fixed, immutable URL.

You can access this setting by:

* Clicking **Settings** in the **Share** modal, or
* Clicking **File > Document Settings** in a dashboard or workbook

The document's identifier must be unique. Additionally, note that changes will be reflected in real time.

## Boosting permissions with AccessBoost

<Note>
  Admin permissions are required to enable AccessBoost unless the [**Non-administrators can enable AccessBoost on content** setting](/administration/content-permissions#accessboost) in **Admin > Content permissions** is enabled.
</Note>

AccessBoost allows content managers to enable permission boosting by ignoring an Omni user's [database connection role](/administration/users/permissions). When enabled, the user can run a dashboard or app and view all of the data that content shows even if they typically wouldn't be able to see content built using SQL. AccessBoost only alters the access to the data on dashboards and apps. AccessBoost still respects a user's connection role when the user runs a query at the workbook level.

AccessBoost may be useful in scenarios where users with connection roles of **Querier**, **Modeler**, and **Admins** that want to share dashboard or app content with users that have lower level connection roles like **Restricted Querier** and **Viewer**.

AccessBoost does not allow users with a connection role of **No Access** to access a document on that connection.

**Note that AccessBoost does not**:

* [**Allow users to bypass `access_filters`**](/modeling/develop/data-access-control)
* [**Automatically bypass in-use `access_grants`**](/modeling/models/access-grants). If you want to bypass checks for content built on topics or views using the access grant, add an `access_boostable: true` property to the grant.
* **Alter access to data when running queries in workbooks**. Only data access on dashboards and apps is affected.

### AccessBoost in embedded Omni

Enabling AccessBoost for the **Organization** role also applies on content that is [embedded externally](/embed), which can pose security implications to consider. Typically, for embedded content Omni applies the **Viewer** connection role - which would **only** allow users to see content that is tied to [modeled topics](/modeling/topics); limiting data that is exposed to external customers.

This means that embed users can view SQL content and content not built on topics. However, this also means that you could inadvertently expose data to embed users that you don't want them to see.

Embed users can provision AccessBoost when both **AccessBoost** and **Non-administrators can enable AccessBoost on content** are enabled in **Settings > Content permissions**.

### Enabling AccessBoost

AccessBoost is enabled using the [**AccessBoost setting**](/administration/content-permissions) in **Settings > Content Permissions > AccessBoost**.

When enabled at the organization level, you can set AccessBoost:

* For your organization's [**Default access role**](/administration/content-permissions) in **Settings > Content Permissions > Default Content Access**
* At the content level, in the document or folder's **Share** modal

### Examples

| Level        | Description                                                                                                                                                              | Enabled                                                                                                                                                                                                                                                                                                                               | Disabled                                                                                                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization | An admin user can enable or disable AccessBoost at the organization level in the Admin settings under Administration > Content Permissions                               | Allows users who manage content to enable AccessBoost at the folder and document levels                                                                                                                                                                                                                                               | Prevents any users who manage content from enabling AccessBoost on the folder or document levels                                                                                                            |
| Folder       | Once an admin user has enabled AccessBoost in the Admin settings for Content Permissions the content manager users can choose to enable AccessBoost at the folder level. | Allows users with access to a folder to open any dashboards or apps in that folder, view the content of those dashboards or apps even if the user's connection role would prevent them from viewing that content. i.e. a dashboard or app built with SQL requires the user opening it to have a connection role of Querier or higher. | A user must have a viewer connection role or higher for content built off of modeled topics. Any content built with SQL requires users to have a connection role of Querier or higher.                      |
| Document     | A user managing their content can choose to enable AccessBoost at the document level                                                                                     | Allows users with access to the document to open and view the dashboard or app, but not workbook view, for a document even if the user's connection role would prevent them from viewing that content. i.e. a dashboard or app built with SQL requires the user opening it to have a connection role of Querier or higher.            | Without AccessBoost, a user must have a viewer connection role or higher for content built off of modeled topics. Any content built with SQL requires users to have a connection role of Querier or higher. |

## Sharing content externally

Omni has robust sharing functionality through [Delivery](/share) and [Embedding](/embed) which allows users and organizations to securely share the data in a variety of forms.

### Customizing embedded content

The **Embed** tab in a document's **Share** dialog has several options to customize what content is embedded and how it displays to users:

<img alt="Embed tab in the Dashboard share modal" />

* **Content** - Embed the document's **Workbook**, **Dashboard**, or **App**, if applicable
* **Appearance settings** - Define how the embedded content will display, including **Light/dark** mode and Omni **Theme**
* **Include current filters in embed** - If enabled, currently-applied filters will be included in the embedded content
* **Allow copy to clipboard for embedded content** - If enabled, users will be able to copy values to their clipboard from the embedded content. The generated iframe code will include a `allow="clipboard-write"`.

## Access warnings

Access warnings will appear as a yellow asterisk (`*`) on dashboards and as an **Access Warnings** button in draft [apps](/visualize-present/apps) when a tile contains content that Viewers or Restricted Queriers won't be able to see. These warnings are visible only to document editors — users with a Viewer or Restricted Querier connection role will simply see a blank tile.

<img alt="" />

Viewers and Restricted Queriers can only run topic-based queries. Any tile that uses raw SQL, references fields outside a topic, or is in a workbook that modifies security-relevant model properties will produce a warning. If a tile depends on another restricted tile, it is also flagged.

### Warning reasons

#### Query-structural issues

These warnings mean the tile itself is built in a way that Viewers and Restricted Queriers cannot run.

| Reason                   | What it means                                                                            | Fix                                                                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Raw SQL                  | The tile uses a hand-written SQL query instead of a modeled topic query.                 | Rebuild the tile using a topic, or save the SQL as a [query view](/analyze-explore/saved-views) and include it in a topic. |
| No topic selected        | The query has no topic associated with it.                                               | Assign a topic to the query.                                                                                               |
| Fields outside the topic | The query includes fields from views that aren't part of the selected topic.             | Remove those fields or switch to a topic that includes them.                                                               |
| Topic not found          | The topic this tile was built on no longer exists — it may have been renamed or deleted. | Reassign the tile to a valid topic.                                                                                        |
| Invalid model            | The model or branch referenced by the query can't be resolved.                           | This usually indicates a stale query; re-open the tile and re-save.                                                        |

#### Access grant issues

These warnings mean the topic or field requires an [access grant](/modeling/models/access-grants) and either the grant itself or the user's attributes are the problem. The three reasons have different fixes:

| Reason                    | What it means                                                                                                   | Fix                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Grant not defined         | A topic or field references an access grant name that doesn't exist in the model's `access_grants:` block.      | Define the missing grant in the model, or remove the `required_access_grants` reference.                     |
| User lacks the grant      | The user's [attributes](/administration/users/attributes) don't satisfy the grant's `allowed_values` condition. | Update the user's attributes, or adjust the grant's `allowed_values`.                                        |
| Grant definitions changed | The workbook modifies which access grants are required on a view or topic.                                      | Move the grant change to the shared model, or restructure the workbook to avoid modifying grant definitions. |

#### Workbook model changes

These warnings mean the workbook itself contains model-layer modifications that Viewers and Restricted Queriers aren't permitted to be exposed to. The fix is to move the relevant model change to the shared model, or restructure the workbook to remove it.

| Reason                         | What the workbook changed                                                                                                                |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Custom topic definitions       | Defines topics beyond what's permitted (only AI-generated or simple upload topics are allowed in shared workbooks for restricted users). |
| Relationship changes           | Adds join relationships that aren't rooted in the shared model.                                                                          |
| Default access filters         | Sets `default_topic_access_filters` at the model level.                                                                                  |
| Default required access grants | Sets `default_topic_required_access_grants` at the model level.                                                                          |
| Model extends                  | Uses `extends:` to pull in another shared model.                                                                                         |
| Dynamic shared extensions      | Defines `dynamicSharedExtensions` (user-attribute-driven model layers).                                                                  |
| Field sets                     | Defines or removes field sets.                                                                                                           |
| SQL preamble                   | Adds a `sql_preamble` that runs before every query.                                                                                      |
| Removed security properties    | Deletes inherited security properties (access filters, extends, SQL preamble) from the parent model.                                     |

### Resolving access warnings

1. **Fix the query or workbook** — see the fix column in the tables above for the specific action per reason.
2. **Enable [AccessBoost](/share#boosting-permissions-with-accessboost)** — bypasses connection role restrictions for dashboard and app viewers. Use with caution; AccessBoost does not bypass `access_filters` or access grants unless `access_boostable: true` is set on the grant.

<Tip>
  If your query is built from **raw SQL** and you save it as a query view, make sure you either include it in a topic or make a new topic for that query view, or you will continue to see access warnings on your dashboard.
</Tip>


# Visualization showcase
Source: https://docs.omni.co/showcase/index

Check out these examples to see what's possible in Omni!

<Columns>
  <Card title="Calendar heatmap" href="/showcase/visualizations/calendar-heatmaps">
    Calendar cells colored by a value
  </Card>

  <Card title="Card grid" href="/showcase/visualizations/card-grid">
    A grid of responsive cards with metrics and images
  </Card>

  <Card title="Card list" href="/showcase/visualizations/list-view">
    A vertical list of cards with metrics or details
  </Card>

  <Card title="Card with criteria checklist" href="/showcase/visualizations/card-criteria-checklist">
    A card with a list of criteria
  </Card>

  <Card title="Card with strip plot" href="/showcase/visualizations/card-with-strip-plot">
    Card with a strip plot that displays changes over time
  </Card>

  <Card title="Card with target candlesticks" href="/showcase/visualizations/card-target-candlesticks">
    Card with current vs target and conditional coloring
  </Card>

  <Card title="Cohort table" href="/showcase/visualizations/cohort-table">
    Stylized cohort table for 12 months
  </Card>

  <Card title="Colored progress bars" href="/showcase/visualizations/colored-progress-bars">
    Use color to reinforce level of progress
  </Card>

  <Card title="Dashboard tabs" href="/showcase/visualizations/dashboard-tabs">
    Tabbed navigation for dashboards
  </Card>

  <Card title="Dashboard tile anchors" href="/showcase/visualizations/dashboard-tile-anchors">
    Table of contents for a dashboard
  </Card>

  <Card title="Data readout" href="/showcase/visualizations/data-readout">
    Sparkline with description containing query data references
  </Card>

  <Card title="Dumbbell plot" href="/showcase/visualizations/dumbbell-plot">
    Compare a pair of data points per category
  </Card>

  <Card title="Gauges" href="/showcase/visualizations/gauge">
    Displays a single value in a range
  </Card>

  <Card title="Gradient card & metrics" href="/showcase/visualizations/gradient-card">
    Wide card with KPI-style metrics
  </Card>

  <Card title="Honeycomb categorical chart" href="/showcase/visualizations/honeycomb-categorical">
    Hexagonal grid with conditional coloring
  </Card>

  <Card title="Honeycomb map" href="/showcase/visualizations/honeycomb-map">
    Stylized, hexagonal map with conditional coloring
  </Card>

  <Card title="Image grid" href="/showcase/visualizations/image-grid">
    Grid of images with a metric and label
  </Card>

  <Card title="Invoice report" href="/showcase/visualizations/invoice-report">
    Structured invoice with contact & order details
  </Card>

  <Card title="Kanban" href="/showcase/visualizations/kanban">
    Kanban-style project board with cards
  </Card>

  <Card title="KPI with conditional colors" href="/showcase/visualizations/kpi-conditional-colors">
    Dynamically apply colors to KPI values
  </Card>

  <Card title="KPI table" href="/showcase/visualizations/kpi-table">
    Table displaying multiple KPIs
  </Card>

  <Card title="KPI with sparkline" href="/showcase/visualizations/kpi-with-sparkline">
    KPI-style metric with sparkline
  </Card>

  <Card title="Location with national flag" href="/showcase/visualizations/location-with-national-flag">
    Show a location next to its national flag
  </Card>

  <Card title="Metric tree" href="/showcase/visualizations/metric-tree">
    Pyramid-shaped tree of interdependent metrics
  </Card>

  <Card title="Pie/donut with custom legend" href="/showcase/visualizations/pie-donut-custom-legend">
    Pie/donut with custom legend
  </Card>

  <Card title="Pills" href="/showcase/visualizations/pills">
    Display category values as color-coded pills
  </Card>

  <Card title="Record lookup" href="/showcase/visualizations/record-lookup">
    Card with details from a single record
  </Card>

  <Card title="Repeating pie charts" href="/showcase/visualizations/repeating-pie-chart">
    Multiple pie charts, one for each row of results
  </Card>

  <Card title="Repeating square fill charts" href="/showcase/visualizations/repeating-square-fill-chart">
    Percentage-filled square charts, one for each row of results
  </Card>

  <Card title="Repeating waffle charts" href="/showcase/visualizations/repeating-waffle-chart">
    Percentage-filled waffle charts, one for each row of results
  </Card>

  <Card title="Simple subtotal table" href="/showcase/visualizations/simple-subtotal-table">
    Table with subtotals on top and coloring by category
  </Card>

  <Card title="Star rating" href="/showcase/visualizations/star-rating">
    Display a numeric rating as filled and empty stars
  </Card>

  <Card title="Status indicator" href="/showcase/visualizations/status-indicator">
    Show a status next to a colored indicator dot
  </Card>

  <Card title="Symmetric funnel" href="/showcase/visualizations/symmetric-funnel">
    Funnel with multiple stages
  </Card>

  <Card title="Table with tiny bar charts" href="/showcase/visualizations/table-with-tiny-bars">
    Small chart within each table row
  </Card>

  <Card title="Team progress tracker" href="/showcase/visualizations/team-progress-tracker">
    Show team members progress to their goals
  </Card>

  <Card title="Test results cards" href="/showcase/visualizations/test-results-cards">
    Consistent presentation of multiple metrics with varying ranges
  </Card>

  <Card title="Thermometer" href="/showcase/visualizations/thermometer">
    Fundraising style progress indicator
  </Card>

  <Card title="Uptime heatmaps" href="/showcase/visualizations/uptime-heatmaps">
    Use color to show reliability of a service over time
  </Card>

  <Card title="User profile" href="/showcase/visualizations/user-profile">
    Combine a name, email, and avatar into one column
  </Card>

  <Card title="Word cloud" href="/showcase/visualizations/word-cloud">
    Visualization that highlights frequently-used words
  </Card>
</Columns>


# Calendar heatmaps
Source: https://docs.omni.co/showcase/visualizations/calendar-heatmaps

The code for these examples can be used in the Markdown visualization to create different styles of calendars with cells colored by a value.

## Full year calendar

<img alt="" />

### Setup

This query used for this example has the following structure:

* **Date field** - make sure to enable "fill in missing dates" to capture any days that are missing data and to extend to the full year
* **Value field** - a numeric field that we'll use to color the day by
* **Color calculation** - a simple % of the largest value to map colors (`=B1 / MAX(B:B)`)
* **Color bucket calculation** - name of the color "bucket" the date fits into so we can have fewer colors to work with (`=IFS(C1 = 0, "empty", C1 < 0.2, "lt20", C1 < 0.4, "lt40", C1 < 0.6, "lt60", C1 < 0.8, "lt80", TRUE, "lt100")`)

<img alt="" />

### Example code

The example below is customized to work for 2025. For different years, you'll need to adjust the number of empty `<li>` tags to get the data starting on the right day of the week.

```html expandable theme={null}
<style>
article.calendar-grid {
  /* sizing */
  --cell-width: 12px;
  --cell-height: 12px;
  --cell-gap: 3px;
  --weekday-width: calc(3 * var(--cell-width));
  --calendar-label-size: 10px;

  /* colors */
  --empty-color: rgba(0,0,0,0.05);
  --lt20: #c1e598;
  --lt40: #94d284;
  --lt60: #62bb6e;
  --lt80: #399d55;
  --lt100: #1a7d41;
  
  width: min-content;
}
article.calendar-grid h3 {
  margin-top: 0;
}
article.calendar-grid ul {
  list-style: none;
  margin: 0;
  padding: 0 8px; 
}
article.calendar-grid ul li {
  list-style: none;
  margin: 0;
  padding: 0; 
  color: var(--color-text1);
}
article.calendar-grid ul.labels {
  display: grid;
  grid-template-columns: var(--weekday-width) repeat(12, 1fr);
  gap: var(--cell-gap);

  & li {
    display: flex;
    align-items: center;
    text-align: center;
    justify-content: center;
    font-size: var(--calendar-label-size);
    text-transform: uppercase;
  }
}
article.calendar-grid ul.calendar {
 display: grid;
  display: grid;
  grid-template-rows: repeat(7, 1fr);
  grid-auto-flow: column;
  grid-auto-columns: min-content;
  gap: var(--cell-gap);
  width: 100%;
  
  & li {
    border: 1px solid rgba(0,0,0,0.1);
    border-radius: 3px;
    width: var(--cell-width);
    height: var(--cell-height);
    display: flex;
    align-items: center;
    justify-content: center;
    position: relative;
  }
  & li.heading {
    border: none;
    width: var(--day-width);
    font-size: var(--calendar-label-size);
    text-transform: uppercase;
    text-align: right;
    justify-content: flex-end;
    padding-right: 3px;
  }
  & li.last-year {
    visibility: hidden;
  }
  & li.empty {
    background: var(--empty-color);
  }
  & li.lt20 {
    background: var(--lt20);
  }
  & li.lt40 {
    background: var(--lt40);
  }
  & li.lt60 {
    background: var(--lt60);
  }
  & li.lt80 {
    background: var(--lt80);
  }
  & li.lt100 {
    background: var(--lt100);
  }
  & li .tooltip-content {
    visibility: hidden;
    position: absolute;
    z-index: 1;
    bottom: 125%;
    left: 50%;
    transform: translateX(-50%);
    width: 80px;
    background-color: #333;
    color: white;
    text-align: center;
    border-radius: 5px;
    padding: 4px 6px;
    font-size: 10px;
    font-weight: normal;
    opacity: 0;
    transition: opacity 0.15s;
    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
    line-height: 1.4;
    word-wrap: break-word;
    white-space: normal;
  }
  & li .tooltip-content::after {
    content: "";
    position: absolute;
    top: 100%;
    left: 50%;
    margin-left: -5px;
    border-width: 5px;
    border-style: solid;
    border-color: #333 transparent transparent transparent;
  }
  & li:hover .tooltip-content {
    visibility: visible;
    opacity: 1;
  }
}
article.calendar-grid ul.legend {
  font-size: var(--calendar-label-size);
  text-transform: uppercase;
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: flex-end;
  gap: var(--cell-gap);
  padding-top: 12px;

  & li.legend-item {
    border: 1px solid rgba(0,0,0,0.1);
    border-radius: 3px;
    width: var(--cell-width);
    height: var(--cell-height);    
  }
  & li.empty {
    background: var(--empty-color);
  }
  & li.lt20 {
    background: var(--lt20);
  }
  & li.lt40 {
    background: var(--lt40);
  }
  & li.lt60 {
    background: var(--lt60);
  }
  & li.lt80 {
    background: var(--lt80);
  }
  & li.lt100 {
    background: var(--lt100);
  }

}
</style>

<article class="calendar-grid">
<h3>2025 sales by day</h3>
<ul class="labels">
  <li></li>
  <li>Jan</li>
  <li>Feb</li>
  <li>Mar</li>
  <li>Apr</li>
  <li>May</li>
  <li>Jun</li>
  <li>Jul</li>
  <li>Aug</li>
  <li>Sep</li>
  <li>Oct</li>
  <li>Nov</li>
  <li>Dec</li>
</ul>
<ul class="calendar">
  <li class="heading"></li>
  <li class="heading">mon</li>
  <li class="heading"></li>
  <li class="heading">wed</li>
  <li class="heading"></li>
  <li class="heading">fri</li>
  <li class="heading"></li>
  <!-- the following 3 LIs get our start weekday to Wednesday -->
  <li class="last-year"></li>
  <li class="last-year"></li>
  <li class="last-year"></li>
  {{#result}}
  <li class="{{calc_2.value_static}}">
    <div class="tooltip-content">
      {{order_items.created_at[date].value_static}}<br />
      {{order_items.total_sale_price.value}}
    </div>
  </li>
  {{/result}}
</ul>
<ul class="legend">
  <li>Less</li>
  <li class="legend-item empty"></li>
  <li class="legend-item lt20"></li>
  <li class="legend-item lt40"></li>
  <li class="legend-item lt60"></li>
  <li class="legend-item lt80"></li>
  <li class="legend-item lt100"></li>
  <li>More</li>
</ul>
</article>
```

## Full year calendar, vertical

<img alt="" />

### Setup

The setup for the vertical full year calendar is identical to the example above:

* **Date field** - make sure to enable "fill in missing dates" to capture any days that are missing data and to extend to the full year
* **Value field** - a numeric field that we'll use to color the day by
* **Color calculation** - a simple % of the largest value to map colors (`=B1 / MAX(B:B)`)
* **Color bucket calculation** - name of the color "bucket" the date fits into so we can have fewer colors to work with (`=IFS(C1 = 0, "empty", C1 < 0.2, "lt20", C1 < 0.4, "lt40", C1 < 0.6, "lt60", C1 < 0.8, "lt80", TRUE, "lt100")`)

<img alt="" />

### Example code

```html expandable theme={null}
<style>
article.calendar-grid {
  /* sizing */
  --cell-width: 32px;
  --cell-height: 12px;
  --cell-gap: 1px;
  --month-height: calc(3 * var(--cell-height));
  --calendar-label-size: 10px;

  /* colors */
  --empty-color: var(--color-border1);
  --lt20: #c1e598;
  --lt40: #94d284;
  --lt60: #62bb6e;
  --lt80: #399d55;
  --lt100: #1a7d41;
  
}
article.calendar-grid h3 {
  margin-top: 0;
}
article.calendar-grid .calendar-wrapper {
  display: flex;
  flex-direction: row;
  gap: 4px;
}
article.calendar-grid ul {
  list-style: none;
  margin: 0;
  padding: 0; 
}
article.calendar-grid ul li {
  list-style: none;
  margin: 0;
  padding: 0; 
  color: var(--color-text1);
}
article.calendar-grid ul.labels {
  display: grid;
  grid-template-rows: var(--cell-height) repeat(12, 1fr);
  gap: var(--cell-gap) var(--cell-gap);

  & li {
    display: flex;
    align-items: center;
    text-align: center;
    justify-content: center;
    font-size: var(--calendar-label-size);
    text-transform: uppercase;
  }
}
article.calendar-grid ul.calendar {
  display: grid;
  grid-template-columns: repeat(7, var(--cell-width));
  grid-auto-flow: row;
  grid-auto-columns: min-content;
  gap: var(--cell-gap);
  width: 100%;
  
  & li {
    border-radius: 0;
    width: var(--cell-width);
    height: var(--cell-height);
    display: flex;
    align-items: center;
    justify-content: center;
    position: relative;
    font-size: var(--calendar-label-size);
    font-weight: bold;
    color: var(--color-text4);
  }
  & li.heading {
    width: var(--cell-width);
    font-size: var(--calendar-label-size);
    text-transform: uppercase;
    text-align: center;
    justify-content: center;
  }
  & li.last-year {
    visibility: hidden;
  }
  & li.empty {
    background: var(--empty-color);
  }
  & li.lt20 {
    background: var(--lt20);
  }
  & li.lt40 {
    background: var(--lt40);
  }
  & li.lt60 {
    background: var(--lt60);
  }
  & li.lt80 {
    background: var(--lt80);
  }
  & li.lt100 {
    background: var(--lt100);
  }
  & li .tooltip-content {
    visibility: hidden;
    position: absolute;
    z-index: 1;
    bottom: 125%;
    left: 50%;
    transform: translateX(-50%);
    width: 80px;
    background-color: #333;
    color: white;
    text-align: center;
    border-radius: 5px;
    padding: 4px 6px;
    font-size: 10px;
    font-weight: normal;
    opacity: 0;
    transition: opacity 0.15s;
    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
    line-height: 1.4;
    word-wrap: break-word;
    white-space: normal;
  }
  & li .tooltip-content::after {
    content: "";
    position: absolute;
    top: 100%;
    left: 50%;
    margin-left: -5px;
    border-width: 5px;
    border-style: solid;
    border-color: #333 transparent transparent transparent;
  }
  & li:hover .tooltip-content {
    visibility: visible;
    opacity: 1;
  }
}
article.calendar-grid ul.legend {
  font-size: var(--calendar-label-size);
  text-transform: uppercase;
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: flex-start;
  gap: var(--cell-gap);
  padding-top: 12px;

  & li.legend-item {
    border: 1px solid rgba(0,0,0,0.1);
    width: min(var(--cell-width), var(--cell-height));
    height: min(var(--cell-width), var(--cell-height));
  }
  & li.empty {
    background: var(--empty-color);
  }
  & li.lt20 {
    background: var(--lt20);
  }
  & li.lt40 {
    background: var(--lt40);
  }
  & li.lt60 {
    background: var(--lt60);
  }
  & li.lt80 {
    background: var(--lt80);
  }
  & li.lt100 {
    background: var(--lt100);
  }
  & li:first-of-type {
    padding-left: var(--cell-width);
    padding-right: 3px;
  }
  & li:last-of-type {
    padding-left: 3px;
  }

}
</style>

<article class="calendar-grid">
<h3>2024 {{fields.order_items.total_sale_price.label}} {{#filters.users.state.value}}for {{filters.users.state.value}}{{/filters.users.state.value}} by day</h3>
<div class="calendar-wrapper">
<ul class="labels">
  <li></li>
  <li>Jan</li>
  <li>Feb</li>
  <li>Mar</li>
  <li>Apr</li>
  <li>May</li>
  <li>Jun</li>
  <li>Jul</li>
  <li>Aug</li>
  <li>Sep</li>
  <li>Oct</li>
  <li>Nov</li>
  <li>Dec</li>
</ul>
<ul class="calendar">
  <li class="heading">S</li>
  <li class="heading">M</li>
  <li class="heading">T</li>
  <li class="heading">W</li>
  <li class="heading">R</li>
  <li class="heading">F</li>
  <li class="heading">S</li>
  <li class="Sunday last-year"></li><!-- placeholder to ensure 2024 starts on correct day of week -->
  {{#result}}
  <li class="month-day-{{order_items.created_at[day_of_month].raw}} {{calc_2.value_static}}">
    <div class="tooltip-content">
      {{order_items.created_at[date].value_static}}<br />
      {{order_items.total_sale_price.value}}
    </div>
  </li>
  {{/result}}
</ul>
</div>
<ul class="legend">
  <li class="legend-label">Less</li>
  <li class="legend-item empty"></li>
  <li class="legend-item lt20"></li>
  <li class="legend-item lt40"></li>
  <li class="legend-item lt60"></li>
  <li class="legend-item lt80"></li>
  <li class="legend-item lt100"></li>
  <li class="legend-label">More</li>
</ul>
</article>
```

## Single month heatmap

Fills a single month like a typical wall calendar, correctly laying out the days of the week no matter the month. Also adds a little `•` marker on today, if it is in view.

<img alt="" />

### Setup

This example uses a lot of calculations make the drawing of any month possible. When referencing calculations in mustache, you need to use the ID of the field, which will automatically be assigned to the calculation when you create it. For example, the first calc you create will have the ID of `calc_1`, the second `calc_2`, etc. In the example query, the calc ID has been provided as part of the label so you can more easily connect the references to the calculation in the markdown code. When you create your own calculations, they may have different IDs.

**Note:** Make sure to have "fill in missing rows" turned on for `Date`, `Day of month` and the `Day of week` columns in order to correctly display the full month.

| Col | Name                       | Calculation formula                                                                                              | Purpose                                                                                     |
| --- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| A   | Date                       | query data                                                                                                       |                                                                                             |
| B   | Day of month               | query data                                                                                                       | Number in the calendar cell                                                                 |
| C   | Day of week num            | query data                                                                                                       | Need to know which day of week to start on                                                  |
| D   | adjusted DoW num (calc\_3) | =MOD(C1, 7) + 1                                                                                                  | Our data starts counting week on Mondays. This adjusts the start day of the week to Sunday. |
| E   | Users                      | query data                                                                                                       | metric used to base color off of                                                            |
| F   | pct of max (calc\_1)       | =E1 / MAX(E:E)                                                                                                   | create range for easy bucketing                                                             |
| G   | color class (calc\_4)      | =IFS(F1 = 0, "empty", F1 \< 0.2, "lt20", F1 \< 0.4, "lt40", F1 \< 0.6, "lt60", F1 \< 0.8, "lt80", TRUE, "lt100") | define bucket ranges to simplify coloring                                                   |
| H   | heading (calc\_2)          | =TEXT(A1, "mmmm yyyy")                                                                                           | nice formatting of the month for the heading                                                |
| I   | today (calc\_5)            | =IF(A1 = TODAY(), "today", "")                                                                                   | which cell to put a little "today" indicator                                                |

<img alt="" />

### Example code

```html expandable theme={null}
<style>
article.calendar-grid {
  /* sizing */
  --cell-width: 32px;
  --cell-height: 32px;
  --cell-gap: 2px;
  --calendar-label-size: 10px;

  /* colors */
  --empty-color: var(--color-background-alt);
  --lt20: #b8c7e0;
  --lt40: #88b3d6;
  --lt60: #549fc8;
  --lt80: #258bab;
  --lt100: #077b7e;

  width: fit-content;
  margin: 0 auto;
}
article.calendar-grid h3 {
  margin: 0;
  font-size: var(--font-sm);
}
article.calendar-grid ul {
  list-style: none;
  margin: 0;
  padding: 0; 
}
article.calendar-grid ul li {
  list-style: none;
  margin: 0;
  padding: 0; 
}
article.calendar-grid ul.calendar {
  display: grid;
  grid-template-columns: repeat(7, var(--cell-width));
  grid-auto-flow: row;
  grid-auto-columns: min-content;
  gap: var(--cell-gap);
  width: 100%;
  
  & li {
    border-radius: 2px;
    border: 1px solid rgba(0,0,0,0.1);
    width: var(--cell-width);
    height: var(--cell-height);
    display: flex;
    align-items: center;
    justify-content: center;
    position: relative;
    color: black;
  }
  & li.heading {
    width: var(--cell-width);
    font-size: var(--calendar-label-size);
    text-transform: uppercase;
    text-align: center;
    align-items: flex-end;
    color: var(--color-text1);
    border-width: 0;
  }
  li:nth-of-type(8) {
    /* adjusted DoW number: This is what gets us starting on the right day of the week */
    grid-column-start: {{result.0.calc_3.raw}};
  }
  & li span.date {
    font-size: var(--calendar-label-size);
    font-weight: normal;
    display: flex;
    width: 100%;
    height: 100%;
    line-height: var(--cell-height);
    justify-content: center;
    text-align: center;
    align-items: center;
  }
  & li.empty {
    background: var(--empty-color);
  }
  & li.today {
    xborder-color: rgba(0,0,0,0.5);
  }
  & li.today::before {
    content: "•";
    position: absolute;
    bottom: -4px;
  }
  & li.today ~ li.empty {
    color: var(--color-text1);
  }
  & li.lt20 {
    background: var(--lt20);
  }
  & li.lt40 {
    background: var(--lt40);
  }
  & li.lt60 {
    background: var(--lt60);
  }
  & li.lt80 {
    background: var(--lt80);
    color: white;
  }
  & li.lt100 {
    background: var(--lt100);
    color: white;
  }
  & li .tooltip-content {
    visibility: hidden;
    position: absolute;
    z-index: 1;
    bottom: 100%;
    left: 50%;
    transform: translateX(-50%);
    width: 50px;
    background-color: #333;
    color: white;
    text-align: center;
    border-radius: 5px;
    padding: 4px 6px;
    font-size: 10px;
    font-weight: normal;
    opacity: 0;
    transition: opacity 0.15s;
    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
    line-height: 1.4;
    word-wrap: break-word;
    white-space: normal;
    text-transform: lowercase;
  }
  & li .tooltip-content::after {
    content: "";
    position: absolute;
    top: 100%;
    left: 50%;
    margin-left: -5px;
    border-width: 5px;
    border-style: solid;
    border-color: #333 transparent transparent transparent;
  }
  & li:hover .tooltip-content {
    visibility: visible;
    opacity: 1;
  }
}
article.calendar-grid ul.legend {
  font-size: var(--calendar-label-size);
  text-transform: uppercase;
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: flex-start;
  gap: var(--cell-gap);
  padding-top: 16px;

  & li.legend-item {
    border: 1px solid rgba(0,0,0,0.1);
    width: 12px;
    height: 12px;
  }
  & li.empty {
    background: var(--empty-color);
  }
  & li.lt20 {
    background: var(--lt20);
  }
  & li.lt40 {
    background: var(--lt40);
  }
  & li.lt60 {
    background: var(--lt60);
  }
  & li.lt80 {
    background: var(--lt80);
  }
  & li.lt100 {
    background: var(--lt100);
  }
  & li.legend-more {
    padding-left: 3px;
    color: var(--color-text1);
  }
  & li.legend-today {
    padding-left: 24px;
    color: var(--color-text1);
  }

}
</style>

<article class="calendar-grid">
<h3>{{result._first.calc_2.value}} • {{fields.users.count.label}}</h3>
<div class="calendar-wrapper">
<ul class="calendar">
  <li class="heading">S</li>
  <li class="heading">M</li>
  <li class="heading">T</li>
  <li class="heading">W</li>
  <li class="heading">T</li>
  <li class="heading">F</li>
  <li class="heading">S</li>
  {{#result}}
  <li class="{{calc_5.raw}} {{calc_4.value_static}}">
    <span class="date">{{users.created_at[day_of_month].value}}</span>
    <div class="tooltip-content">
      {{users.count.value}}<br />{{fields.users.count.label}}
    </div>
  </li>
  {{/result}}
</ul>
</div>
<ul class="legend">
  <li class="legend-item empty"></li>
  <li class="legend-item lt20"></li>
  <li class="legend-item lt40"></li>
  <li class="legend-item lt60"></li>
  <li class="legend-item lt80"></li>
  <li class="legend-item lt100"></li>
  <li class="legend-more">More {{fields.users.count.label}}</li>
  <li class="legend-today">• today</li>
</ul>
</article>
```


# Card with criteria checklist
Source: https://docs.omni.co/showcase/visualizations/card-criteria-checklist

The code for this example can be used in the Markdown visualization to create a card with a list of criteria:

<img alt="" />

## Example query

<img alt="" />

## Example code

```html expandable theme={null}
<style>
/* Base styling */
body {
  font-family: Inter, sans-serif;
  margin: 0;
  padding: 10px;
  background-color: #f5f5f5;
}

/* Report card table styling */
.report-card-table {
  width: 100%;
  border-collapse: separate;
  border-spacing: 0 10px;
  margin-bottom: 10px;
}

/* Opportunity row styling */
.opportunity-row {
  background-color: white;
  box-shadow: 0 2px 2px rgba(0,0,0,0.1);
}

.opportunity-row > td {
  padding: 10px;
}

.opportunity-row td:first-child {
  border-top-left-radius: 10px;
  border-bottom-left-radius: 10px;
  border-left: 4px solid #191970;
}

.opportunity-row td:last-child {
  border-top-right-radius: 10px;
  border-bottom-right-radius: 10px;
}

/* Priority indicators */
.high-priority td:first-child {
  border-left-color: #907EFE;
}

.medium-priority td:first-child {
  border-left-color: #3943B7;
}

.low-priority td:first-child {
  border-left-color: #57A773;
}

/* Company info column styling */
.company-info {
  width: 33%;
  padding: 20px 20px 20px 30px;
  vertical-align: top;
}

.company-header {
  display: flex;
  align-items: center;
  margin-bottom: 15px;
}

.company-title {
  font-weight: bold;
  font-size: 20px;
  color: #191970;
  margin-right: 15px;
}

.company-logo {
  width: 80px;
  height: 80px;
  border-radius: 10px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  background-color: #f0f0f0;
  display: flex;
  justify-content: center;
  align-items: center;
  color: #999;
  font-size: 12px;
  margin-left: auto;
}

.company-logo img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: 10px;
}

.company-meta {
  margin-bottom: 18px;
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 15px;
}

.meta-item {
  font-size: 14px;
  color: #555;
  background-color: #f8f8f8;
  padding: 12px;
  border-radius: 8px;
}

.meta-value {
  display: block;
  font-weight: bold;
  color: #333;
  font-size: 16px;
  margin-top: 5px;
}

.company-tags {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  margin-bottom: 20px;
}

.tag {
  display: inline-block;
  background-color: #E6E6FA;
  color: #191970;
  font-size: 12px;
  padding: 6px 12px;
  border-radius: 16px;
  font-weight: 500;
}

/* Assessment column styling */
.assessment-info {
  width: 67%;
  padding: 2px;
  vertical-align: top;
}

.criteria-section {
  background-color: #f9f9f9;
  border-radius: 0 10px 10px 0;
  padding: 15px;
  height: 100%;
}

.criteria-table-container {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 15px;
  margin-top: 5px;
}

.criteria-column {
  width: 100%;
}

.criteria-header {
  font-weight: bold;
  font-size: 16px;
  color: #191970;
  margin-bottom: 1px;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.criteria-score {
  background-color: #191970;
  color: white;
  border-radius: 10%;
  width: 60px;
  height: 40px;
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 16px;
  font-weight: bold;
}

.criteria-table {
  width: 100%;
  border-collapse: collapse;
  margin-top: 5px;
}

.criteria-table th {
  text-align: left;
  padding: 10px;
  font-size: 14px;
  font-weight: 600;
  color: #444;
  border-bottom: 2px solid #e0e0e0;
}

.criteria-table td {
  padding: 10px;
  border-bottom: 1px solid #e8e8e8;
  vertical-align: middle;
}

.criteria-table tr:last-child td {
  border-bottom: none;
}

.status-indicator {
  display: inline-block;
  width: 24px;
  height: 24px;
  border-radius: 50%;
  position: relative;
}

.status-true {
  background-color: #57A773;
}

.status-true:after {
  content: "✓";
  color: white;
  position: absolute;
  font-size: 14px;
  font-weight: bold;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

.status-false {
  background-color: #E63946;
}

.status-false:after {
  content: "✗";
  color: white;
  position: absolute;
  font-size: 14px;
  font-weight: bold;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

.criteria-label {
  font-size: 14px;
  color: #333;
  font-weight: 400;
}

/* Footer styling */
.company-footer {
  font-size: 13px;
  color: #666;
  border-top: 1px solid #eee;
  padding-top: 10px;
  margin-top: 12px;
  display: flex;
  flex-wrap: wrap;
  gap: 10px;
  justify-content: space-between;
}

.company-footer span {
  word-wrap: break-word;
  overflow-wrap: break-word;
  white-space: normal;
  justify-content: space-between;
}

/* Tooltip styling */
.tooltip-container {
  position: relative;
  display: inline-flex;
  align-items: center;
}

.tooltip-icon {
  display: inline-flex;
  justify-content: center;
  align-items: center;
  width: 16px;
  height: 16px;
  background-color: #ccc;
  color: white;
  border-radius: 50%;
  font-size: 12px;
  font-weight: bold;
  margin-left: 8px;
  cursor: help;
}

.tooltip-content {
  visibility: hidden;
  position: absolute;
  z-index: 100;
  bottom: 125%;
  left: 50%;
  transform: translateX(-50%);
  width: 240px;
  background-color: #333;
  color: white;
  text-align: left;
  border-radius: 6px;
  padding: 10px 15px;
  font-size: 12px;
  font-weight: normal;
  opacity: 0;
  transition: opacity 0.3s;
  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
  line-height: 1.4;
  word-wrap: break-word;
  white-space: normal;
}

.tooltip-content::after {
  content: "";
  position: absolute;
  top: 100%;
  left: 50%;
  margin-left: -5px;
  border-width: 5px;
  border-style: solid;
  border-color: #333 transparent transparent transparent;
}

.tooltip-container:hover .tooltip-content {
  visibility: visible;
  opacity: 1;
}
</style>

<table class="report-card-table">
  <tbody>
    {{#result}}
    <tr class="opportunity-row {{priorityClass}}">
      <td class="company-info">
        <div class="company-header">
          <div class="company-title">{{opptys.opportunity_name.value_static}}</div>
          <div class="company-logo">
            <img src={{opptys.logo.value_static}} alt="N/A">
          </div>
        </div>
        <div class="company-meta">
          <div class="meta-item">ARR <span class="meta-value">{{opptys.arr.value_static}}</span></div>
          <div class="meta-item">Current Stage <span class="meta-value">{{opptys.stage_name.value_static}}</span></div>
          <div class="meta-item">Close Date <span class="meta-value">{{opptys.close_date.value_static}}</span></div>
        </div>
        <div class="company-tags">
          <span class="tag">{{opptys.type.value_static}}</span>
        </div>
        <div class="company-footer">
          <span>Qualified At: {{opptys.qualified_at.value_static}}</span>
        </div>
        <div class="company-footer">
          <span>Next Steps: {{opptys.next_steps.value_static}}</span>
        </div>
        <div class="company-footer">
        </div>
      </td>
      <td class="assessment-info">
        <div class="criteria-section">
          <div class="criteria-header">
            <span>Assessment Criteria</span>
            <span class="criteria-score">{{opptys.score.value_static}}/10</span>
          </div>
          <table class="criteria-table">
            <thead>
              <tr>
                <th width="40">Status</th>
                <th>Criteria</th>
                <th width="40">Status</th>
                <th>Criteria</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><span class="status-indicator status-{{opptys.next_steps_populated.value_static}}"></span></td>
                <td class="criteria-label">
                  <div class="tooltip-container">
                    Next Steps Populated
                    <span class="tooltip-icon">i</span>
                    <span class="tooltip-content">Have next steps been set?</span>
                  </div>
                </td>
                <td><span class="status-indicator status-{{opptys.roadmap_call_scheduled.value_static}}"></span></td>
                <td class="criteria-label">Roadmap Call Scheduled</td>
              </tr>
              <tr>
                <td><span class="status-indicator status-{{opptys.exec_sponsor_introduced.value_static}}"></span></td>
                <td class="criteria-label">Exec Sponsor Introduced</td>
                <td><span class="status-indicator status-{{opptys.poc_scoped.value_static}}"></span></td>
                <td class="criteria-label">POC Scoped</td>
              </tr>
              <tr>
                <td><span class="status-indicator status-{{opptys.realistic_close_date_based_on_stage.value_static}}"></span></td>
                <td class="criteria-label">
                  <div class="tooltip-container">
                    Realistic Close Date Based On Stage
                    <span class="tooltip-icon">i</span>
                    <span class="tooltip-content">This flags if the opportunity is in "Qualifying" with a close date within 14 days, in "Scoping" with a close date within 7 days, or in "Evaluating" with a close date within 3 days</span>
                  </div>
                </td>
                <td><span class="status-indicator status-{{opptys.economic_buyer_identified.value_static}}"></span></td>
                <td class="criteria-label">
                  <div class="tooltip-container">
                    Economic Buyer Identified
                    <span class="tooltip-icon">i</span>
                    <span class="tooltip-content">Have we identified who will be making the final buying decision?</span>
                  </div>
                </td>
              </tr>
              <tr>
                <td><span class="status-indicator status-{{opptys.decision_criteria_identified.value_static}}"></span></td>
                <td class="criteria-label">Decision Criteria Set</td>
                <td><span class="status-indicator status-{{opptys.pain_identified.value_static}}"></span></td>
                <td class="criteria-label">Pain Identified</td>
              </tr>
              <tr>
                <td><span class="status-indicator status-{{opptys.champion_identified.value_static}}"></span></td>
                <td class="criteria-label">Champion Identified</td>
                <td></td>
                <td></td>
              </tr>
              <tr>
                <td><span class="status-indicator status-{{opptys.security_sign_off.value_static}}"></span></td>
                <td class="criteria-label">
                  <div class="tooltip-container">
                    Security Sign Off
                    <span class="tooltip-icon">i</span>
                    <span class="tooltip-content">Have we completed the security signoff process?</span>
                  </div>
                </td>
                <td></td>
                <td></td>
              </tr>
            </tbody>
          </table>
        </div>
      </td>
    </tr>
    {{/result}}
  </tbody>
</table>
```


# Card grid
Source: https://docs.omni.co/showcase/visualizations/card-grid

The code for this example can be used in the Markdown visualization to create a grid of responsive cards with metrics and images:

<img alt="" />

## Example dataset

<img alt="" />

## Example code

```html expandable theme={null}
<style>
/* https://play.tailwindcss.com/vHqt0FBGy8 */
.deals-container {
  display: grid;
  padding: 1.5rem;
  grid-template-columns: repeat(1, minmax(0, 1fr));
  column-gap: 1.5rem;
  row-gap: 2rem;
  list-style: none;

  @media (min-width: 1024px) {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }

  @media (min-width: 1280px) {
    grid-template-columns: repeat(2, minmax(0, 1fr));
    column-gap: 2rem;
  }

  @media (min-width: 1536px) {
    grid-template-columns: repeat(3, minmax(0, 1fr));
    column-gap: 2rem;
  }

  @media (min-width: 1960px) {
    grid-template-columns: repeat(3, minmax(0, 1fr));
    column-gap: 2rem;
  }
}

.deal-container {
  overflow: hidden;
  border-radius: 0.75rem;
  border: 1px solid #E5E7EB;
  list-style: none;
}

.deal-header {
  display: flex;
  padding: 1.5rem;
  column-gap: 1rem;
  align-items: center;
  border-bottom: 1px solid rgb(17 24 39 / 0.05);
  background-color: #F9FAFB;
}

.deal-logo {
  object-fit: cover;
  flex: none;
  border-radius: 0.5rem;
  border: 1px solid rgb(229 231 235);
  box-shadow: 0 0 0 0 calc(1px) rgb(229 231 235);
  width: 4rem;
  height: 4rem;
  background-color: #ffffff;
}

.deal-name {
  font-size: 1rem;
  line-height: 1.25rem;
  font-weight: 500;
  line-height: 1.5rem;
  color: #111827;
}

.deal-details {
  padding-top: 1rem;
  padding-bottom: 1rem;
  padding-left: 1.5rem;
  padding-right: 1.5rem;
  margin-top: -0.75rem;
  margin-bottom: -0.75rem;
  border-top-width: 1px;
  border-color: #F3F4F6;
  font-size: 0.875rem;
  line-height: 1.25rem;
  line-height: 1.5rem;
}

.deal-details-inner {
  display: flex;
  padding-top: 0.3rem;
  padding-bottom: 0.3rem;
  column-gap: 1rem;
  justify-content: space-between;
}

/* Tailwind Helpers */
.-my-3 {
  margin-top: -0.75rem;
  margin-bottom: -0.75rem;
}

.flex {
  display: flex;
}

.flex-row {
  flex-direction: row;
}

.flex-col {
  flex-direction: column;
}

.grid {
  display: grid;
}

.h-12 {
  height: 3rem;
}

.w-12 {
  width: 3rem;
}

.flex-none {
  flex: none;
}

.grid-cols-1 {
  grid-template-columns: repeat(1, minmax(0, 1fr));
}

.items-start {
  align-items: flex-start;
}

.items-center {
  align-items: center;
}

.justify-between {
  justify-content: space-between;
}

.gap-x-2 {
  column-gap: 0.5rem;
}

.gap-x-4 {
  column-gap: 1rem;
}

.gap-x-6 {
  column-gap: 1.5rem;
}

.gap-y-8 {
  row-gap: 2rem;
}

.divide-y > :not([hidden]) ~ :not([hidden]) {
  border: 0;
  border-style: solid;
  border-top-width: 1px;
  border-bottom-width: 1px;
}

.divide-y > div.deal-details-inner:last-of-type {
  border-bottom-width: 0px;
}

.divide-gray-100 > :not([hidden]) ~ :not([hidden]) {
  border-color: rgb(243 244 246);
}

.overflow-hidden {
  overflow: hidden;
}

.rounded-lg {
  border-radius: 0.5rem;
}

.rounded-md {
  border-radius: 0.375rem;
}

.rounded-xl {
  border-radius: 0.75rem;
}

.border {
  border-width: 1px;
}

.border-b {
  border-bottom-width: 1px;
}

.border-gray-200 {
  border-color: rgb(229 231 235);
}

.border-gray-900\/5 {
  border-color: rgb(17 24 39 / 0.05);
}

.bg-gray-50 {
  background-color: rgb(249 250 251);
}

.bg-red-50 {
  background-color: rgb(254 242 242);
}

.bg-white {
  background-color: rgb(255 255 255);
}

.object-cover {
  object-fit: cover;
}

.p-6 {
  padding: 1.5rem;
}

.px-2 {
  padding-left: 0.5rem;
  padding-right: 0.5rem;
}

.px-6 {
  padding-left: 1.5rem;
  padding-right: 1.5rem;
}

.py-1 {
  padding-top: 0.25rem;
  padding-bottom: 0.25rem;
}

.py-3 {
  padding-top: 0.75rem;
  padding-bottom: 0.75rem;
}

.py-4 {
  padding-top: 1rem;
  padding-bottom: 1rem;
}

.text-sm {
  font-size: 0.875rem;
  line-height: 1.25rem;
}

.text-xs {
  font-size: 0.75rem;
  line-height: 1rem;
}

.font-medium {
  font-weight: 500;
}

.leading-6 {
  line-height: 1.5rem;
}

.text-gray-500 {
  color: rgb(107 114 128);
}

.text-gray-700 {
  color: rgb(55 65 81);
}

.text-gray-900 {
  color: rgb(17 24 39);
}

.text-red-700 {
  color: rgb(185 28 28);
}

.px-1 {
  padding-left: 0.25rem;
  padding-right: 0.25rem;
}

.pl-1 {
  padding-left: 0.25rem;
}

.pr-1 {
  padding-right: 0.25rem;
}

.pl-2 {
  padding-left: 0.50rem;
}

.pr-2 {
  padding-right: 0.50rem;
}

.text-sky-700 {
  color: rgb(3 105 161);
}

.ring-sky-600\/10 {
  border: 1px solid rgb(2 132 199 / 0.1);
}

.bg-sky-50 {
  background-color: rgb(240 249 255);
}

.ml-2 {
  margin-left: 0.5rem;
}

.bg-green-50 {
  background-color: rgb(240 253 244);
}

.text-green-700 {
  color: rgb(21 128 61);
}

.ring-green-600\/10 {
  border: 1px solid rgb(22 163 74 / 0.1);
}
</style>

<ul class="deals-container">
  {{#result}}
  <li class="deal-container">
    <div class="deal-header">
      <img src="https://{{omni_dbt__product_images.image.value_static}}?size=512" class="deal-logo">
      <section class="deal-name flex flex-col" style="justify-content: start;">
        <div class="flex flex-row" style="align-items: center;">{{omni_dbt__products.name.value}}</div>
      </section>
    </div>
    <dl class="-my-3 divide-y divide-gray-100 px-6 py-4 text-sm leading-6">
      <div class="deal-details-inner" style="border-bottom: none;">
        <dt class="text-gray-500">Revenue</dt>
        <dd class="flex items-start gap-x-2">
          <section class="rounded-md ml-2 font-medium ring-1 ring-inset text-green-700 bg-green-50 ring-green-600/10" style="padding: 2px 6px">{{omni_dbt__order_items.total_sale_price.value}}</section>
        </dd>
      </div>
      <div class="deal-details-inner">
        <dt class="text-gray-500">Brand</dt>
        <dd class="flex items-start gap-x-2">
          <div class="font-medium text-gray-900">{{omni_dbt__products.brand.value}}</div>
        </dd>
      </div>
      <div class="deal-details-inner">
        <dt class="text-gray-500">Category</dt>
        <dd class="flex items-start gap-x-2">
          <div class="font-medium text-gray-900">{{omni_dbt__products.category.value}}</div>
        </dd>
      </div>
      <div class="deal-details-inner">
        <dt class="text-gray-500">Total Items Sold</dt>
        <dd class="flex items-start gap-x-2">
          <div class="font-medium text-gray-900">{{omni_dbt__order_items.count.value}}</div>
        </dd>
      </div>
      <div class="deal-details-inner">
        <dt class="text-gray-500">Retail Price</dt>
        <dd class="flex items-start gap-x-2">
          <div class="font-medium text-gray-900">{{omni_dbt__products.retail_price.value}}</div>
        </dd>
      </div>
    </dl>
  </li>
  {{/result}}
</ul>
```


# Card with target candlesticks
Source: https://docs.omni.co/showcase/visualizations/card-target-candlesticks

The code for this example can be used in the Markdown visualization to create cards with conditional coloring, based on the current value versus the target.

In this visualization, the card is green if the KPI at or beating target and red if not.

<img alt="" />

## Setup

This markdown in this example complex and references a lot of calculations to position and style elements. Use this sample dataset, instructions, and code to recreate this example in your own instance.

1. [Download the sample CSV](https://github.com/exploreomni/doc-sample-data/blob/main/visualizations/candlesticks.csv).

2. Upload the sample CSV to your instance. Refer to the [Data input tables guide](/analyze-explore/data-input-csvs#adding-a-data-input-table-to-a-workbook) for instructions.

3. In a new query tab, select all fields except `Candlesticks Count`.

4. Format the fields as follows:

   * **Currency** - `Total Sales` and `Target Sales`
   * **Percent** - `Progress Bar Value`, `Progress Bar Target`, `From Target`, `Candle Value`, `Candle Target`, `Change Py`, and `Change Pm`

5. Format `Created At Month` to the month abbreviation with 2 digits for the year.

6. Sort the query so the most recent month in the data set, `Feb 25`, is first.

Your query should look like this:

<img alt="" />

You can now click **Chart** and select the **Markdown** chart type. Copy and paste the sample code below into the markdown editor.

**Note:** To recreate this with your own data set, you'll need a to create your own calculations for most fields. The formulas below refer to the column positions in the screenshot above:

| Col | Name                | Calculation formula        | Purpose                                                                 |
| --- | ------------------- | -------------------------- | ----------------------------------------------------------------------- |
| D   | Progress Bar Range  | =MAX(B1, C1)               | Denominator for the progress bar                                        |
| E   | Progress Bar Value  | =B1 / D1                   | % fill for the progress bar                                             |
| F   | Progress Bar Target | =C1 / D1                   | % position for the target mark                                          |
| G   | Delta From Target   | =B1 - C1                   | value change from target                                                |
| H   | % From Target       | =G1 / C1                   | % change from target (used in up/down arrows )                          |
| I   | Delta Direction     | =IF(G1 >= 0, "pos", "neg") | class name used to color the card header, progress bars and candle dots |
| J   | 12mo Min            | =MIN(B:C)                  | smallest of all the Total Sales and Target values                       |
| K   | 12mo Max            | =MAX(B:C)                  | largest of all the Total Sales and Target values                        |
| L   | 12mo Range          | =K1 - J1                   | the denominator for all the candle position calculations                |
| M   | Candle Value        | =(B1 - J1) / L1            | % fill for each candle                                                  |
| N   | Candle Target       | =(C1 - J1) / L1            | % position for each candle target mark                                  |
| O   | % Change Py         | =(B1 - B13) / B13          | % change from previous year (used in up/down arrows)                    |
| P   | Py Direction        | =IF(O1 >= 0, "pos", "neg") | class name used to point previous year change arrow up or down          |
| Q   | % Change Pm         | =(B1 - B2) / B2            | % change from previous month (used in up/down arrows)                   |
| R   | Pm Direction        | =IF(Q1 >= 0, "pos", "neg") | class name used to point previous month change arrow up or down         |

## Example code

```html expandable theme={null}
<style>
.card {
  --color-pos: #6BABB4;
  --color-neg: #D64467;
  /* --color-fill does the primary card and progress bar coloring */
  --color-fill: var(--color-{{result._first.candlesticks.delta_direction.value_static}});
  --card-inline-padding: var(--size4);

  background: var(--color-background);
  border: 1px solid var(--color-border2);
  border-radius: var(--radius-lg);
  display: flex;
  flex-direction: column;
  height: 100%;
  overflow: hidden;

  & h2 {
    margin: 0;
    padding: var(--size2) var(--card-inline-padding);
    font-size: var(--font-md);
    color: white;
    background: var(--color-fill);
  }

  & .card-body {
    padding: var(--size2) var(--card-inline-padding);
  }
}

.card-kpi {
  padding-block: var(--size4);

  & h3 {
    margin: 0;
    font-size: var(--font-xxl);
  }

  & h4 {
    margin: 0;
    font-size: var(--font-sm);

    & span {
      font-size: var(--font-xs);
      font-variation-settings: "wght" 400;
    }
  }
}

.card-progress {
  height: 24px;
  position: relative;
  padding: 4px 0;

  /* Since we are using the first row values for the big horizontal progress bar
     we can hard code the progress bar width and target mark in the css */
  & .progress-bar {
    background-color: var(--color-fill);
    width: {{result._first.candlesticks.progress_bar_value.value_static}};
    height: 12px;
  }

  & .progress-target {
    width: 2px;
    height: 20px;
    background: var(--color-text4);
    position: absolute;
    top: 0;
    left: calc({{result._first.candlesticks.progress_bar_target.value_static}} - 2px);
  }
}

.card-compare {
  list-style: none;
  margin: 0;
  padding: var(--size2);
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  align-items: center;

  & li {
    display: grid;
    grid-template-columns: min-content 1fr;
    gap: 0 var(--size2);

    & .up {
      color: var(--color-text-inverse);
      background: var(--color-surface-invert);
      width: 20px;
      height: 20px;
      text-align: center;
      border-radius: 50%;
      grid-row: 1/3;
    }

    & .down {
      color: var(--color-text-inverse);
      background: var(--color-surface-invert);
      width: 20px;
      height: 20px;
      text-align: center;
      border-radius: 50%;
      grid-row: 1/3;
    }

    & .compare-change {
      font-variation-settings: "wght" 600;
      line-height: var(--line-height-xs);
    }

    & .compare-label {
      font-size: var(--font-xs);
    }
  }

  & li.pos {
    .up { display: inline-block; }
    .down { display: none; }
  }

  & li.neg {
    .up { display: none; }
    .down { display: inline-block; }
  }
}

.card-columns {
  list-style: none;
  margin: 0;
  padding: var(--size6) 0 0;
  display: flex;
  flex-direction: row-reverse;
  justify-content: space-between;

  & li {
    display: flex;
    flex-direction: column;
    gap: 4px;
    width: 20px;
  }

  & li:last-of-type {
    /* If you don't want to include the previous year, hide it! */
    display: none;
  }

  & .column-progress {
    height: 80px;
    display: flex;
    flex-direction: column-reverse;
    align-items: center;
    position: relative;

    & .column-progress-bar {
      background: var(--color-foreground4);
      width: 12px;
      display: block;
    }

    & .column-progress-target {
      height: 2px;
      width: 20px;
      background: var(--color-text4);
      position: absolute;
    }
  }

  & .column-dot {
    background: var(--color-background-alt);
    width: 12px;
    height: 12px;
    border-radius: 50%;
    display: inline-block;
    margin: 0 4px;
  }

  & .neg .column-dot {
    background: var(--color-neg);
  }

  & .pos .column-dot {
    background: var(--color-pos);
  }

  & .column-date {
    transform: rotate(-90deg);
    transform-origin: top left;
    display: inline-block;
    font-size: var(--font-xxs);
    width: 48px;
    height: 20px;
    top: 48px;
    position: relative;
    text-align: right;
  }
}
</style>

<article class="card {{result._first.candlesticks.delta_direction.value_static}}">
  <h2>Category</h2>
  <section class="card-body">
    <section class="card-kpi">
      <h3>{{result._first.candlesticks.total_sales.value}}</h3>
      <h4><span>vs target </span> {{result._first.candlesticks.target.value}}</h4>
    </section>
    <section class="card-progress">
      <div class="progress-bar"></div>
      <div class="progress-target"></div>
    </section>
    <ul class="card-compare">
      <li class="{{result._first.candlesticks.delta_direction.value_static}}">
        <span class="down">&searr;</span>
        <span class="up">&nearr;</span>
        <span class="compare-change">{{result._first.candlesticks.__from_target.value}}</span>
        <span class="compare-label">vs target</span>
      </li>
      <li class="{{result._first.candlesticks.pm_dir.value_static}}">
        <span class="down">&searr;</span>
        <span class="up">&nearr;</span>
        <span class="compare-change">{{result._first.candlesticks.__change_pm.value}}</span>
        <span class="compare-label">vs PM</span>
      </li>
      <li class="{{result._first.candlesticks.py_direction.value_static}}">
        <span class="down">&searr;</span>
        <span class="up">&nearr;</span>
        <span class="compare-change">{{result._first.candlesticks.__change_py.value}}</span>
        <span class="compare-label">vs PY</span>
      </li>
    </ul>
    <ul class="card-columns">
      {{#result}}
      <li class="{{candlesticks.delta_direction.value_static}}">
        <span class="column-progress">
          <span class="column-progress-bar" style="height: {{candlesticks.candle_value.value_static}}"></span>
          <span class="column-progress-target" style="bottom: {{candlesticks.candle_target.value_static}}"></span>
        </span>
        <span class="column-dot"></span>
        <span class="column-date">{{candlesticks.created_at_month.value}}</span>
      </li>
      {{/result}}
    </ul>
  </section>
</article>
```


# Card with strip plot
Source: https://docs.omni.co/showcase/visualizations/card-with-strip-plot

The code for this example can be used in the Markdown visualization to create a card with a strip plot:

<img alt="" />

## Example query

The example code references a lot of calculations to position and style elements. Below is a screenshot of the query as a reference.

<img alt="" />

## Example code

```html expandable theme={null}
<style>
.tick-chart {
  display: grid;
  grid-template-columns: min-content 1fr min-content;
  gap: var(--size2);
  align-items: center;
  height: var(--size8);

  & .tick-label {
    font-size: var(--font-xxs);
    color: var(--color-text3);

    &.min-label {
      text-align: right;
    }

    &.max-label {
      text-align: left;
    }
  }

  & .ticks {
    margin: 0;
    padding: 0;
    height: var(--size6);
    position: relative;
    list-style: none;

    & li {
      position: absolute;
      background-color: #4269D0;
      height: var(--size6);
      width: 1px;
      margin: 0;
      padding: 0;
    }

    & li.focus-tick {
      width: 2px;
      background-color: var(--color-text4);
      height: var(--size10);
      top: -8px;
    }
  }
}

.compare-table {
  margin: var(--size4) 0;
  padding: 0;
  color: var(--color-text3);
  font-size: var(--font-xs);
  width: 100%;

  tr {
    & td {
      border-bottom: 1px solid var(--color-border1);
      height: var(--size6);
      padding: 0;
    }

    & .compare-label {
      width: 100%;
    }

    & .compare-value {
      padding-inline: var(--size2);
      text-align: right;
    }

    & .compare-change {
      width: var(--size5);
    }

    & .change-icon {
      height: var(--size5);
      width: var(--size5);
      display: none;
    }

    & .compare-change.up {
      color: #3ca951;

      & .up-arrow {
        display: flex;
      }
    }

    & .compare-change.down {
      color: #ff725c;

      & .down-arrow {
        display: flex;
      }
    }

    & .compare-change.same {
      color: var(--color-text1);

      & .no-change {
        display: flex;
      }
    }
  }

  tr.last-row td {
    border-bottom: 0;
  }
}

.bignum {
  h4 {
    font-size: var(--font-sm);
    color: #4269D0;
    margin: 0;
  }

  h2 {
    font-size: var(--font-xl);
    color: var(--color-key);
    margin: 0;
    color: var(--text4);
    font-weight: bold;
  }
}

.footnote {
  font-size: var(--font-xs);
  color: var(--color-text1);
  padding-block: var(--size1);
}
</style>

<div class="bignum">
  <h4>Avg Sales Price</h4>
  <h2>{{result._first.order_items.sale_price_average.value}}</h2>
</div>

<table class="compare-table">
  <tr>
    <td class="compare-label">1-week change</td>
    <td class="compare-value">{{result._first.calc_6.value}}</td>
    <td class="compare-change {{result._first.calc_9.value}}">
      <span class="change-icon up-arrow">
        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
          <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
          <path d="M17 7l-10 10" />
          <path d="M8 7l9 0l0 9" />
        </svg>
      </span>
      <span class="change-icon down-arrow">
        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
          <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
          <path d="M7 7l10 10" />
          <path d="M17 8l0 9l-9 0" />
        </svg>
      </span>
      <span class="change-icon no-change">
        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
          <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
          <path d="M5 12l14 0" />
        </svg>
      </span>
    </td>
  </tr>
  <tr>
    <td class="compare-label">1-year change</td>
    <td class="compare-value">{{result._first.calc_7.value}}</td>
    <td class="compare-change {{result._first.calc_10.value}}">
      <span class="change-icon up-arrow">
        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
          <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
          <path d="M17 7l-10 10" />
          <path d="M8 7l9 0l0 9" />
        </svg>
      </span>
      <span class="change-icon down-arrow">
        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
          <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
          <path d="M7 7l10 10" />
          <path d="M17 8l0 9l-9 0" />
        </svg>
      </span>
      <span class="change-icon no-change">
        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
          <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
          <path d="M5 12l14 0" />
        </svg>
      </span>
    </td>
  </tr>
  <tr>
    <td class="compare-label">4-week average</td>
    <td class="compare-value">{{result._first.calc_8.value}}</td>
    <td class="compare-change empty"></td>
  </tr>
  <tr class="last-row">
    <td class="compare-label">52-week average</td>
    <td class="compare-value">{{result._totals._first.order_items.sale_price_average.value}}</td>
    <td class="compare-change empty"></td>
  </tr>
</table>

<div class="tick-chart">
  <div class="tick-label min-label">{{result._first.calc_4.value}}</div>
  <ul class="ticks">
    {{#result}}
    <li style="left: {{calc_1.value}}%"></li>
    {{/result}}
    <li style="left: {{result._first.calc_1.value}}%" class="focus-tick"></li>
  </ul>
  <div class="tick-label max-label">{{result._first.calc_5.value}}</div>
</div>

<div class="footnote">52 week range</div>
```


# Cohort table
Source: https://docs.omni.co/showcase/visualizations/cohort-table

The code for this example can be used in the Markdown visualization to create a more condensed and styled cohort table for a year's worth of monthly cohorts.

The table includes the metric for each cohort over time as well as the size of each cohort.

<img alt="" />

## Setup

To build this chart you will need to structure your query with the cohorts as the rows and the time passed as the pivot. A calculation is used to pull the cohort size out of the pivot. Additional calculations are necessary to figure out how to color each cell. We'll also need the [column totals](/analyze-explore/point-click-queries#column-totals) enabled.

The following table explains each field used in the example, including the calculation formulas.

| Col | Name                     | Description or formula                                                                                                                                    | Purpose                                                                                                                                             |
| --- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| A   | Monthly cohort           | query field                                                                                                                                               | A row for each cohort, sorted with the oldest at the top                                                                                            |
| B   | Users Count              | query field                                                                                                                                               | Count of users in the cohort (inside pivot)                                                                                                         |
| C   | Customers                | =PIVOTOFFSET(B1, 0, 0)                                                                                                                                    | First column of users count is the size of the cohort                                                                                               |
| D   | Sales                    | query field                                                                                                                                               | Total sales for the cohort (inside pivot)                                                                                                           |
| E   | Sales (row max)          | =MAX(PIVOTROW(D1))                                                                                                                                        | Maximum sales value for the row - set total calculation to `maximum`                                                                                |
| F   | Sales (row non-zero min) | =IFERROR(MINIFS(PIVOTROW(D1), PIVOTROW(D1), ">0"), 0)                                                                                                     | Minimum non-zero value for the row. If row is all zeros, will set to 0. Set total calculation to `minimum`                                          |
| G   | pct                      | =(D1 - F\_TOTAL) / (E\_TOTAL - F\_TOTAL)                                                                                                                  | how close to the max value is the current cell - will be a value between 0 and 1 where 0 is the overall min sales value, 1 is the overall max value |
| H   | bucket                   | =IF(G1 \<= 0.167, "bucket1", IF(G1 \<= 0.333, "bucket2", IF(G1 \<= 0.5, "bucket3", IF(G1 \<= 0.667, "bucket4", IF(G1 \<= 0.833, "bucket5", "bucket6"))))) | string to identify bin for coloring                                                                                                                 |

Don't forget to [enable the column totals and adjust the total calculation](/analyze-explore/point-click-queries#column-totals) as follows:

* column D - Sales - to be `maximum`
* column E - Sales (row max) - to be `maximum`
* column F - Sales (row non-zero min) - to be `minimum`

<img alt="" />

## Example code

```html expandable theme={null}
<style>
.cohort-table {
  --header-color: var(--color-foreground2);
  --total-color: var(--color-border1);
  --empty-color: var(--color-foreground2);
  --cell-radius: 8px;
  border-spacing: 2px;
  width: 100%;

  & th {
    text-align: right;
    padding: 4px 8px;
    font-weight: 500;
  }

  & th.left-align {
    text-align: left;
  }

  & td {
    text-align: right;
    padding: 4px 8px;
  }

  & tbody th {
    background: var(--header-color);
    border-radius: var(--cell-radius);
    font-weight: normal;
  }

  & tfoot th {
    background: var(--total-color);
    border-radius: var(--cell-radius);
    font-weight: 500;
  }

  & tfoot td {
    background: var(--total-color);
    border-radius: var(--cell-radius);
  }

  & tbody td {
    background: transparent;
    border-radius: var(--cell-radius);
  }

  & tbody td.bucket1 { background: #F0E654ee; color: hsl(219deg 3% 3% / 85%); }
  & tbody td.bucket2 { background: #94D161ee; color: hsl(219deg 3% 3% / 85%); }
  & tbody td.bucket3 { background: #5DB27Fee; color: hsl(219deg 3% 3% / 85%); }
  & tbody td.bucket4 { background: #468C8Dee; color: hsl(180deg 0% 100% / 85%); }
  & tbody td.bucket5 { background: #40628Aee; color: hsl(180deg 0% 100% / 85%); }
  & tbody td.bucket6 { background: #423076ee; color: hsl(180deg 0% 100% / 85%); }

  /* blank out bottom right */
  & tbody {
    & tr:nth-of-type(2) td:nth-child(n+14) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(3) td:nth-child(n+13) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(4) td:nth-child(n+12) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(5) td:nth-child(n+11) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(6) td:nth-child(n+10) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(7) td:nth-child(n+9) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(8) td:nth-child(n+8) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(9) td:nth-child(n+7) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(10) td:nth-child(n+6) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(11) td:nth-child(n+5) { color: var(--empty-color); background: var(--empty-color); }
    & tr:nth-of-type(12) td:nth-child(n+4) { color: var(--empty-color); background: var(--empty-color); }
  }
}
</style>

<table class="cohort-table">
  <thead>
    <tr>
      <th class="left-align">Monthly Cohort</th>
      <th>Customers</th>
      <th>1st Month</th>
      <th>2nd Month</th>
      <th>3rd Month</th>
      <th>4th Month</th>
      <th>5th Month</th>
      <th>6th Month</th>
      <th>7th Month</th>
      <th>8th Month</th>
      <th>9th Month</th>
      <th>10th Month</th>
      <th>11th Month</th>
      <th>12th Month</th>
    </tr>
  </thead>
  <tbody>
    {{#result}}
    <tr>
      <th class="left-align">{{ecomm__users.created_at[month].value}}</th>
      <th>{{calc_1.value_static}}</th>
      <td class="{{0.1st Month.calc_5.raw}}">{{0.1st Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{1.2nd Month.calc_5.raw}}">{{1.2nd Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{2.3rd Month.calc_5.raw}}">{{2.3rd Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{3.4th Month.calc_5.raw}}">{{3.4th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{4.5th Month.calc_5.raw}}">{{4.5th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{5.6th Month.calc_5.raw}}">{{5.6th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{6.7th Month.calc_5.raw}}">{{6.7th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{7.8th Month.calc_5.raw}}">{{7.8th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{8.9th Month.calc_5.raw}}">{{8.9th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{9.10th Month.calc_5.raw}}">{{9.10th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{10.11th Month.calc_5.raw}}">{{10.11th Month.ecomm__order_items.sale_price_sum.value}}</td>
      <td class="{{11.12th Month.calc_5.raw}}">{{11.12th Month.ecomm__order_items.sale_price_sum.value}}</td>
    </tr>
    {{/result}}
  </tbody>
  <tfoot>
    <tr>
      <th class="left-align">Max</th>
      <td>{{result._totals.0.calc_1.value_static}}</td>
      <td>{{result._totals.0.0.1st Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.1.2nd Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.2.3rd Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.3.4th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.4.5th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.5.6th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.6.7th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.7.8th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.8.9th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.9.10th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.10.11th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
      <td>{{result._totals.0.11.12th Month.ecomm__order_items.sale_price_sum.value_static}}</td>
    </tr>
  </tfoot>
</table>
```


# Colored progress bars
Source: https://docs.omni.co/showcase/visualizations/colored-progress-bars

Create color-sectioned progress bar visualizations using Markdown in Omni to display current state with visual color cues.

The code for these examples can be used in the Markdown visualization to create progress bars that are sectioned by color to reinforce the meaning current progress state.

The progress bar visualization rounds to the nearest 5% but shows the exact value next to the bars.

## Fill to progress level

This style shows the unmet progress levels as unfilled, but with a border color to indicate the meaning of the level.

<img alt="" />

### Setup

This chart has a very simple structure - the current measurement, the target, and the necessary calculations to create the chart. Adjust your calculation as needed for your data, but make sure you use the % formatting on the "progress" column.

The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name                    | Description or formula    | Purpose                                          |
| --- | ----------------------- | ------------------------- | ------------------------------------------------ |
| A   | Total Sale Price        | Field measuring progress  |                                                  |
| B   | Target (`calc_1`)       | Goal or target            |                                                  |
| C   | Progress (`calc_2`)     | `=A1 / B1`                | % of target to goal - make sure formatted as a % |
| D   | Bars to fill (`calc_3`) | `=ROUND(C1 * 100 / 5, 0)` | Round to the number of bars to fill              |

### Example code

```html expandable theme={null}
<style>
ol.highlight-progress {
  --progress-padding: 3px;
  --progress-step-width: 12px;
  --progress-step-height: 56px;
  --color-bad-hsl: 343 100% 57.1%;
  --color-meh-hsl: 56 100% 57.1%;
  --color-good-hsl: 97 100% 39.6%;
  --color-bg-opacity: 0%;
  --color-border-opacity: 25%;

  list-style: none;
  margin: 0;
  padding: 0;
  background: var(--color-surface-invert);
  background: none;
  display: grid;
  grid-template-columns: repeat(20, var(--progress-step-width)) 1fr;
  gap: var(--progress-padding);
  border: calc(1.25 * var(--progress-padding)) solid var(--color-progress-bg);
  border-radius: 4px;

  & li {
    /* default is "good" */
    background: hsla(var(--color-good-hsl) / var(--color-bg-opacity));
    height: var(--progress-step-height);
    border: 1px solid hsla(var(--color-good-hsl) / var(--color-border-opacity));
  }

  & li:nth-child(-n + 13) {
    /* layer on "meh" */
    background: hsla(var(--color-meh-hsl) / var(--color-bg-opacity));
    border: 1px solid hsla(var(--color-meh-hsl) / var(--color-border-opacity));
  }

  & li:nth-child(-n + 5) {
    /* layer on "bad" */
    background: hsla(var(--color-bad-hsl) / var(--color-bg-opacity));
    border: 1px solid hsla(var(--color-bad-hsl) / var(--color-border-opacity));
  }

  & li:nth-child(-n + {{result._first.calc_3.value}}) {
    --color-bg-opacity: 50%;
  }

  & li.bar-first {
    border-radius: 4px 0 0 4px;
  }

  & li.bar-last {
    border-radius: 0 4px 4px 0;
  }

  & li.progress {
    background: transparent;
    padding-inline: 4px;
    display: flex;
    flex-direction: column;
    justify-content: center;
    border: 0;

    & span {
      font-size: var(--font-md);
      font-weight: bold;
    }
  }
}
</style>

<ol class="highlight-progress">
  <li class="bar-first"></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li class="bar-last"></li>
  <li class="progress"><span>{{result._first.calc_2.value}}</span> to {{result._first.calc_1.value}}</li>
</ol>
```

## Show unmet levels as faded

This style shows the unmet progress levels as solid, but semi-transparent. As the progress levels fill, they become bolder and opaque.

<img alt="" />

### Setup

The data in this example shows an inverted coloring, where low is good, as it is measuring the percentage of returned or cancelled orders. You can adjust the calculations and coloring to suit your use case, but make sure you use the % formatting on the "progress" column.

The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name                              | Description or formula    | Purpose                                              |
| --- | --------------------------------- | ------------------------- | ---------------------------------------------------- |
| A   | Order ID Count Distinct           | Total number of orders    | Denominator for progress calculation                 |
| B   | Count Returned                    | Number orders returned    | Part of the numerator for progress calculation       |
| C   | Count Cancelled                   | Number orders cancelled   | Other part of the numerator for progress calculation |
| D   | Return and Cancel Rate (`calc_1`) | `=(B1 + C1) / A1`         | % calculation for number returned or cancelled       |
| E   | Bars to fill (`calc_2`)           | `=ROUND(D1 * 100 / 5, 0)` | Round to the number of bars to fill                  |

### Example code

```html expandable theme={null}
<style>
ol.highlight-progress {
  --progress-padding: 3px;
  --progress-step-width: 12px;
  --progress-step-height: 56px;
  --color-bad-hsl: 343 100% 57.1%;
  --color-meh-hsl: 56 100% 57.1%;
  --color-good-hsl: 97 100% 39.6%;
  --color-bg-opacity: 15%;

  list-style: none;
  margin: 0;
  padding: 0;
  background: var(--color-surface-invert);
  background: none;
  display: grid;
  grid-template-columns: repeat(20, var(--progress-step-width)) 1fr;
  gap: var(--progress-padding);
  border: calc(1.25 * var(--progress-padding)) solid var(--color-progress-bg);
  border-radius: 4px;

  & li {
    /* default is "bad" */
    background: hsla(var(--color-bad-hsl) / var(--color-bg-opacity));
    height: var(--progress-step-height);
  }

  & li:nth-child(-n + 10) {
    /* layer on "meh" */
    background: hsla(var(--color-meh-hsl) / var(--color-bg-opacity));
  }

  & li:nth-child(-n + 3) {
    /* layer on "good" */
    background: hsla(var(--color-good-hsl) / var(--color-bg-opacity));
  }

  & li:nth-child(-n + {{result._first.calc_2.value}}) {
    --color-bg-opacity: 100%;
  }

  & li.progress {
    background: transparent;
    padding-inline: 4px;
    display: flex;
    flex-direction: column;
    justify-content: center;

    & span {
      font-size: var(--font-md);
      font-weight: bold;
    }
  }
}
</style>

<ol class="highlight-progress">
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li></li>
  <li class="progress"><span>{{result._first.calc_1.value}}</span>of orders cancelled or returned</li>
</ol>
```


# Dashboard tabs
Source: https://docs.omni.co/showcase/visualizations/dashboard-tabs

Markdown tiles can be used to create tabs in dashboards, allowing users to jump from one dashboard to another in internal or embedded scenarios.

<Note>
  **Looking for tabbed dashboard navigation?** The recommended approach is to use [Dashboard pages](/visualize-present/dashboards/pages), which provides built-in page tabs without custom HTML. The Markdown-based pattern below is still valid for scenarios where you need custom styling or are working in an embedded context.
</Note>

The links can be exact, or relative references (e.g. `/dashboards/<dashboard-id>`) and are contained in the `href` field of an `<a>` tag as seen below. This example has basic styling and only two tabs. Expand on it and add your own styles.

<img alt="Dashboard with two styled tab links for navigating between dashboards" />

## Example code

```html expandable theme={null}
<style>
.dash-tabs {
  display: flex;
  flex-direction: row;
  justify-content: center;
  width: 100%;
}

.dash-tabs a.tab {
  display: block;
  width: 100%;
  text-align: center;
  text-decoration: none;
  padding: 16px 32px;
  border-bottom: 1px solid var(--color-border1);
  background: var(--color-background-alt);
  color: var(--color-text3);
  font-size: var(--font-md);
}

.dash-tabs a.tab.active {
  background: var(--color-background);
  border: 1px solid var(--color-border1);
  border-bottom-color: var(--color-background);
  font-weight: 500;
  color: var(--text4)
}
</style>

<div class="dash-tabs">
  <a href="/dashboards/<dashboard-one-id>" class="tab active">
    Dash one
  </a>
  <a href="/dashboards/<dashboard-two-id>" class="tab">
    Dash two
  </a>
</div>
```


# Dashboard tile anchors (table of contents)
Source: https://docs.omni.co/showcase/visualizations/dashboard-tile-anchors

This example can be used in the Markdown visualization to create a linked table of contents.

[Markdown visualizations](/visualize-present/visualizations/types/markdown) and [dashboard Markdown text tiles](/visualize-present/dashboards/text-markdown) can include links to other tiles within the dashboard. This is a nice way to create a table of contents or "back to the top" links or buttons to help users move around a longer dashboard.

<iframe title="Dashboard Tile Anchors" />

## Linking to existing charts

Any HTML element with an `id` on the page can be referenced as an anchor point to jump to. Every chart tile on the dashboard has a unique ID that is based on the title of the tile. For example, if the title of your tile is `Top Performing Brands` the corresponding ID is `top-performing-brands` and you can reference that anchor point with a markdown link like this:

```markdown theme={null}
[Jump to brand analysis](#top-performing-brands)
```

or if you are writing HTML in the markdown editor, like this:

```html theme={null}
<a href="#top-performing-brands">Jump to brand analysis</a>
```

## Creating your own anchors

If you are making more complex HTML-based markdown tiles, you can also include IDs in your element tags. It's a bit more complex to reference these IDs in other markdown tiles. Because we sanitize the HTML and markdown for security, we replace all user-generated IDs with a `user-content-` prepended to the provided ID. For example, if you write this HTML:

```html theme={null}
<article id="brand-analysis">We sell lots of stuff!</article>
```

then you will need to reference it like this:

```html theme={null}
<a href="#user-content-brand-analysis">Jump to brand analysis</a>
```

<Tip>
  If you need help getting the ID for any element, you can also use your browser's code inspector to locate the element.
</Tip>

## Linking to another dashboard with filters and controls retained

A Markdown link can also jump to a different dashboard while carrying over the current dashboard's filter or control selections, instead of opening the destination with nothing applied.

### Filters

Reference the filter's JSON value with [Mustache](/visualize-present/mustache-reference), and pass it as the destination dashboard's own filter ID, prefixed with `f--`:

```html wrap title="Link to another dashboard, keeping a dashboard filter" theme={null}
<a href="/dashboards/sales-abc123?f--rW8-IWVU={{filters.8v_G12D7.json}}">Go to Sales dashboard</a>
```

`8v_G12D7` is the ID of the filter on the current dashboard, and `rW8-IWVU` is the ID of the filter on the destination dashboard. These are usually different values, since filter IDs are scoped to the dashboard they're created on. See [Locating keys](/visualize-present/mustache-reference#control_id-and-filter_id) for how to find a filter or control ID.

<Note>
  Use the `.json` element, not `.value_url_encoded`, for filter passthrough. `.json` carries the filter's full condition (its operator and values), which the destination filter applies to whatever field it's already configured for - so unlike controls, the source and destination don't need to reference the same field. `.value_url_encoded` only passes the bare value, which isn't enough for the destination to apply the filter correctly.
</Note>

### Controls

Controls use the `c--` prefix instead of `f--`. Reference the control's `value` or `value_url_encoded` element:

```html wrap title="Link to another dashboard, keeping a control" theme={null}
<a href="/dashboards/sales-abc123?c--8v_G12D7={{controls.rW8-IWVU.value_url_encoded}}">Go to Sales dashboard</a>
```

<Warning>
  Control passthrough only works when the destination control is built on the exact same field as the current dashboard's control. If the two dashboards pull the control from a different view or field, the destination dashboard won't recognize the value and will load with no control value applied.

  It's also limited to controls that hold a single field or value selection - field switcher, time frame switcher, parent controls, and Top N limit. Multi-field picker, period over period, and dynamic filter controls aren't supported this way.
</Warning>

## Example code

The following example references the video at the top of the page.

### Anchor/header tiles

Each of the 3 colorful headers in the above example serve as anchor destinations to navigate to. For this example, each hading has been created using a separate markdown visualization in the workbook, each titled to match the text inside the heading.

<img alt="" />

```html expandable title="Example code for the 'Overview' heading" theme={null}
<style>
.md-card {
  display: flex;
  background: linear-gradient(
    132deg,
    #8eecd5 2.13%,
    #9DAAF4 67.53%,
    #F7A8CB 90%
  );
  padding: var(--size4);
  border-radius: var(--radius-md);
  color: var(--color-text-inverse);
  justify-content: center;
  height: 100%;
  align-items: center;
  margin-block: 0;
}
</style>

<h1 class="md-card">Overview</h1>
```

### Table of contents

Use a dashboard Markdown text tile to create the table of contents:

```html expandable theme={null}
<style>
a {
  color: #E40473;
  text-decoration: none;
  font-size: 14px;
  border-radius: 10px;
  border: 2px solid #D3D3D3;
  margin-left: auto;
  padding: 10px;
  margin-right: 10px;
}

.navbar {
  background-color: #;
  padding: 30px;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.right {
  display: block;
  position: absolute;
}
</style>

<nav class="navbar">
  <span style="color:#E40473;padding: 15px;font-size: 20px;">Sections: </span>
  <a href="#overview">Overview</a>
  <a href="#organic-marketing">Organic Marketing - Detail</a>
  <a href="#paid-marketing">Paid Marketing - Detail</a>
</nav>
<hr style="border: none; border-bottom: 2px solid #FF1493; margin: 0; width: 100%; padding-top: 15px">
```


# Data readout
Source: https://docs.omni.co/showcase/visualizations/data-readout

Build a sparkline with descriptive text using Markdown visualization in Omni, referencing live query values in the results set.

The code for this example can be used in the Markdown visualization to create a sparkline visualization with a description. The description uses  to reference values in the results set.

<img alt="" />

## Example code

```html wrap theme={null}
In the past 12 months, Acme Corp has had **{{result._totals._first.order_items.order_count.value}}** orders made by **{{result._totals._first.users.count.value}}** users, resulting in **{{result._totals._first.order_items.sale_price_sum.value}}** total revenue.<br><br><Sparkline field="order_items.order_count" color="#ED6C91" height=70% width=100% reverse=true></Sparkline>
```


# Dumbbell plot
Source: https://docs.omni.co/showcase/visualizations/dumbbell-plot

The code for this example can be used in the Markdown visualization to create a table of dumbbell charts.

Sometimes called barbell plots or connected dot plots, these charts are good for comparing related data points across a category. This example was inspired by charts in the results of the [2025 Stack Overflow Survey](https://survey.stackoverflow.co/2025/technology#admired-and-desired).

<img alt="" />

## Setup

These charts use the Mustache iterator syntax to draw a chart for each row in the results. Your query should have a column with the category label for each dumbbell that you want to display along with the start and end values for each category. Additionally, you'll need a calculation to get the length of the bar.

**Note:** This example only covers a positive change between start and end values. You'll need to make some adjustments if the change you are measuring can also be negative.

The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name               | Description or formula | Purpose                        |
| --- | ------------------ | ---------------------- | ------------------------------ |
| A   | Database           | query field            | Label of the category          |
| B   | Desired Percentage | query field            | start (left) value of dumbbell |
| C   | Admired Percentage | query field            | end (right) value of dumbbell  |
| D   | bar width          | =C1 - B1               | Length of the bar              |

## Example code

```html expandable theme={null}
<style>
h3 {
  margin-top: 0;
}

.dumbbell-plot-table {
  --start-color: #0891F2;
  --end-color: #F1434B;
  --dot-radius: 5px;
  --dot-diameter: calc(var(--dot-radius) * 2);
  --label-width: 7ch;
  --line-opacity: 0.25;
  --border-style: 1px dotted color-mix(in srgb, var(--color-border1), transparent 0%);

  list-style: none;
  margin: 0;
  padding: 0;
  display: grid;
  grid-template-columns: min-content 1fr;
  width: 100%;
}

.dumbbell-plot-table h4 {
  white-space: nowrap;
  margin: 0;
  font-size: var(--font-xs);
  border-bottom: var(--border-style);
}

.dumbbell-plot-table section.dumbbell-plot-wrapper {
  padding-inline: var(--label-width);
  border-bottom: var(--border-style);
}

ul.dumbbell-plot {
  position: relative;
  margin: 0;
  padding: 0;
  list-style: none;
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: row;
  gap: 0;
  align-items: center;

  & li.dot-label {
    position: absolute;
    width: var(--label-width);
    display: flex;
    flex-direction: row;
    align-items: center;
    gap: 4px;
    font-size: var(--font-xxs);
    font-weight: 500;
  }

  & li.dot-start {
    justify-content: flex-end;
    color: var(--start-color);

    & span.dot {
      background-color: var(--start-color);
    }
  }

  & li.dot-end {
    justify-content: flex-start;
    color: var(--end-color);

    & span.dot {
      background-color: var(--end-color);
    }
  }

  & li .dot {
    display: inline-block;
    width: var(--dot-diameter);
    height: var(--dot-diameter);
    border-radius: 50%;
    flex: 0 0 var(--dot-diameter);
  }

  & li.dot-span {
    position: absolute;
    background: magenta;
    display: flex;
    flex-direction: column;
    justify-content: space-around;
    opacity: var(--line-opacity);

    & span.line {
      display: block;
      height: var(--dot-radius);
      background-image: linear-gradient(to right, var(--start-color), var(--end-color));
      width: 100%;
    }
  }
}

ul.dumbbell-plot-legend {
  list-style: none;
  margin: 0;
  padding: 12px 0;
  display: flex;
  flex-direction: row;
  gap: 16px;
  font-size: var(--font-xs);
  font-weight: 500;
  grid-column: 1 / 2;

  & li {
    display: flex;
    flex-direction: row;
    gap: 6px;
    align-items: center;
  }

  & .dumbbell-plot-legend-dot {
    width: 10px;
    height: 10px;
    background-color: pink;
    display: block;
    border-radius: 50%;
  }

  & .dumbbell-plot-legend-dot.start {
    background-color: var(--start-color);
  }

  & .dumbbell-plot-legend-dot.end {
    background-color: var(--end-color);
  }
}
</style>

<h3>Databases Dumbbell Plot from Stack Overflow</h3>
<p>As seen in the <a href="https://survey.stackoverflow.co/2025/technology#admired-and-desired">2025 Stack Overflow Admired/Desired charts</a>. From their site: To better gauge hype versus reality, we created a visualization that shows the distance between the proportion of respondents who want to use a technology ("desired") and the proportion of users that have used the same technology in the past year and want to continue using it ("admired").</p>

<article class="dumbbell-plot-table">
  {{#result}}
  <h4>{{stackoverflow_databases.database.value}}</h4>
  <section class="dumbbell-plot-wrapper">
    <ul class="dumbbell-plot">
      <li class="dot-span" style="left:{{stackoverflow_databases.desired_percentage.value_static}}%; width: {{calc_1.value_static}}%;"><span class="line"></span></li>
      <li class="dot-label dot-start" style="left: calc({{stackoverflow_databases.desired_percentage.value_static}}% - var(--label-width) + var(--dot-radius))"><span class="label">{{stackoverflow_databases.desired_percentage.value}}%</span><span class="dot"></span></li>
      <li class="dot-label dot-end" style="left:calc({{stackoverflow_databases.admired_percentage.value_static}}% - var(--dot-radius));"><span class="dot"></span><span clas="label">{{stackoverflow_databases.admired_percentage.value}}%</span></li>
    </ul>
  </section>
  {{/result}}
  <ul class="dumbbell-plot-legend">
    <li><span class="dumbbell-plot-legend-dot start"></span>Desired</li>
    <li><span class="dumbbell-plot-legend-dot end"></span>Admired</li>
  </ul>
</article>
```


# Gauges
Source: https://docs.omni.co/showcase/visualizations/gauge

Create gauge and speedometer chart visualizations using Markdown in Omni to show where a value falls within a defined range.

The code for these examples can be used in the Markdown visualization to create gauges, or speedometer charts, that show where a single value falls in a predefined range.

## Basic gauge

<img alt="" />

### Example code

```html expandable theme={null}
<style>
.gauge-chart {
  /* colors */
  --track-color: var(--color-border1);
  --fill-color: var(--color-info);
  --mask-color: var(--color-background);
  /* dimensions */
  --chart-size: 400px;
  --minmax-offset: var(--size2);
  --track-width-ratio: .70;
  --track-size: var(--chart-size);
  --mask-track-size: calc(var(--track-size) * var(--track-width-ratio));
  /* values */
  --fill-rotation: calc({{result._first.calc_5.value}} * 180deg);
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: var(--size1);
  height: 100%;
}

.gauge-wrapper {
  width: var(--chart-size);
  height: calc(var(--chart-size) / 2);
  overflow: hidden;
}

.gauge {
  width: var(--chart-size);
  height: var(--chart-size);
  position: relative;
  list-style: none;
  margin: 0;
  padding: 0;

  & .center {
    border-radius: 50%;
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }

  & .track {
    background-color: var(--track-color);
    width: var(--track-size);
    height: var(--track-size);
  }

  & .fill {
    width: var(--track-size);
    height: var(--track-size);
    background-image: conic-gradient(
      from -90deg,
      var(--fill-color) var(--fill-rotation),
      transparent 0);
  }

  & .mask {
    background-color: var(--mask-color);
    width: var(--mask-track-size);
    height: var(--mask-track-size);
  }

  & .metric {
    position: absolute;
    bottom: 50%;
    text-align: center;
    width: 100%;

    & .metric-label {
      padding: 0;
      margin: 0;
    }

    & .metric-value {
      padding: 0;
      margin: 0;
      line-height: 1;
      font-size: 56px;
      font-weight: 500;
    }
  }
}

.footer {
  width: var(--chart-size);
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  color: var(--color-text1);

  & p {
    --label-width: calc(calc(1 - var(--track-width-ratio)) * var(--chart-size) / 2);
    width: var(--label-width);
    text-align: center;
    margin: 0;
  }
}

.legend {
  width: var(--chart-size);
  display: flex;
  flex-direction: row;
  font-size: var(--font-xs);
  align-items: center;
  justify-content: center;
  gap: var(--size1);
  color: var(--color-text1);
  padding-top: var(--size1);

  & p {
    margin: 0;
  }
}
</style>

<div class="gauge-chart">
  <div class="gauge-wrapper">
    <ul class="gauge">
      <li class="center track"></li>
      <li class="center fill"></li>
      <li class="center mask"></li>
      <li class="metric">
        <p class="metric-label">{{fields.order_items.total_sale_price.label}}</p>
        <p class="metric-value">{{result._first.order_items.total_sale_price.value}}</p>
      </li>
    </ul>
  </div>
  <div class="footer">
    <p>$0</p>
    <p>{{result._first.calc_4.value}}</p>
  </div>
</div>
```

## Gauge with context

<img alt="" />

### Setup

This markdown in this example references a lot of calculations to position and style elements. Below is a screenshot of the query as a reference.

<img alt="" />

### Example code

```html expandable theme={null}
<style>
.gauge-chart {
  /* colors */
  --track-color: var(--color-border1);
  --fill-color: var(--color-info);
  --mask-color: var(--color-background);
  --minmax-color: color-mix(in srgb, var(--fill-color) 30%, transparent);
  --avg-color: color-mix(in srgb, var(--fill-color), black 40%);
  /* dimensions */
  --chart-size: 400px;
  --minmax-offset: var(--size2);
  --track-width-ratio: .70;
  --minmax-outer-size: var(--chart-size);
  --track-size: calc(var(--chart-size) - 2 * var(--minmax-offset));
  --mask-track-size: calc(var(--track-size) * var(--track-width-ratio));
  --minmax-inner-size: var(--mask-track-size);
  --mask-minmax-size: calc(var(--minmax-inner-size) - 2 * var(--minmax-offset));
  /* values */
  --fill-rotation: calc({{result._first.calc_5.value}} * 180deg);
  --min-rotation: calc({{result._first.calc_6.value}} * 180deg);
  --avg-rotation: calc({{result._first.calc_8.value}}* 180deg);
  --max-rotation: calc({{result._first.calc_7.value}} * 180deg);
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: var(--size1);
  height: 100%;
}

.gauge-wrapper {
  width: var(--chart-size);
  height: calc(var(--chart-size) / 2);
  overflow: hidden;
}

.gauge {
  width: var(--chart-size);
  height: var(--chart-size);
  position: relative;
  list-style: none;
  margin: 0;
  padding: 0;

  & .center {
    border-radius: 50%;
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }

  & .track {
    background-color: var(--track-color);
    width: var(--track-size);
    height: var(--track-size);
  }

  & .fill {
    width: var(--track-size);
    height: var(--track-size);
    background-image: conic-gradient(
      from -90deg,
      var(--fill-color) var(--fill-rotation),
      transparent 0);
  }

  & .minmax {
    border-radius: 50%;
    background-image: conic-gradient(
      from -90deg,
      transparent var(--min-rotation),
      var(--minmax-color) var(--min-rotation),
      var(--minmax-color) var(--avg-rotation),
      var(--avg-color) var(--avg-rotation),
      var(--avg-color) calc(var(--avg-rotation) + .5deg),
      var(--minmax-color) calc(var(--avg-rotation) + .5deg),
      var(--minmax-color) var(--max-rotation),
      transparent 0);
  }

  & .minmax.minmax-outer {
    width: var(--minmax-outer-size);
    height: var(--minmax-outer-size);
  }

  & .minmax.minmax-inner {
    width: var(--minmax-inner-size);
    height: var(--minmax-inner-size);
  }

  & .mask {
    background-color: var(--mask-color);
  }

  & .mask.mask-track {
    width: var(--mask-track-size);
    height: var(--mask-track-size);
  }

  & .mask.mask-minmax {
    width: var(--mask-minmax-size);
    height: var(--mask-minmax-size);
  }

  & .metric {
    position: absolute;
    bottom: 50%;
    text-align: center;
    width: 100%;

    & .metric-label {
      padding: 0;
      margin: 0;
    }

    & .metric-value {
      padding: 0;
      margin: 0;
      line-height: 1;
      font-size: 48px;
      color: var(--fill-color);
      font-weight: 500;
    }
  }
}

.footer {
  width: var(--chart-size);
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  color: var(--color-text1);

  & p {
    --label-width: calc(calc(1 - var(--track-width-ratio)) * var(--chart-size) / 2);
    width: var(--label-width);
    text-align: center;
    margin: 0;
  }
}

.legend {
  width: var(--chart-size);
  display: flex;
  flex-direction: row;
  font-size: var(--font-xs);
  align-items: center;
  justify-content: center;
  gap: var(--size1);
  color: var(--color-text1);
  padding-top: var(--size1);

  & p {
    margin: 0;
  }

  & .legend-title {
    padding-right: var(--size4);
  }

  & .legend-avg {
    margin-left: var(--size6);
    width: var(--size05);
    height: var(--size4);
    background-color: var(--avg-color);
  }

  & .legend-minmax {
    width: var(--size4);
    height: var(--size4);
    background-color: var(--minmax-color);
    display: inline-block;
  }
}
</style>

<div class="gauge-chart">
  <div class="gauge-wrapper">
    <ul class="gauge">
      <li class="center track"></li>
      <li class="center fill"></li>
      <li class="center minmax minmax-outer"></li>
      <li class="center mask mask-track"></li>
      <li class="center minmax minmax-inner"></li>
      <li class="center mask mask-minmax"></li>
      <li class="metric">
        <p class="metric-label">{{fields.order_items.total_sale_price.label}}</p>
        <p class="metric-value">{{result._first.order_items.total_sale_price.value}}</p>
      </li>
    </ul>
  </div>
  <div class="footer">
    <p>$0</p>
    <p>{{result._first.calc_4.value}}</p>
  </div>
  <div class="legend">
    <p class="legend-title">Last 7 days</p>
    <p class="legend-minmax"></p>
    <p class="legend-value">
      {{result._first.calc_2.value}} min &mdash; {{result._first.calc_3.value}} max
    </p>
    <p class="legend-avg"></p>
    <p class="legend-value">{{result._first.calc_1.value}} avg</p>
  </div>
</div>
```


# Gradient card with metrics
Source: https://docs.omni.co/showcase/visualizations/gradient-card

The code for this example can be used in the Markdown visualization to create a full-width card with a gradient background and multiple metrics.

<img alt="" />

## Example code

```html expandable theme={null}
<style>
.md-card {
  display: flex;
  background: linear-gradient(
    132deg,
    #8eecd5 2.13%,
    #9DAAF4 67.53%,
    #F7A8CB 90%
  );
  padding: var(--size4);
  border-radius: var(--radius-md);
  color: var(--color-text-inverse);
  justify-content: center;
  height: 100%;
  align-items: center;
}

.md-card-metrics {
  display: flex;
  flex-direction: column;
  gap: var(--size4);
  margin: 0;
  padding: 0;
  list-style: none;
  width: 100%;
  align-items: center;
  justify-content: center;
}

.md-card-metrics li {
  padding-block: var(--size4);
  padding-inline: var(--size6);
  display: grid;
  grid-template-columns: max-content 1fr;
  width: 100%;
}

@media (width >= 769px) {
  .md-card-metrics {
    flex-direction: row;
  }

  .md-card-metrics li {
    max-width: calc(4px * 70);
  }
}

.md-metric-emoji {
  font-size: 52px;
  color: var(--color-text-inverse);
  margin: 0;
  grid-row: 1 / 3;
  display: flex;
  align-items: center;
  padding-inline: 0 var(--size4);
}

.md-metric-label {
  font-size: 14px;
  color: var(--color-text-inverse);
  opacity: 0.66;
}

.md-metric-value {
  font-size: 36px;
  line-height: 1;
  font-weight: bold;
}
</style>

<div class="md-card">
  <ul class="md-card-metrics">
    <li>
      <div class="md-metric-emoji">
        <svg width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M9.75736 5.75736C10.8826 4.63214 12.4087 4 14 4C15.5913 4 17.1174 4.63214 18.2426 5.75736C19.3679 6.88258 20 8.4087 20 10C20 11.5913 19.3679 13.1174 18.2426 14.2426C17.1174 15.3679 15.5913 16 14 16C12.4087 16 10.8826 15.3679 9.75736 14.2426C8.63214 13.1174 8 11.5913 8 10C8 8.4087 8.63214 6.88258 9.75736 5.75736ZM14 8C13.4696 8 12.9609 8.21071 12.5858 8.58579C12.2107 8.96086 12 9.46957 12 10C12 10.5304 12.2107 11.0391 12.5858 11.4142C12.9609 11.7893 13.4696 12 14 12C14.5304 12 15.0391 11.7893 15.4142 11.4142C15.7893 11.0391 16 10.5304 16 10C16 9.46957 15.7893 8.96086 15.4142 8.58579C15.0391 8.21071 14.5304 8 14 8ZM29.7574 5.75736C30.8826 4.63214 32.4087 4 34 4C35.5913 4 37.1174 4.63214 38.2426 5.75736C39.3679 6.88258 40 8.4087 40 10C40 11.5913 39.3679 13.1174 38.2426 14.2426C37.1174 15.3679 35.5913 16 34 16C32.4087 16 30.8826 15.3679 29.7574 14.2426C28.6321 13.1174 28 11.5913 28 10C28 8.4087 28.6321 6.88258 29.7574 5.75736ZM34 8C33.4696 8 32.9609 8.21071 32.5858 8.58579C32.2107 8.96086 32 9.46957 32 10C32 10.5304 32.2107 11.0391 32.5858 11.4142C32.9609 11.7893 33.4696 12 34 12C34.5304 12 35.0391 11.7893 35.4142 11.4142C35.7893 11.0391 36 10.5304 36 10C36 9.46957 35.7893 8.96086 35.4142 8.58579C35.0391 8.21071 34.5304 8 34 8ZM10 22C9.46957 22 8.96086 22.2107 8.58579 22.5858C8.21071 22.9609 8 23.4696 8 24V26C8 27.1046 7.10457 28 6 28C4.89543 28 4 27.1046 4 26V24C4 22.4087 4.63214 20.8826 5.75736 19.7574C6.88258 18.6321 8.4087 18 10 18H14C15.1046 18 16 18.8954 16 20C16 21.1046 15.1046 22 14 22H10ZM32 20C32 18.8954 32.8954 18 34 18H38C39.5913 18 41.1174 18.6321 42.2426 19.7574C43.3679 20.8826 44 22.4087 44 24V26C44 27.1046 43.1046 28 42 28C40.8954 28 40 27.1046 40 26V24C40 23.4696 39.7893 22.9609 39.4142 22.5858C39.0391 22.2107 38.5304 22 38 22H34C32.8954 22 32 21.1046 32 20ZM19.7574 21.7574C20.8826 20.6321 22.4087 20 24 20C25.5913 20 27.1174 20.6321 28.2426 21.7574C29.3679 22.8826 30 24.4087 30 26C30 27.5913 29.3679 29.1174 28.2426 30.2426C27.1174 31.3679 25.5913 32 24 32C22.4087 32 20.8826 31.3679 19.7574 30.2426C18.6321 29.1174 18 27.5913 18 26C18 24.4087 18.6321 22.8826 19.7574 21.7574ZM24 24C23.4696 24 22.9609 24.2107 22.5858 24.5858C22.2107 24.9609 22 25.4696 22 26C22 26.5304 22.2107 27.0391 22.5858 27.4142C22.9609 27.7893 23.4696 28 24 28C24.5304 28 25.0391 27.7893 25.4142 27.4142C25.7893 27.0391 26 26.5304 26 26C26 25.4696 25.7893 24.9609 25.4142 24.5858C25.0391 24.2107 24.5304 24 24 24ZM20 38C19.4696 38 18.9609 38.2107 18.5858 38.5858C18.2107 38.9609 18 39.4696 18 40V42C18 43.1046 17.1046 44 16 44C14.8954 44 14 43.1046 14 42V40C14 38.4087 14.6321 36.8826 15.7574 35.7574C16.8826 34.6321 18.4087 34 20 34H28C29.5913 34 31.1174 34.6321 32.2426 35.7574C33.3679 36.8826 34 38.4087 34 40V42C34 43.1046 33.1046 44 32 44C30.8954 44 30 43.1046 30 42V40C30 39.4696 29.7893 38.9609 29.4142 38.5858C29.0391 38.2107 28.5304 38 28 38H20Z" fill="currentColor"/>
        </svg>
      </div>
      <div class="md-metric-value">{{result.0.dbt_czima__users.count.value}}</div>
      <div class="md-metric-label">People using data better</div>
    </li>
    <li>
      <div class="md-metric-emoji">
        <svg width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M24 4C25.1046 4 26 4.89543 26 6V8C26 9.10457 25.1046 10 24 10C22.8954 10 22 9.10457 22 8V6C22 4.89543 22.8954 4 24 4ZM9.78579 9.78579C10.5668 9.00474 11.8332 9.00474 12.6142 9.78579L14.0142 11.1858C14.7953 11.9668 14.7953 13.2332 14.0142 14.0142C13.2332 14.7953 11.9668 14.7953 11.1858 14.0142L9.78579 12.6142C9.00474 11.8332 9.00474 10.5668 9.78579 9.78579ZM38.2142 9.78578C38.9953 10.5668 38.9953 11.8332 38.2142 12.6142L36.8142 14.0142C36.0332 14.7953 34.7668 14.7953 33.9858 14.0142C33.2047 13.2332 33.2047 11.9668 33.9858 11.1858L35.3858 9.78579C36.1668 9.00474 37.4332 9.00474 38.2142 9.78578ZM24 16C22.3209 16 20.6844 16.5283 19.3223 17.5101C17.9602 18.4918 16.9415 19.8773 16.4105 21.4702C15.8796 23.0631 15.8633 24.7827 16.3639 26.3853C16.8645 27.988 17.8568 29.3926 19.2 30.4C19.273 30.4547 19.3422 30.5144 19.407 30.5786C19.8455 31.0127 20.2368 31.4892 20.5755 32H27.4245C27.7632 31.4892 28.1545 31.0127 28.593 30.5786C28.6578 30.5144 28.727 30.4547 28.8 30.4C30.1432 29.3926 31.1355 27.988 31.6361 26.3853C32.1367 24.7827 32.1204 23.0631 31.5895 21.4702C31.0585 19.8773 30.0398 18.4918 28.6777 17.5101C27.3156 16.5283 25.6791 16 24 16ZM30.3316 34.9988C30.3871 34.9027 30.4348 34.8016 30.4739 34.6962C30.6967 34.2612 30.9826 33.86 31.3232 33.5063C33.2756 32.0024 34.7186 29.9328 35.4542 27.578C36.2051 25.174 36.1806 22.5946 35.3842 20.2053C34.5878 17.8159 33.0597 15.7377 31.0165 14.2651C28.9733 12.7924 26.5186 12 24 12C21.4814 12 19.0267 12.7924 16.9835 14.2651C14.9403 15.7377 13.4122 17.8159 12.6158 20.2053C11.8194 22.5946 11.7949 25.174 12.5458 27.578C13.2814 29.9328 14.7244 32.0024 16.6768 33.5063C17.012 33.8544 17.2942 34.2483 17.5153 34.6753C17.5584 34.7955 17.6127 34.9104 17.6769 35.0186C17.7291 35.1415 17.7765 35.2666 17.8189 35.3937C18.0671 36.1382 18.1365 36.9307 18.0216 37.7071C18.0072 37.8041 18 37.902 18 38C18 39.5913 18.6321 41.1174 19.7574 42.2426C20.8826 43.3679 22.4087 44 24 44C25.5913 44 27.1174 43.3679 28.2426 42.2426C29.3679 41.1174 30 39.5913 30 38C30 37.902 29.9928 37.8041 29.9784 37.7071C29.8635 36.9307 29.9329 36.1382 30.1811 35.3937C30.2258 35.2597 30.276 35.128 30.3316 34.9988ZM25.9775 36H22.0225C22.0989 36.7007 22.0929 37.41 22.0032 38.1131C22.0309 38.6023 22.2375 39.0659 22.5858 39.4142C22.9609 39.7893 23.4696 40 24 40C24.5304 40 25.0391 39.7893 25.4142 39.4142C25.7625 39.0659 25.9691 38.6023 25.9968 38.1131C25.9071 37.41 25.9011 36.7007 25.9775 36ZM4 24C4 22.8954 4.89543 22 6 22H8C9.10457 22 10 22.8954 10 24C10 25.1046 9.10457 26 8 26H6C4.89543 26 4 25.1046 4 24ZM38 24C38 22.8954 38.8954 22 40 22H42C43.1046 22 44 22.8954 44 24C44 25.1046 43.1046 26 42 26H40C38.8954 26 38 25.1046 38 24Z" fill="currentColor"/>
        </svg>
      </div>
      <div class="md-metric-value">{{result.0.dbt_czima__query_history.count.value}}</div>
      <div class="md-metric-label">Questions asked</div>
    </li>
    <li>
      <div class="md-metric-emoji">
        <svg width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M9.85786 9.85786C13.6086 6.10714 18.6957 4 24 4C29.3043 4 34.3914 6.10714 38.1421 9.85786C41.8929 13.6086 44 18.6957 44 24C44 26.6264 43.4827 29.2272 42.4776 31.6537C41.4725 34.0802 39.9993 36.285 38.1421 38.1421C36.285 39.9993 34.0802 41.4725 31.6537 42.4776C29.2272 43.4827 26.6264 44 24 44C21.3736 44 18.7728 43.4827 16.3463 42.4776C13.9198 41.4725 11.715 39.9993 9.85786 38.1421C8.00069 36.285 6.5275 34.0802 5.52241 31.6537C4.51732 29.2272 4 26.6264 4 24C4 18.6957 6.10714 13.6086 9.85786 9.85786ZM24 8C19.7565 8 15.6869 9.68571 12.6863 12.6863C9.68571 15.6869 8 19.7565 8 24C8 26.1012 8.41385 28.1817 9.21793 30.1229C10.022 32.0641 11.2006 33.828 12.6863 35.3137C14.172 36.7994 15.9359 37.978 17.8771 38.7821C19.8183 39.5861 21.8988 40 24 40C26.1012 40 28.1817 39.5861 30.1229 38.7821C32.0641 37.978 33.828 36.7994 35.3137 35.3137C36.7994 33.828 37.978 32.0641 38.7821 30.1229C39.5861 28.1817 40 26.1012 40 24C40 19.7565 38.3143 15.6869 35.3137 12.6863C32.3131 9.68571 28.2435 8 24 8ZM24 12C25.1046 12 26 12.8954 26 14V23.1716L31.4142 28.5858C32.1953 29.3668 32.1953 30.6332 31.4142 31.4142C30.6332 32.1953 29.3668 32.1953 28.5858 31.4142L22.5858 25.4142C22.2107 25.0391 22 24.5304 22 24V14C22 12.8954 22.8954 12 24 12Z" fill="currentColor"/>
        </svg>
      </div>
      <div class="md-metric-value">{{result.0.dbt_czima__query_history.minutes_of_usage.value}}</div>
      <div class="md-metric-label">Minutes spent analyzing</div>
    </li>
  </ul>
</div>
```


# Honeycomb categorical chart
Source: https://docs.omni.co/showcase/visualizations/honeycomb-categorical

The code for this example can be used in the Markdown visualization to create a hexagonal grid with a label and value in each cell.

Cells are colored by a categorical value, in this case by the gender majority per age. This chart uses the Mustache iterator syntax to draw a shape for each row in the results.

<img alt="" />

## Setup

Your query should have a dimension that determines the number of hexagons, their labels and some way to determine color. The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col   | Name                                 | Description or formula                                                   | Purpose                                                |
| ----- | ------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------ |
| A     | Age                                  | query field                                                              | determines number of hexagons to make and their labels |
| B     | Determine Gender Majority (`calc_1`) | =IF(PIVOTOFFSET(C1, 0, 0) - PIVOTOFFSET(C1, 0, 1) > 0, "female", "male") | more male or female calculation                        |
| C     | Users Count                          | query field                                                              | values to count                                        |
| Pivot | Gender                               | query field                                                              | breakdown                                              |

## Example code

```html expandable theme={null}
<style>
h3 {
  margin-block: 0;
}

h4 {
  margin-top: 0;
  color: var(--color-text1);
  font-size: var(--font-sm);
}

.honeycomb2 {
  --hc-width: 60px;
  --hc-height: calc(1.1547 * var(--hc-width)); /* 1.1547 ~= 2/sqrt(3) */
  --hc-gap: 8px;
  /* calculate width based on # of cells you want per row
     will also need to adjust the css below for offsets */
  width: calc(12.5 * var(--hc-width) + 12 * var(--hc-gap));
  margin: 0;
  padding: 0;
  list-style: none;
  display: flex;
  flex-wrap: wrap;
  flex-direction: row;
  gap: 0 var(--hc-gap);

  & li {
    width: var(--hc-width);
    height: var(--hc-height);
    margin: 0;
    padding: 0;
    display: flex;
    background-color: var(--color-border1);
    clip-path: polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);
    display: grid;
    grid-template-rows: 1fr 1fr;
    margin-top: calc(var(--hc-height) / -6);

    & .hex-label {
      text-align: center;
      font-size: 12px;
      width: 100%;
    }

    & .hex-value {
      display: flex;
      flex-direction: column;
      justify-content: flex-end;
      align-items: center;
      font-size: 16px;
      font-weight: bold;
    }
  }

  & li.female {
    background-color: var(--color-critical4);
  }

  & li.male {
    background-color: var(--color-info4);
  }

  /* # of cells */
  & li:nth-of-type(12n + 1) {
    margin-left: calc(var(--hc-width) / 2 + var(--hc-gap) / 2);
  }

  & li:first-of-type,
  & li:nth-of-type(24n + 1) {
    margin-left: 0;
  }

  & li:nth-of-type(-n + 12) {
    margin-top: 0;
  }
}
</style>

<h3>Are there more male or female shoppers?</h3>
<h4>Broken down by age of shopper</h4>

<ul class="honeycomb2">
  {{#result}}
  <li class="{{calc_1.value}}">
    <span class="hex-value">{{users.age.value}}</span>
    <span class="hex-label">{{calc_1.value}}</span>
  </li>
  {{/result}}
</ul>
```


# Honeycomb map
Source: https://docs.omni.co/showcase/visualizations/honeycomb-map

The code for this example can be used in the Markdown visualization to create a stylized map of the United States.

<img alt="" />

## Setup

This example requires your data be sorted alphabetically by state name, as individual cell positions are referenced to set the cell color. This dataset did not, unfortunately, include Hawaii.

Depending on your data, you may need to manually adjust cell references to ensure that the value for coloring is correctly assigned.

<img alt="" />

| Col | Name                         | Description or formula                                                                                                                            |
| --- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| A   | State                        | must be sorted A to Z                                                                                                                             |
| B   | Users Count                  | value for color coding                                                                                                                            |
| C   | Categorize values (`calc_1`) | =IF(B1 > (0.8 \* MAX(B:B)), "p80", IF(B1 > (0.6 \* MAX(B:B)), "p60", IF(B1 > (0.4 \* MAX(B:B)), "p40", IF(B1 > (0.2 \* MAX(B:B)), "p20", "p0")))) |

## Example code

```html expandable theme={null}
<style>
.honeycomb {
  --hc-width: 40px;
  --hc-height: calc(1.1547 * var(--hc-width)); /* 1.1547 ~= 2/sqrt(3) */
  --hc-gap: 4px;
  width: 552px;
  margin: 0 auto;
  padding: 0;
  list-style: none;
  display: flex;
  flex-direction: column;

  & li {
    margin: 0;
    padding: 0;
    display: flex;
    gap: var(--hc-gap);
    margin-top: calc(var(--hc-height) / -6);
  }

  & li:nth-of-type(2n) {
    margin-left: calc(var(--hc-width) / 2 + var(--hc-gap) / 2);
  }

  & li:first-of-type {
    margin-top: 0;
  }

  & .hex {
    box-sizing: content-box;
    width: var(--hc-width);
    height: var(--hc-height);
    clip-path: polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);
    display: flex;
    justify-content: center;
    align-items: center;
    text-align: center;
    font-size: 16px;
    font-weight: bold;
    text-transform: uppercase;
    background-color: var(--color-border1);
  }

  & .hex:empty {
    background-color: transparent;
  }

  & li.hc-legend {
    margin-top: 0;
    padding-block: var(--size8) var(--size2);
    gap: var(--size6);
    justify-content: center;

    & > div {
      display: flex;
      flex-direction: row;
      gap: var(--size2);
      align-items: center;
      font-size: var(--font-xs);
    }

    & .hc-legend-swatch {
      display: block;
      border-radius: var(--radius-sm);
      width: var(--size4);
      height: var(--size4);
    }
  }

  & .p80 { background-color: #44337D; color: white; }
  & .p60 { background-color: #306C8C; color: white; }
  & .p40 { background-color: #219D8A; color: white; }
  & .p20 { background-color: #63C960; color: #333; }
  & .p0 { background-color: #D7E225; color: #333; }
  & .nodata { background-color: var(--color-border2); }
}
</style>

<ul class="honeycomb">
  <li id="row1">
    <div class="hex {{result.1.calc_1.value}}">AK</div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex {{result.18.calc_1.value}}">ME</div>
  </li>
  <li id="row2">
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex {{result.44.calc_1.value}}">VT</div>
    <div class="hex {{result.28.calc_1.value}}">NH</div>
  </li>
  <li id="row3">
    <div class="hex"></div>
    <div class="hex {{result.46.calc_1.value}}">WA</div>
    <div class="hex {{result.25.calc_1.value}}">MT</div>
    <div class="hex {{result.33.calc_1.value}}">ND</div>
    <div class="hex {{result.22.calc_1.value}}">MN</div>
    <div class="hex {{result.48.calc_1.value}}">WI</div>
    <div class="hex"></div>
    <div class="hex {{result.21.calc_1.value}}">MI</div>
    <div class="hex"></div>
    <div class="hex {{result.31.calc_1.value}}">NY</div>
    <div class="hex {{result.20.calc_1.value}}">MA</div>
    <div class="hex {{result.38.calc_1.value}}">RI</div>
  </li>
  <li id="row4">
    <div class="hex"></div>
    <div class="hex {{result.11.calc_1.value}}">ID</div>
    <div class="hex {{result.49.calc_1.value}}">WY</div>
    <div class="hex {{result.40.calc_1.value}}">SD</div>
    <div class="hex {{result.14.calc_1.value}}">IA</div>
    <div class="hex {{result.12.calc_1.value}}">IL</div>
    <div class="hex {{result.13.calc_1.value}}">IN</div>
    <div class="hex {{result.34.calc_1.value}}">OH</div>
    <div class="hex {{result.37.calc_1.value}}">PA</div>
    <div class="hex {{result.29.calc_1.value}}">NJ</div>
    <div class="hex {{result.6.calc_1.value}}">CT</div>
    <div class="hex"></div>
  </li>
  <li id="row5">
    <div class="hex"></div>
    <div class="hex {{result.36.calc_1.value}}">OR</div>
    <div class="hex {{result.27.calc_1.value}}">NV</div>
    <div class="hex {{result.5.calc_1.value}}">CO</div>
    <div class="hex {{result.26.calc_1.value}}">NE</div>
    <div class="hex {{result.24.calc_1.value}}">MO</div>
    <div class="hex {{result.16.calc_1.value}}">KY</div>
    <div class="hex {{result.47.calc_1.value}}">WV</div>
    <div class="hex {{result.9.calc_1.value}}">DC</div>
    <div class="hex {{result.19.calc_1.value}}">MD</div>
    <div class="hex {{result.7.calc_1.value}}">DE</div>
    <div class="hex"></div>
  </li>
  <li id="row6">
    <div class="hex"></div>
    <div class="hex {{result.4.calc_1.value}}">CA</div>
    <div class="hex {{result.43.calc_1.value}}">UT</div>
    <div class="hex {{result.30.calc_1.value}}">NM</div>
    <div class="hex {{result.15.calc_1.value}}">KS</div>
    <div class="hex {{result.3.calc_1.value}}">AR</div>
    <div class="hex {{result.41.calc_1.value}}">TN</div>
    <div class="hex {{result.39.calc_1.value}}">SC</div>
    <div class="hex {{result.32.calc_1.value}}">NC</div>
    <div class="hex {{result.45.calc_1.value}}">VA</div>
    <div class="hex"></div>
    <div class="hex"></div>
  </li>
  <li id="row7">
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex {{result.2.calc_1.value}}">AZ</div>
    <div class="hex {{result.36.calc_1.value}}">OK</div>
    <div class="hex {{result.17.calc_1.value}}">LA</div>
    <div class="hex {{result.23.calc_1.value}}">MS</div>
    <div class="hex {{result.1.calc_1.value}}">AL</div>
    <div class="hex {{result.10.calc_1.value}}">GA</div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
  </li>
  <li id="row8">
    <div class="hex nodata">HI</div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex {{result.42.calc_1.value}}">TX</div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex {{result.9.calc_1.value}}">FL</div>
    <div class="hex"></div>
    <div class="hex"></div>
    <div class="hex"></div>
  </li>
  <li class="hc-legend">
    <div><span class="hc-legend-swatch p80"></span><span class="hc-legend-label">Most</span></div>
    <div><span class="hc-legend-swatch p60"></span><span class="hc-legend-label">More</span></div>
    <div><span class="hc-legend-swatch p40"></span><span class="hc-legend-label">Medium</span></div>
    <div><span class="hc-legend-swatch p20"></span><span class="hc-legend-label">Less</span></div>
    <div><span class="hc-legend-swatch p0"></span><span class="hc-legend-label">Least</span></div>
    <div><span class="hc-legend-swatch nodata"></span><span class="hc-legend-label">No data</span></div>
  </li>
</ul>
```


# Image grid
Source: https://docs.omni.co/showcase/visualizations/image-grid

The code for this example can be used in the Markdown visualization to create a grid of images, each of which contains a description and metric.

<img alt="" />

## Example code

```html expandable theme={null}
<style>
  .product-image-grid  {
  display: grid;
  grid-template-columns: repeat(3, 98px);
  gap: 7px;
  }
  .product-image-item  {
  display: flex;
  flex-direction: column;
  gap: 7px;
  }
  .product-image  {
  background-size: cover;
  background-position: center;
  height: 100px;
  position: relative;
  }
  .product-rank-number  {
  padding: 2px;
  position: absolute;
  top: 0;
  left: 0;
  background: var(--color-surface-invert);
  color: var(--color-text-inverse);
  }
  .product-name  {
  font-size: 10px;
  margin: 0;
  }
  .product-compare  {
  align-items: center;
  display: flex;
  font-size: 11px;
  gap: 8px;
  font-weight: 500;
  }
</style>
### Top Products This Month

<div class="product-image-grid">{{#result}}
<div class="product-image-item">
  <section class="product-image" style="background-image: url(https://{{product_images.image.value_static}})">
  <p class="product-rank-number">{{sale_price_sum_rank.value}}</p>
</section>
<section class="product-compare"> {{order_items.sale_price_sum.value_static}}<ChangeArrow current="{{order_items.sale_price_sum.value_static}}" comparison="{{order_items.sale_price_sum_1.value_static}}"></ChangeArrow>
</section>
<p class="product-name">{{products.name.value_static}}</p>
</div>{{/result}}
</div>
```


# Invoice report
Source: https://docs.omni.co/showcase/visualizations/invoice-report

The code for these examples can be used in the Markdown visualization to create a structured invoice, complete with contact information and order details.

<img alt="" />

## Example code

```html expandable theme={null}
# Invoice
<img src="https://i.etsystatic.com/21003174/r/il/a9dfd6/4600341262/il_fullxfull.4600341262_kno3.jpg" style="width: 100px"/>

---------------------------------------

    Invoice Number: {{result.0.order_items.user_id.value_static}}
    Name: {{result.0.users.full_name.value_static}}
    Contact: {{result.0.users.full_name.value_static}} • {{result.0.users.email.value_static}}


### Order Summary

<table>
<thead>
<tr>
<th>Order ID</th>
<th>Order Date</th>
<th>Item Count</th>
<th>Total</th>
</tr>
</thead>
<tbody>
{{#result}}
<tr>
<td> {{order_items.order_id.value}} </td>
<td> {{order_items.created_at[date].value}} </td>
<td> {{order_items.count.value}} </td>
<td> {{order_items.sale_price_sum.value}} </td>
</tr>
{{/result}}
</tbody>
</table>


**Grand Total**: {{result.totals.first.order_items.sale_price_sum.value}} (no tax)
<br><br>
### Terms

+ Payments are to be made payable to Initech via Paypal[^1] or Direct Deposit[^2].
+ Grand Total must be paid by the end of [DATE] (30 days).
+ If Grand Total is not paid by the end of [DATE], a late-fee[^3] will be applied to the Grand Total.

[^1]: Paypal e-mail address for payments is <payments@initech.com>.
[^2]: Please contact if you wish to do a Direct Deposit.
[^3]: Late-fee of *2%* interest per-day until paid.
```


# Kanban
Source: https://docs.omni.co/showcase/visualizations/kanban

The code for this example can be used in the Markdown visualization to create a Kanban-style project board.

In this example, each card on the board represents a company in the dataset.

<img alt="" />

## Example query

<img alt="" />

## Example dataset

<img alt="" />

## Example code

```html expandable theme={null}
<style>
  /* Base styling */
  body {
    font-family: 'Inter', sans-serif;
    margin: 0;
    padding: 20px;
    background-color: #F4F5F7;
  }
  
  /* Kanban table styling */
  .kanban-table {
    width: 100%;
    border-collapse: separate;
    border-spacing: 15px 0;
    margin-bottom: 20px;
  }
  
  .kanban-table th {
    background-color: #F4F5F7;
    color: #5D5FEF;
    font-size: 18px;
    padding: 10px;
    text-align: center;
    border-bottom: 2px solid #5D5FEF;
    border-radius: 8px 8px 0 0;
  }
  
  .kanban-table td {
    padding: 10px;
    vertical-align: top;
    background-color: #FAFAFA;
    border-radius: 0 0 8px 8px;
  }
  
  /* Card styling */
  .kanban-card {
    background-color: white;
    border-radius: 10px;
    border-left: 4px solid #5D5FEF;
    box-shadow: 0 2px 4px rgba(0,0,0,0.08);
    padding: 12px;
    margin-bottom: 15px;
    position: relative;
  }
  
  .card-title {
    font-weight: bold;
    font-size: 16px;
    margin-bottom: 8px;
    color: #2C2F77;
    padding-right: 70px; /* Make room for the image */
  }
  
  .card-description {
    font-size: 14px;
    color: #333;
    margin-bottom: 10px;
  }
  
  .card-metrics {
    display: flex;
    justify-content: space-between;
    font-size: 12px;
    color: #666;
    border-top: 1px solid #eee;
    padding-top: 8px;
  }
  
  .card-image {
    position: absolute;
    top: 12px;
    right: 12px;
    width: 60px;
    height: 60px;
    border-radius: 8px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  }
  
  /* Tag styling */
  .tag {
    display: inline-block;
    background-color: #5D5FEF25;
    color: #2C2F77;
    font-size: 11px;
    padding: 3px 8px;
    border-radius: 12px;
    margin-right: 5px;
    margin-bottom: 5px;
  }
  
  /* Priority indicators */
  .priority-one {
    border-left-color: #ff4d4d;
  }
  
  .priority-two {
    border-left-color: #ffb84d;
  }
  
  .priority-three {
    border-left-color: #4da6ff;
  }
  </style>

<!-- <h1 style="color: #191970; text-align: center;">Project Kanban Board</h1> -->  
<table class="kanban-table">
    <thead>
      <tr>
        <th>Sales Ready</th>
        <th>Trial</th>
        <th>Closed Won</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          {{#result}}
          {{#Sales Ready.opptys.opportunity_name_list.value}}
          <!-- Static examples representing how the template would render -->
          <div class="kanban-card priority-high">
            <div class="card-title">{{Sales Ready.opptys.opportunity_name_list.value}}</div>
            <div class="card-description">{{Sales Ready.opptys.arr_sum.value}}</div>
            <div><span class="tag">{{Sales Ready.opptys.type_list.value}}</span> </div>
            <div class="card-metrics">
              <span>Owner: {{Sales Ready.opptys.account_owner_list.value}}</span>
              <span>Close Date: {{Sales Ready.opptys.close_date_date_max.value_static}}</span>
            </div>
            <img class="card-image" src="{{Sales Ready.opptys.logo_list.value_static}}" alt="Company logo">
          </div>
          {{/Sales Ready.opptys.opportunity_name_list.value}}
          {{/result}}
        </td>
        <td>
          {{#result}}
          {{#Trial.opptys.opportunity_name_list.value}}
          <!-- Static examples representing how the template would render -->
          <div class="kanban-card priority-high">
            <div class="card-title">{{Trial.opptys.opportunity_name_list.value}}</div>
            <div class="card-description">{{Trial.opptys.arr_sum.value}}</div>
            <div><span class="tag">{{Trial.opptys.type_list.value}}</span> </div>
            <div class="card-metrics">
              <span>Owner: {{Trial.opptys.account_owner_list.value}}</span>
              <span>Close Date: {{Trial.opptys.close_date_date_max.value_static}}</span>
            </div>
            <img class="card-image" src="{{Trial.opptys.logo_list.value_static}}" alt="Company logo">
          </div>
          {{/Trial.opptys.opportunity_name_list.value}}
          {{/result}}
        </td>
        <td>
          {{#result}}
          {{#Closed Won.opptys.opportunity_name_list.value}}
          <!-- Static examples representing how the template would render -->
          <div class="kanban-card priority-high">
            <div class="card-title">{{Closed Won.opptys.opportunity_name_list.value}}</div>
            <div class="card-description">{{Closed Won.opptys.arr_sum.value}}</div>
            <div><span class="tag">{{Closed Won.opptys.type_list.value}}</span> </div>
            <div class="card-metrics">
              <span>Owner: {{Closed Won.opptys.account_owner_list.value}}</span>
              <span>Close Date: {{Closed Won.opptys.close_date_date_max.value_static}}</span>
            </div>
            <img class="card-image" src="{{Closed Won.opptys.logo_list.value_static}}" alt="Company logo">
          </div>
          {{/Closed Won.opptys.opportunity_name_list.value}}
          {{/result}}
        </td>
      </tr>
    </tbody>
  </table>
```


# KPI conditional colors
Source: https://docs.omni.co/showcase/visualizations/kpi-conditional-colors

The code for this example can be used in the Markdown visualization to apply conditional color styling to KPI charts.

This example shows a KPI chart with dynamic color styling using the Markdown visualization.

<img alt="Three KPI charts with conditional colors" />

## Setup

This pattern uses a SQL `CASE` statement to assign a label based on the value of a metric. That label is then referenced in the Markdown as a CSS class to control styling.

For example:

```sql theme={null}
CASE
  WHEN ${kpi_conditional_color.metric_value} < 0 THEN 'negative'
  WHEN ${kpi_conditional_color.metric_value} = 0 THEN 'neutral'
  WHEN ${kpi_conditional_color.metric_value} > 0 THEN 'positive'
END AS metric_class
```

Which would look like this in the workbook query:

<img alt="Conditional values in workbook query results" />

## Example code

```html theme={null}
<style>
.kpi-visualization.negative {
  color: red;
}

.kpi-visualization.positive {
  color: green;
}

.kpi-visualization.neutral {
  color: gray;
}
</style>

<div class="kpi-visualization kpi-vertical-center {{result._first.kpi_conditional_color.metric_class.raw}}">
  <div class="kpi-markdown-wrapper kpi-align-center">
    <single-value label="Metric Value">
      <span>{{result._first.kpi_conditional_color.metric_value.value}}</span>
    </single-value>
  </div>
</div>
```


# KPI table
Source: https://docs.omni.co/showcase/visualizations/kpi-table

The code for this example can be used in the Markdown visualization to create a table of KPIs.

In this example, each column is specific to a different source (ex: `email`).

<img alt="" />

## Example code

```html theme={null}
<table>
<thead>
<tr>
<th>Display</th>
<th>Email</th>
<th>Facebook</th>
<th>Organic</th>
<th>Search</th>
</tr>
</thead>
<tbody>
<tr>
<td>**{{result.0.Display.users.count.value}} Users**<br>
<ChangeArrow current="{{result.0.Display.users.count.value_static}}" comparison="{{result.1.Display.users.count.value_static}}"></ChangeArrow> (last month {{result.1.Display.users.count.value}})</td>
<td>**{{result.0.Email.users.count.value}} Users**<br>
<ChangeArrow current="{{result.0.Email.users.count.value_static}}" comparison="{{result.1.Email.users.count.value_static}}"></ChangeArrow> (last month {{result.1.Email.users.count.value_static}})</td>
<td>**{{result.0.Facebook.users.count.value}} Users**<br>
<ChangeArrow current="{{result.0.Facebook.users.count.value_static}}" comparison="{{result.1.Facebook.users.count.value_static}}"></ChangeArrow> (last month {{result.1.Facebook.users.count.value_static}})</td>
<td>**{{result.0.Organic.users.count.value}} Users**<br>
<ChangeArrow current="{{result.0.Organic.users.count.value_static}}" comparison="{{result.1.Organic.users.count.value_static}}"></ChangeArrow> (last month {{result.1.Organic.users.count.value}})</td>
<td>**{{result.0.Search.users.count.value}} Users**<br>
<ChangeArrow current="{{result.0.Search.users.count.value_static}}" comparison="{{result.1.Search.users.count.value_static}}"></changearrow> (last month {{result.1.Search.users.count.value}})</td>
</tr>
<tr>
<td> <Sparkline field="Display.users.count" color="cornflowerblue" reverse="true" height="80%"></Sparkline></td>
<td> <Sparkline field="Email.users.count" color="MediumSeaGreen" reverse="true" height="80%"/></td>
<td> <Sparkline field="Facebook.users.count" color="gold" reverse="true" height="80%"/></td>
<td> <Sparkline field="Organic.users.count" color="darkorange" reverse="true" height="80%"/></td>
<td> <Sparkline field="Search.users.count" color="crimson" reverse="true" height="80%"/></td>
</tr>
</tbody>
</table>
```


# KPI with sparkline
Source: https://docs.omni.co/showcase/visualizations/kpi-with-sparkline

The code for this example can be used in the Markdown visualization to create a KPI-style visualization with a sparkline and change arrow.

<img alt="" />

## Example code

```html theme={null}
<div style="display:flex; align-items: center; justify-content:center; flex-direction: column;">
<div style="display:flex; align-items: center;flex-direction:column;">
###**{{result._first.users.count.value}}** Users this Month

<p style="font-size: var(--font-sm);"> <ChangeArrow current="{{result.0.users.count.value_static}}" comparison="{{result.1.users.count.value_static}}"></ChangeArrow> last month from {{result.1.users.count.value}}
</p>
</div>
<Sparkline field="users.count" color="#4889DE" height=50% width=70% reverse=true></Sparkline>
</div>
```


# Card list
Source: https://docs.omni.co/showcase/visualizations/list-view

The code for this example can be used in the Markdown visualization to card list view:

<img alt="" />

## Example query

<img alt="" />

## Example code

```html theme={null}
<style>
  .contact-entry {
    display: flex;
    align-items: flex-start;
    background: #f9f9f9;
    padding: 12px;
    margin-bottom: 8px;
    border-radius: 12px;
    gap: 12px;
  }

  .contact-avatar {
    width: 40px;
    height: 40px;
    border-radius: 50%;
    object-fit: cover;
    flex-shrink: 0;
  }

  .contact-info b {
    display: block;
    font-size: 16px;
    margin-bottom: 4px;
  }

  .contact-info .line {
    font-size: 14px;
    color: #333;
    margin-bottom: 2px;
  }

  .contact-info a {
    font-size: 14px;
    color: #007AFF;
    word-break: break-word;
    text-decoration: none;
  }
</style>

{{#result}}<div class="contact-entry"><img class="contact-avatar" src="https://ui-avatars.com/api/?name={{people.full_name.value_static}}&background=random" alt="Avatar" /><div class="contact-info"><b>{{people.full_name.value}}</b><div class="line">{{people.title.value_static}} - {{people.practice_group.value_static}}</div><div class="line"><a href="mailto:{{people.email.value_static}}">{{people.email.value_static}}</a></div><div class="line"><a href="tel:{{people.office_phone_number.value_static}}">{{people.office_phone_number.value_static}}</a></div></div></div>{{/result}}
```


# Location with national flag
Source: https://docs.omni.co/showcase/visualizations/location-with-national-flag

The code for this example can be used in a Markdown column to display a location alongside its national flag.

This example uses a Markdown column to display a location next to its national flag in a [table](/visualize-present/visualizations/types/table). The flag image is loaded from [flagcdn.com](https://flagcdn.com) using a two-letter country code.

<img alt="A table column showing each location next to its national flag, such as a flag beside Vienna, Montreal, and Stockholm" />

## Setup

To display a flag, you need a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (for example, `at`, `ca`, `se`, `us`) that can be passed into the flag image URL. You can provide this code in a few ways:

* Enter the code manually in an [input column](/analyze-explore/input-columns)
* Use a calculation with `XLOOKUP` to map locations to codes from another table
* Reference a field that already contains the code in your database

Set the column you want to display to **Display as** **Markdown**, then hide the helper code column so only the combined location renders.

The template references the country code as `{{calc_1.value}}` and the `location` field from the `saas__users_detailed` view. Update these references to match your own fields.

| Col | Name                    | Description or formula                                | Purpose                        |
| --- | ----------------------- | ----------------------------------------------------- | ------------------------------ |
| A   | Location                | Location field                                        | Label shown next to the flag   |
| B   | Country code (`calc_1`) | Two-letter country code (e.g. `at`, `ca`, `se`, `us`) | Passed into the flag image URL |

## Example code

**Markdown template**:

```handlebars wrap theme={null}
<div style="display:flex; align-items:center; gap:6px;">
  <img src="https://flagcdn.com/w20/{{calc_1.value}}.png" style="height:14px; border-radius:2px;">
  <span>{{saas__users_detailed.location.value}}</span>
</div>
```

**CSS styles**:

No custom CSS is required for this example, so you can leave the **CSS style** field empty.


# Metric tree
Source: https://docs.omni.co/showcase/visualizations/metric-tree

The code for this example can be used in the Markdown visualization to create a tree of interdependent metrics.

<img alt="" />

## Setup

This tree is highly customized to this exact tree shape. If you're willing to dig into some HTML/CSS it could be massaged to some other examples as well.

It also leverages Omni's sparkline component to draw the tiny chart. Below is the results set of sample data used to draw this tree.

<img alt="" />

## Example code

```html theme={null}
<style>
  .metric-tree {
  --node-gap: 20px;
  --node-width: 80px;
  --double-node-width: calc(var(--node-width) * 2 + var(--node-gap));
  --connector-color: var(--color-border2);
  --connector-style: solid;
  --connector-width: 1px;
  --connector-radius: 4px;
  --connector-height: 48px;
  list-style: none;
  margin: 0;
  padding: var(--size1);
  display: flex;
  flex-direction: column;

  & li {
    display: grid;
    justify-content: center;
    box-sizing: content-box;
  }
  & li.level1 {
    grid-template-columns: var(--double-node-width);
  }
  & li.level2 {
    grid-template-columns: repeat(3, var(--double-node-width));
  }
  & li.level3 {
    grid-template-columns: repeat(4, var(--double-node-width));
  }
  & li.level4 {
    grid-template-columns: repeat(5, var(--double-node-width));
  }
  & li.lines.level1 {
    grid-template-columns: calc(var(--double-node-width) * 2);
  }
  & li.lines.level2 {
    grid-template-columns: repeat(3, var(--double-node-width));
  }
  & li.lines.level3 {
    grid-template-columns: repeat(4, var(--double-node-width));
  }
  & li.lines .line {
    height: var(--connector-height);
    position: relative;
  }
  & li.lines .line .line-before {
    content: "";
    width: var(--connector-width);
    height: 50%;
    background: var(--connector-color);
    position: absolute;
    left: calc(50% - var(--connector-width));
  }
  & li.lines .line .line-after {
    content: "";
    border-color: var(--connector-color);
    border-style: var(--connector-style);
    border-width: var(--connector-width) var(--connector-width) 0px
      var(--connector-width);
    border-radius: var(--connector-radius) var(--connector-radius) 0 0;
    position: absolute;
    width: calc(100% - var(--connector-width));
    height: 50%;
    bottom: 0;
    left: calc(var(--connector-width) * -1);
  }
}
.metric-tree article.node {
  margin-inline: var(--node-gap);
  display: flex;
  flex-direction: column;
  justify-content: flex-end;
  border-color: var(--color-border1);
  border-radius: var(--connector-radius);
  border-width: 0;
  border-style: var(--connector-style);
  & .header {
    display: flex;
    flex-direction: column;
    padding: var(--size2);
  }
  & .graph {
    display: flex;
    flex-direction: row;
    justify-content: center;
    align-items: flex-end;
  }
}
.metric-tree {
  & h4 {
    padding: 0; 
    margin: 0; 
    text-align: center;
    display: none;
  }
  & h2 {
    padding: 0; 
    margin: 0; 
    text-align: center;
    font-size: var(--font-lg);
    line-height: 1.2;
  }
  & h3 {
    padding: 0; 
    margin: 0; 
    text-align: center;
    font-size: var(--font-sm);
    line-height: 1.2;
    color: var(--color-text1);
  }
}
.disclaimer {
  padding: 24px;
  width: 620px;
  margin: 0 auto;
  color: var(--color-text1);
  text-align: center;
} 
</style>
<ul class="metric-tree">
  <li class="level1">
    <article class="node">
      <div class="header">
        <h3>{{fields.calc_1.label}}</h3>
        <h4>Our most important metric</h4>
        <h2>{{result._totals._first.calc_1.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="calc_1" height="60" width="150" type="area" color="#78A851" show-axis=""></sparkline>
      </div>
    </article>
  </li>
  <li class="level1 lines">
    <div class="line"><span class="line-before"></span><span class="line-after"></span></div>
  </li>
  <li class="level2">
    <article class="node">
      <div class="header">
        <h3>{{fields.order_items.total_sale_price.label}}</h3>
        <h4>Money from customers</h4>
        <h2>{{result._totals._first.order_items.total_sale_price.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="order_items.total_sale_price" height="40" width="150" type="area" color="#5D6471" show-axis=""></sparkline>
      </div>
    </article>
    <article class="empty"></article>
    <article class="node">
      <div class="header">
        <h3>{{fields.inventory_items.cost_sum.label}}</h3>
        <h4>Money we pay out</h4>
        <h2>{{result._totals._first.inventory_items.cost_sum.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="inventory_items.cost_sum" height="40" width="150" type="area" color="#FF6161" show-axis=""></sparkline>
      </div>
    </article>
  </li>
  <li class="level2 lines">
    <div class="line"><span class="line-before"></span><span class="line-after"></span></div>
    <article class="empty"></article>
    <div class="line"><span class="line-before"></span><span class="line-after"></span></div>
  </li>
  <li class="level3">
    <article class="node">
      <div class="header">
        <h3>{{fields.users.count.label}}</h3>
        <h4>that actually purchased stuff</h4>
        <h2>{{result._totals._first.users.count.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="users.count" height="40" width="150" type="bar" color="#5D6471" show-axis=""></sparkline>
      </div>
    </article>
    <article class="node">
      <div class="header">
        <h3>{{fields.order_items.sale_price_average.label}}</h3>
        <h4>per order</h4>
        <h2>{{result._totals._first.order_items.sale_price_average.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="order_items.sale_price_average" height="40" width="150" type="line" color="#5D6471" show-axis=""></sparkline>
      </div>
    </article>
    <article class="node">
      <div class="header">
        <h3>{{fields.calc_2.label}}</h3>
        <h4>What it took to make the stuff</h4>
        <h2>{{result._totals._first.calc_2.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="calc_2" height="40" width="150" type="bar" color="#FF6161" show-axis=""></sparkline>
      </div>
    </article>
    <article class="node">
      <div class="header">
        <h3>{{fields.calc_3.label}}</h3>
        <h4>Cost to move stuff around</h4>
        <h2>{{result._totals._first.calc_3.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="calc_3" height="40" width="150" type="bar" color="#FF6161" show-axis=""></sparkline>
      </div>
    </article>
  </li>
  <li class="level3 lines">
    <div class="line"><span class="line-before"></span><span class="line-after"></span></div>
  </li>
  <li class="level4">
    <article class="node">
      <div class="header">
        <h3>{{fields.calc_4.label}}</h3>
        <h4>to our website</h4>
        <h2>{{result._totals._first.calc_4.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="calc_4" height="40" width="150" type="bar" color="#5D6471" show-axis=""></sparkline>
      </div>
    </article>
    <article class="node">
      <div class="header">
        <h3>{{fields.calc_5.label}}</h3>
        <h4>Description</h4>
        <h2>{{result._totals._first.calc_5.value}}</h2>
      </div>
      <div class="graph">
        <sparkline field="calc_5" height="40" width="150" type="line" color="#5D6471" show-axis=""></sparkline>
      </div>
    </article>
  </li>
</ul>
<P class="disclaimer">This tree is highly customized to basically this exact metric tree shape. If you're willing to dig into some html/css it could be massaged to some other examples as well.</P>
```


# Pie or donut with custom legend
Source: https://docs.omni.co/showcase/visualizations/pie-donut-custom-legend

The code for this example can be used in the Markdown visualization to create a pie or donut chart with a customized legend.

<img alt="" />

## Setup

Use this sample dataset and code to recreate this example in your own instance.

1. [Download the sample CSV](https://github.com/exploreomni/doc-sample-data/blob/main/visualizations/pie.csv).
2. Upload the sample CSV to your instance. Refer to the [Data input tables guide](/analyze-explore/data-input-csvs#adding-a-data-input-table-to-a-workbook) for instructions.
3. In a new query tab, select all the dimensions. Every field except `Pie Count` should be selected when you're finished.
4. On the **Results** tab, open the **Options** panel and enable [column totals](/analyze-explore/point-click-queries#column-totals).
5. In the `Session Count` totals cell, click the **...** menu and select **Total Calculation > Sum**.
6. Format the `Percent Of Total` column to **percentage** and adjust the decimal places to your liking.

Your query should look like this:

<img alt="" />

**Note:** To recreate this with your own data set, you'll need to create calculations for `Percent of Total`, `Slice Size`, and `Start Rotation`. These formulas reference the columns as they are in the above screenshot:

* `Percent of Total` - `=B1 / SUM(B:B)`
* `Slice Size` - `=B1 / SUM(B:B) * 360 // or Percent of Total * 360`
* `Start Rotation` - `=SUM(D$1:D1)` // The sum of all the previous values of `Slice Size` - if you are copying this formula, enter it on the second row to get it to apply correctly

Click **Chart** and select the **Markdown** chart type. Copy and paste the sample code below into the Markdown editor.

## Example code

```html expandable theme={null}
<style>
  .pie-card {
    /* ----- variables to customize ----- */
    --chart-size: 200px; /* diameter of the pie */
    --hole-color: var(--color-background); /* color of the donut hole, if used */
    --hole-width-ratio: .5; /* 0 to 1 for size of donut hole: 0=pie, 0.9 is a very skinny donut */ 

    width: 100%;
    height: 100%;
    display: grid;
    grid-template-columns: var(--chart-size) 1fr;
    gap: var(--size8);
  }
  .pie {
    --hole-size: calc(var(--chart-size) * var(--hole-width-ratio));
    width: var(--chart-size);
    height: var(--chart-size);
    position: relative;
    list-style: none;
    margin: 0;
    padding: 0;

    & .center {
      border-radius: 50%;
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
    }
    & .fill {
      width: var(--chart-size);
      height: var(--chart-size); 
    }
    & .mask {
      background-color: var(--hole-color);
      width: var(--hole-size);
      height: var(--hole-size);
    }
    & .title {
      font-size: var(--font-lg);
    }
  }
  .pie-legend {
    display: flex;
    flex-direction: column;
    gap: var(--size6);

    & ul, & li {
      margin: 0;
      padding: 0;
      list-style: none;
    }
    & ul {
      display: grid;
      grid-template-columns: 1fr 1fr 1fr;
      gap: var(--size4);
    }
    & h2, & h3 {
      margin: 0;
      padding: 0;
      display: flex;
      gap: 0;
      flex-direction: column;
      font-weight: normal;
    }
    & h2 {
      font-size: var(--font-lg);
      & .pie-label {
        font-size: var(--font-sm);
        line-height: var(--line-height-sm);
        color: var(--color-text2);
      }
    }
    & h3 {
      font-size: var(--font-md);
      border-left-width: 4px;
      border-left-style: solid;
      padding-left: var(--size3);
      
      & .pie-label {
        font-size: var(--font-xs);
        line-height: var(--line-height-xs);
        color: var(--color-text2);

        & .pie-percent {
          opacity: 0.5;
        }
      }
    }
  }
</style>
<article class="pie-card">
  <ul class="pie">
    {{#result}}
    <li class="center fill" style="background-image: conic-gradient(from {{pie.start_rotation.value_static}}deg, {{pie.slice_color.value_static}} {{pie.slice_size.value_static}}deg, transparent 0)"></li>
    {{/result}}
    <li class="center mask"></li>
  </ul>
  <div class="pie-legend">
    <h2><span class="pie-value">{{result._totals._first.pie.session_count.value}}</span><span class="pie-label">Total sessions</span></h2>
    <ul>
      {{#result}}
      <li><h3 style="border-left-color: {{pie.slice_color.value_static}}"><span class="pie-value">{{pie.session_count.value}}</span><span class="pie-label">{{pie.browser.value}}&nbsp;<span class="pie-percent">• {{pie.percent_of_total.value}}</span></span></h3></li>
      {{/result}}
    </ul>
  </div>
</article>
```


# Pills
Source: https://docs.omni.co/showcase/visualizations/pills

The code for this example can be used in a Markdown column to display category values as color-coded pills.

This example uses a Markdown column to display a category value as a color-coded pill in a [table](/visualize-present/visualizations/types/table). The field's value is used as a CSS class name, and the CSS defines a background color, text color, and rounded shape for each possible value.

<img alt="A table column showing each user's role as a color-coded pill: a green Builder pill, a purple Viewer pill, a red Admin pill, and a yellow Analyst pill" />

## Setup

In the table visualization, select the column you want to format and set **Display as** to **Markdown**. Then add the Markdown template and CSS below.

The template sets the field's value as the `class` of a `<div>` so that the matching CSS rule controls its appearance. Add one CSS class for each possible value in your data—in this example, `Builder`, `Viewer`, `Analyst`, and `Admin`. The class names must match the values exactly, so this pattern works best for fields with a small, fixed set of values that don't contain spaces or special characters.

This example references the `role` field from the `saas__users_detailed` view using [Mustache syntax](/visualize-present/mustache-reference). Replace these references with your own field.

## Example code

**Markdown template**:

```handlebars wrap theme={null}
<div class={{saas__users_detailed.role.value}}>{{saas__users_detailed.role.value}}</div>
```

**CSS styles**:

```css expandable theme={null}
.Viewer {
  background-color: #ede9fe;
  color: #6d28d9;
  border-radius: 20px;
  text-align: center;
}
.Builder {
  background-color: #d1fae5;
  color: #059669;
  border-radius: 20px;
  text-align: center;
}
.Analyst {
  background-color: #fef3c7;
  color: #d97706;
  border-radius: 20px;
  text-align: center;
}
.Admin {
  background-color: #ffe4e6;
  color: #e11d48;
  border-radius: 20px;
  text-align: center;
}
```


# Record lookup
Source: https://docs.omni.co/showcase/visualizations/record-lookup

The code for this example can be used in the Markdown visualization to create a card that contains details for a single record, such as a user profile.

<img alt="" />

## Example code

```html expandable theme={null}
<style>
.md-card {
  display: grid;
  gap: 0 var(--size6);
  grid-template-columns: max-content 1fr;
}

.md-card-info {
  grid-row: 1 / 1;
  grid-column: 2 / 2;
  font-size: 14px;
}

.md-card-info h4 {
  font-size: 32px;
  margin-bottom: 0;
}

.md-card-info p {
  margin: 0;
}

.md-profile {
  grid-row: 1 / span 2;
  grid-column: 1;
}

.md-profile img {
  display: block;
  width: 200px;
  border-radius: 12px;
}

.md-profile p {
  text-align: center;
  font-size: 8px;
  color: var(--color-text1);
  margin: 0;
}

.md-card-metrics {
  grid-row: 2 / 2;
  display: flex;
  gap: var(--size4);
  margin: 0;
  padding: 0;
  list-style: none;
}

.md-card-metrics li {
  padding-block: var(--size4);
}

.divider {
  background-color: var(--color-border2);
  width: 1px;
  margin-inline: var(--size2);
  margin-block: var(--size4);
}

.md-metric-label {
  font-size: 14px;
  color: var(--color-text2);
}
.md-metric-value {
  font-size: 27px;
  font-weight: bold;
}

</style>

<div class="md-card">
<div class="md-card-info">
<h4>{{result.0.users.full_name.value}}</h4>
<p><a href="mailto:{{result.0.users.email.value_static}}">{{result.0.users.email.value}}</a></p>
<p>{{result.0.users.city.value}}, {{result.0.users.state.value}} {{result.0.users.zip.value}}
<a href="http://www.google.com/maps/search/?api=1&query={{result.0.users.zip.value_static}}" target="_blank">view map</a>
</p>
</div>

<div class="md-profile">
<img src="https://robohash.org/{{result.0.users.email.value_static}}" />
<p>Robots lovingly delivered by Robohash.org</p>
</div>

<ul class="md-card-metrics">
<li>
<div class="md-metric-value">{{result.0.users.age.value}}</div>
<div class="md-metric-label">{{fields.users.age.label}}</div>
</li>
<li class="divider"></li>
<li>
<div class="md-metric-value">{{result.0.order_items.order_count.value}}</div>
<div class="md-metric-label">{{fields.order_items.order_count.label}}</div>
</li>
<li class="divider"></li>
<li>
<div class="md-metric-value">{{result.0.order_items.sale_price_sum.value}}</div>
<div class="md-metric-label">{{fields.order_items.sale_price_sum.label}}</div>
</li>

</ul>
</div>
```


# Repeating pie charts
Source: https://docs.omni.co/showcase/visualizations/repeating-pie-chart

The code for this example can be used in the Markdown visualization to create a series of pie charts, one for each row in your results.

Pies will automatically adjust size and wrap to the next line.

<img alt="" />

## Setup

These charts use the Mustache iterator syntax to draw a shape for each row in the results. Your query should have a dimension that determines the number of pies and their labels and the values for the numerator and denominator to calculate the percentage fill. Then you'll need to add a few calculations.

The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name                   | Description or formula          | Purpose                                              |
| --- | ---------------------- | ------------------------------- | ---------------------------------------------------- |
| A   | Category               | query field                     | determines number of pies to make and their labels   |
| B   | Products Count         | query field                     | denominator for % calculation                        |
| C   | Products over \$50     | query field                     | numerator for % calculation                          |
| D   | % over \$50 (`calc_1`) | =C1 / B1                        | calculation for filling pie, label                   |
| E   | rotation (`calc_4`)    | =D1 \* 360                      | calculation to get the degrees for drawing pie slice |
| F   | label pos (`calc_5`)   | =IF(D1 \< 0.5, "left", "right") | calculation to help position and color the label     |

## Example code

```html expandable theme={null}
<style>
  h3 {
    margin-top: 0;
  }
  .pie-party {
    --plate-color: var(--color-border2);
    --slice-color: var(--color-info);

    & ul {
      list-style: none;
      margin: 0;
      padding: 0;
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
      gap: var(--size4);
    }
    & li {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    & p {
      margin: 0;
      padding: 0;
    }

    .pie-plate {
      aspect-ratio: 1/1;
      background-color: var(--plate-color);
      margin: 0 auto;
      border-radius: 50%;
      display: flex;
      align-items: center;
      justify-content: center;
      width: 100%;
      overflow: hidden;
    }
    .pie-slice {
      width: 100%;
      height: 100%;
      position: relative;
      list-style: none;
      margin: 0;
      padding: 0;
      
      & span {
        display: block;
        font-size: var(--font-xxs);
        font-variant-numeric: tabular-nums;
        width: 4ch;
        padding-right: 2px;
        line-height: var(--line-height-xxs);
        position: absolute;
      }
      & span.left {
        text-align: left;
        top: 50%;
        right: 50%;
        color: var(--color-text2);
      }
      & span.right {
        top: 50%;
        left: calc(50% + 1ch);
        text-align: right;
        color: var(--color-text-inverse);
      }
    }
    & p.label {
      text-align: center;
    }
  }
</style>

<article class="pie-party">
  <h3>% of products over $50</h3>
  <ul>
  {{#result}}
    <li>
      <div class="pie-plate"">
        <p class="pie-slice" style="background-image: conic-gradient(from 0deg, var(--slice-color) {{calc_4.value}}deg, transparent 0)">
          <span class="{{calc_5.value}}">{{calc_1.value}}</span>
        </p>
      </div>
      <p class="label">{{products.category.value}}</p>
    </li>
  {{/result}}
    
  </ul>
</article>
```


# Repeating square fill charts
Source: https://docs.omni.co/showcase/visualizations/repeating-square-fill-chart

The code for this example can be used in the Markdown visualization to create a series of percentage-filled squares, one for each row in your results.

Squares will automatically adjust size and wrap to the next line.

<img alt="" />

## Setup

These charts use the Mustache iterator syntax to draw a shape for each row in the results. Your query should have a dimension that determines the number of pies and their labels and the values for the numerator and denominator to calculate the percentage fill. Then you'll need to add a few calculations. The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name                         | Description or formula              | Purpose                                                 |
| --- | ---------------------------- | ----------------------------------- | ------------------------------------------------------- |
| A   | Category                     | query field                         | determines number of squares to make and their labels   |
| B   | Products Count               | query field                         | denominator for % calculation                           |
| C   | Products over \$50           | query field                         | numerator for % calculation                             |
| D   | % over \$50 (`calc_1`)       | =C1 / B1                            | calculation for filling square, label                   |
| E   | inside or outside (`calc_3`) | =IF(D1 \< 0.1, "outside", "inside") | calculation to help position and color the label        |
| F   | square root (`calc_4`)       | =SQRT(D1)                           | calculation to get the length of the side of the square |

## Example code

```html expandable theme={null}
<style>
  h3 {
    margin-top: 0;
  }
  .percent-fill-boxes {
    & ul {
      list-style: none;
      margin: 0;
      padding: 0;
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
      gap: var(--size4);
    }
    & li {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    p {
      margin: 0;
      padding: 0;
    }
    & .big-box {
      width: 100%;
      aspect-ratio: 1 / 1;
      background-color: var(--color-border2);
      position: relative;
      display: flex;
      flex-direction: column-reverse;
    }
    & .little-box {
      aspect-ratio: 1 / 1;
      display: block;
      background-color: var(--color-info);
      position: relative;
      
      & span {
        display: block;
        font-size: var(--font-xxs);
        font-variant-numeric: tabular-nums;
        width: 4ch;
        padding-right: 2px;
        line-height: var(--line-height-xxs);
        position: absolute;

        &.inside {
          text-align: right;
          top: 0;
          right: 0;
          color: var(--color-text-inverse);
        }

        &.outside {
          top: calc(-1 * var(--line-height-xxs));
          right: -4ch;
          text-align: left;
          color: var(--color-text2)
;        }
      }
    }
    & p.label {
      text-align: left;
    }
  }
</style>

<article class="percent-fill-boxes">
  <h3>% of products over $50</h3>
  <ul>
  {{#result}}
    <li>
      <div class="big-box"">
        <p class="little-box" style="width: {{calc_4.value}}">
          <span class="{{calc_3.value}}">{{calc_1.value}}</span>
        </p>
      </div>
      <p class="label">{{products.category.value}}</p>
    </li>
  {{/result}}
    
  </ul>
</article>
```


# Repeating waffle charts
Source: https://docs.omni.co/showcase/visualizations/repeating-waffle-chart

The code for this example can be used in the Markdown visualization to create a series of percentage-filled waffle charts, one for each row in your results.

Squares will automatically adjust size and wrap to the next line.

<img alt="" />

## Setup

These charts use the Mustache iterator syntax to draw a shape for each row in the results. Your query should have a dimension that determines the number of pies and their labels and the values for the numerator and denominator to calculate the percentage fill. Then you'll need to add a lot calculations. The following table explains each field used in the example, including the calculation formulas.

This chart is a bit crazy. We're not actually drawing 100 tiny squares for each waffle shape, but instead filling 10 bars per waffle and drawing some dividers on top of them to simulate a waffle.

<img alt="" />

| Col | Name                   | Description or formula                       | Purpose                                               |
| --- | ---------------------- | -------------------------------------------- | ----------------------------------------------------- |
| A   | Category               | query field                                  | determines number of waffles to make and their labels |
| B   | Products Count         | query field                                  | denominator for % calculation                         |
| C   | Products over \$50     | query field                                  | numerator for % calculation                           |
| D   | % over \$50 (`calc_1`) | =C1 / B1                                     | calculation for filling waffle squares, label         |
| E   | 1s (`calc_5`)          | =IF(D1 >= 10, 100, 10 \* D1)                 | how far to fill the 1s bar                            |
| F   | 10s (`calc_6`)         | =IF(D1 >= 20, 100, MAX(0, (D1 - 10)) \* 10)  | how far to fill the 10s bar                           |
| G   | 20s (`calc_7`)         | =IF(D1 >= 30, 100, MAX(0, (D1 - 20)) \* 10)  | how far to fill the 20s bar                           |
| H   | 30s (`calc_8`)         | =IF(D1 >= 40, 100, MAX(0, (D1 - 30)) \* 10)  | how far to fill the 30s bar                           |
| I   | 40s (`calc_9`)         | =IF(D1 >= 50, 100, MAX(0, (D1 - 40)) \* 10)  | how far to fill the 40s bar                           |
| J   | 50s (`calc_10`)        | =IF(D1 >= 60, 100, MAX(0, (D1 - 50)) \* 10)  | how far to fill the 50s bar                           |
| K   | 60s (`calc_11`)        | =IF(D1 >= 70, 100, MAX(0, (D1 - 60)) \* 10)  | how far to fill the 60s bar                           |
| L   | 70s (`calc_12`)        | =IF(D1 >= 80, 100, MAX(0, (D1 - 70)) \* 10)  | how far to fill the 70s bar                           |
| M   | 80s (`calc_13`)        | =IF(D1 >= 90, 100, MAX(0, (D1 - 80)) \* 10)  | how far to fill the 80s bar                           |
| N   | 90s (`calc_14`)        | =IF(D1 >= 100, 100, MAX(0, (D1 - 90)) \* 10) | how far to fill the 90s bar                           |

## Example code

```html expandable theme={null}
<style>
  h3 {
    margin-top: 0;
  }
  .percent-fill-boxes {
    & ul {
      list-style: none;
      margin: 0;
      padding: 0;
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
      gap: var(--size4);
    }
    & li {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    & p {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    & .big-box {
      --grid-background-color: var(--color-background);
      width: 100%;
      aspect-ratio: 1 / 1;
      position: relative;
      display: grid;
      grid-template-rows: repeat(10, 1fr);
      gap: 2%;
    }
    & .big-box p {
      background-color: var(--color-border2);
      width: 100%;
      position: relative;

      & .row-fill {
        background-color: var(--color-info);
        display: block;
        height: 100%;
      }
      & .row-dividers {
        position: absolute;
        width: 100%;
        height: 100%;
        top: 0;
        left: 0;
        background-image: linear-gradient(
          90deg,
          var(--grid-background-color) 0%,
          var(--grid-background-color) 1%,            
          transparent 1%,
          transparent 9%,
          var(--grid-background-color) 9%,
          var(--grid-background-color) 11%,
          transparent 11%,
          transparent 19%,
          var(--grid-background-color) 19%,
          var(--grid-background-color) 21%,
          transparent 21%,
          transparent 29%,
          var(--grid-background-color) 29%,
          var(--grid-background-color) 31%,
          transparent 31%,
          transparent 39%,
          var(--grid-background-color) 39%,
          var(--grid-background-color) 41%,
          transparent 41%,
          transparent 49%,
          var(--grid-background-color) 49%,
          var(--grid-background-color) 51%,
          transparent 51%,
          transparent 59%,
          var(--grid-background-color) 59%,
          var(--grid-background-color) 61%,
          transparent 61%,
          transparent 69%,
          var(--grid-background-color) 69%,
          var(--grid-background-color) 71%,
          transparent 71%,
          transparent 79%,
          var(--grid-background-color) 79%,
          var(--grid-background-color) 81%,
          transparent 81%,
          transparent 89%,
          var(--grid-background-color) 89%,
          var(--grid-background-color) 91%,
          transparent 91%,
          transparent 99%,
          var(--grid-background-color) 99%,
          var(--grid-background-color) 100%
          );
      }
    }
    & p.label {
      text-align: left;
    }
  }
</style>

<article class="percent-fill-boxes">
  <h3>% of products over $50</h3>
  <ul>
  {{#result}}
    <li>
      <div class="big-box"">
        <p class="d9"><span class="row-fill" style="width: {{calc_14.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d8"><span class="row-fill" style="width: {{calc_13.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d7"><span class="row-fill" style="width: {{calc_12.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d6"><span class="row-fill" style="width: {{calc_11.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d5"><span class="row-fill" style="width: {{calc_10.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d4"><span class="row-fill" style="width: {{calc_9.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d3"><span class="row-fill" style="width: {{calc_8.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d2"><span class="row-fill" style="width: {{calc_7.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d1"><span class="row-fill" style="width: {{calc_6.value}}%"></span><span class="row-dividers"></span></p>
        <p class="d0"><span class="row-fill" style="width: {{calc_5.value}}%"></span><span class="row-dividers"></span></p>
      </div>
      <p class="label">
        <span>{{products.category.value}}&nbsp;•&nbsp;{{calc_1.value}}%</span>
      </p>
    </li>
  {{/result}}
    
  </ul>
</article>
```


# Fancy subtotal table
Source: https://docs.omni.co/showcase/visualizations/simple-subtotal-table

The code for this example can be used in the Markdown visualization to create different styles for displaying a simple table with subtotals.

This table puts the category labels and their subtotals as the first row for the category. Sub-categories are listed in smaller text below.

<img alt="" />

## Setup

Your query must have 2 dimensions (the primary category and the sub category) and a measure to total. The rest of the columns are calculations to get the percentages and provide some styling information to the markdown.

Sort the results by the primary category and enable subtotals from the primary category's triple-dot menu. Use secondary sorts to control how the sub-categories are ordered. You can do a secondary sort by shift-clicking on the column header.

The following table describes the fields in the result set and their purpose.

**Note:** The labels of each calculation includes the calculation's ID in parentheses. This hopefully helps connect the mustache references in the markdown to the correct column of data. Depending on the order in which you create your calculations, these IDs may be different.

<img alt="" />

### Column descriptions

| Col | Name                               | Calculation formula                   | Purpose                                                                          |
| --- | ---------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| A   | Property type friendly             | query data                            | Primary category with subtotals enabled                                          |
| B   | Bike Type                          | query data                            | Sub-category                                                                     |
| C   | Bikeshare Trips Count              | query data                            | metric to total                                                                  |
| D   | pct (count\_of\_percent\_total\_1) | =C1 / SUM(C:C)                        | To display the overall % share of each category to the total                     |
| E   | property class (calc\_1)           | =SUBSTITUTE(LOWER(A1), " ", "-")      | making a css-friendly class name for the primary category to use for coloring    |
| F   | is total (calc\_2)                 | =IF(B1 \<> "", "individual", "total") | css-friendly class name to identify the row in the results as a total row or not |

## Example code

```html expandable theme={null}
<style>
.suggestions-breakdown {
  --color-non-metered-parking: #6985FF;
  --color-paid-parking: #13D3DF;
  --color-park-land: #FFA2F5;
  --color-sidewalk: #1D4CFF;
  --color-undetermined-parking: #EE46D3;
  --color-unknown: #9AA2AF;

  padding-right: 16px;

  & h3 {
    margin-top: 0;
  }
  & ul {
    list-style: none;
    margin: 0;
    padding: 0;
    display: flex;
    gap: 4px;
    flex-direction: column-reverse; /* puts total rows before sub-category */
  }
  & li {
    list-style: none;
    margin: 0;
    padding: 0;
    display: flex;
    flex-direction: row;
    gap: 16px;

    & .type {
      display: flex;
      flex-direction: row;
      gap: 8px;
      align-items: center;
    }
    
    & .value {
      text-align: right;
      flex: 1;
    }
    & .percent {
      text-align: right;
      width: 120px;
    }
  }
  & li.total {
    font-weight: 500;
    font-size: var(--font-sm);
    padding-top: 12px;
    border-top: 1px solid var(--color-border1);

    & .category {
      visibility: hidden;
    }

    & .indicator {
      display: inline-block;
      background: var(--color-other);
      width: 8px;
      height: 8px;
      border-radius: var(--radius-round);
    }
  }

  & li.individual {
    color: var(--color-text2);
    font-size: var(--font-xs);
    
    & .type {
      visibility: hidden;
      font-size: 0px;

      & .indicator {
        display: none;
      }
    }
    & .category {
      text-transform: capitalize;
    }
    & .percent {
      visibility: hidden;
    }
  }

  & li.total + li.individual {
    padding-bottom: 12px;
  }
  & li.heading {
    order: 50;
    font-size: var(--font-xs);
    color: var(--color-text2);
    text-transform: uppercase;
    padding-bottom: 4px;

    & span:first-of-type {
      flex: 1 1 0;
    }
    & span + span {
      text-align: right;
      width: 120px;
    }
  }
}
</style>
<article class="suggestions-breakdown">
<h3>Bike trip breakdown</h3>
<ul>
<li class="heading">
  <span>Type</span>
  <span>Total</span>
  <span>Percent</span>
</li>
{{#result}}
<li class="{{calc_2.value_static}} {{calc_2.value_static}}">
  <span class="type">
    <span class="indicator" style="background-color: var(--color-{{calc_1.value_static}})"></span>
    <span>{{bikeshare_start_stations.property_type_friendly.value}}</span>
  </span>
  <span class="category">{{bikeshare_trips.bike_type.value}}</span>
  <span class="value">{{bikeshare_trips.count.value}}</span>
  <span class="percent">{{count_percent_of_total_1.value}}</span>
</li>
{{/result}}
</ul>
</article>
```


# Star rating
Source: https://docs.omni.co/showcase/visualizations/star-rating

The code for this example can be used in a Markdown column to display a numeric rating as filled and empty stars.

This example uses a Markdown column to display a numeric rating as a row of stars in a [table](/visualize-present/visualizations/types/table), with filled (orange) stars for the rating and empty (gray) stars filling the remainder up to five.

<img alt="A table column showing each row's rating as five stars, with filled orange stars for the rating and gray outlined stars for the remainder" />

## Setup

This example uses a numeric rating field and two [calculations](/analyze-explore/calculations): one for the filled stars and one for the empty stars. Both calculations use a `SWITCH` statement on the rating (column `A`). Add both calculations to your query, then set the column you want to display to **Display as** **Markdown** and hide the rating and remaining helper columns.

The template references the calculations as `{{calc_1.value}}` (filled) and `{{calc_2.value}}` (empty). Calculation reference names depend on the order they're created, so update them to match your own.

| Col | Name                    | Description or formula                                          | Purpose                                     |
| --- | ----------------------- | --------------------------------------------------------------- | ------------------------------------------- |
| A   | Rating                  | Numeric rating field (1–5)                                      | Drives both star calculations               |
| B   | Filled stars (`calc_1`) | `=SWITCH(A1, 1, "★", 2, "★★", 3, "★★★", 4, "★★★★", 5, "★★★★★")` | Orange stars equal to the rating            |
| C   | Empty stars (`calc_2`)  | `=SWITCH(A1, 1, "☆☆☆☆", 2, "☆☆☆", 3, "☆☆", 4, "☆", 5, "")`      | Gray stars filling the remainder up to five |

## Example code

**Markdown template**:

```handlebars wrap theme={null}
<div class="stars-wrap">
  <span style="color:#f59e0b; font-size:20px; letter-spacing:2px;">{{calc_1.value}}</span><span style="color:#ddd; font-size:20px; letter-spacing:2px;">{{calc_2.value}}</span>
</div>
```

**CSS styles**:

```css expandable theme={null}
<style>
  .stars-wrap {
    position: relative;
    display: inline-block;
    color: #ddd;
    font-size: 20px;
    letter-spacing: 2px;
  }

  .stars-filled {
    position: absolute;
    top: 0;
    left: 0;
    overflow: hidden;
    color: #f59e0b;
    white-space: nowrap;
  }
</style>
```


# Status indicator
Source: https://docs.omni.co/showcase/visualizations/status-indicator

The code for this example can be used in a Markdown column to display a status next to a colored indicator dot.

This example uses a Markdown column to display a status value next to a colored indicator dot in a [table](/visualize-present/visualizations/types/table)—green for active and red for inactive. The status value is used as a CSS class name, and the CSS defines the dot color for each possible value.

<img alt="A table column showing each row's status as text next to a colored dot: a green dot for active and a red dot for inactive" />

## Setup

In the table visualization, select the column you want to format and set **Display as** to **Markdown**. Then add the Markdown template and CSS below.

The template sets the field's value as the `class` of a `<div>` so that the matching CSS rule controls the dot's color, and repeats the value as the label text. Add one CSS class for each possible value in your data—in this example, `active` and `inactive`. The class names must match the values exactly, so this pattern works best for fields with a small, fixed set of values that don't contain spaces or special characters.

This example references the `status` field from the `saas__users_detailed` view using [Mustache syntax](/visualize-present/mustache-reference). Replace these references with your own field.

## Example code

**Markdown template**:

```handlebars wrap theme={null}
<div style="display:flex; align-items:center; gap:6px;">
  <div class="{{saas__users_detailed.status.value}}"></div>
  <span>{{saas__users_detailed.status.value}}</span>
</div>
```

**CSS styles**:

```css expandable theme={null}
<style>
  .status-row {
    display: flex;
    align-items: center;
    gap: 6px;
  }

  .active {
    width: 8px;
    height: 8px;
    border-radius: 50%;
    background: #22c55e;
    flex-shrink: 0;
  }
  .inactive {
    width: 8px;
    height: 8px;
    border-radius: 50%;
    background: red;
    flex-shrink: 0;
  }
</style>
```


# Symmetric funnel
Source: https://docs.omni.co/showcase/visualizations/symmetric-funnel

The code for this example can be used in the Markdown visualization to create a funnel with multiple sequential steps.

<img alt="" />

## Setup

This visualization is built on having multiple measures which are then swapped rows and columns, with a calculation built to get stage by stage conversion metrics. For example, in cell `C2`, enter the formula `=B2/B1`.

<img alt="" />

## Example code

```html expandable theme={null}
<style>

.parentView {
  display: flex;
  flex-direction: column;
  align-items: center;
}

.trapezoid {
  background: #ff6666;
  width: 100%;
  display: flex;
  justify-content: center;
  clip-path: polygon(0% 0%, 100% 0%, 90% 100%, 10% 100%);
}

.trapezoid2 {
  background: #ee6021;
  width: 85%;
  display: flex;
  justify-content: center;
  clip-path: polygon(0% 0%, 100% 0%, 90% 100%, 10% 100%);
}

.trapezoid3 {
  background: #f6c62d;
  width: 75%;
  display: flex;
  justify-content: center;
  clip-path: polygon(0% 0%, 100% 0%, 90% 100%, 10% 100%);
}

.trapezoid4 {
  background: #9de24f;
  width: 65%;
  display: flex;
  justify-content: center;
  clip-path: polygon(0% 0%, 100% 0%, 90% 100%, 10% 100%);
}
  
.text {
  color: white;
  display: flex;
  line-height: 1.5;
  font-size: 20px;
}
.conv{
  font-size: 15px;
  line-height: 3;
  font-weight: bold;
}
</style>
<div class = "parentView">
  <div class="trapezoid">
    <h1 class="text"> {{result.0.measure_value.value}} Stage 1 </h1>
  </div>
  <div class="conv"> ↓ {{result.1.calc_1.value}} </div>
  <div class="trapezoid2">
    <h1 class="text"> {{result.1.measure_value.value}} Stage 2 </h1>
  </div>
  <div class="conv"> ↓ {{result.2.calc_1.value}} </div>
  <div class="trapezoid3">
    <h1 class="text"> {{result.2.measure_value.value}} Stage 3 </h1>
  </div>
  <div class="conv"> ↓ {{result.3.calc_1.value}} </div>
  <div class="trapezoid4">
    <h1 class="text"> {{result.3.measure_value.value}} Stage 4 </h1>
</div>
```


# Table with tiny bar charts
Source: https://docs.omni.co/showcase/visualizations/table-with-tiny-bars

The code for this example can be used in the Markdown visualization to create a styled table with a small bar chart in each row.

A row in the Markdown table corresponds to a row in the results.

<img alt="" />

## Setup

These charts use the Mustache iterator syntax to draw a chart for each row in the results. Your query should have a column for each bar that you want to display and then a calculation column for each bar that determines the height of each bar. The calculation in this example calculates the bar height as a percentage of the total for all the traffic sources. Adjust your calculation as needed for different analyses, but make sure you use the % formatting on the calculation column.

The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name                  | Description or formula | Purpose                                                                               |
| --- | --------------------- | ---------------------- | ------------------------------------------------------------------------------------- |
| A   | State Groups          | query field            | used to make cute little badges in each row                                           |
| B   | State                 | query field            | main label for the row                                                                |
| C   | Events Count          | query field            | Total events used in table for displaying and to calculate denominator for bar height |
| D   | Adwords               | query field            | Blue bar                                                                              |
| E   | Adwords % (`calc_7`)  | =D1 / C1               | % fill for blue bar (make sure to format as %)                                        |
| F   | Facebook              | query field            | Yellow bar                                                                            |
| G   | Facebook % (`calc_8`) | =F1 / C1               | % fill for yellow bar (make sure to format as %)                                      |
| H   | Email                 | query field            | Pink bar                                                                              |
| I   | Email % (`calc_9`)    | =H1 / C1               | % fill for pink bar (make sure to format as %)                                        |
| J   | Organic               | query field            | Teal bar                                                                              |
| K   | Organic % (`calc_10`) | =J1 / C1               | % fill for teal bar (make sure to format as %)                                        |
| L   | YouTube               | query field            | Orange bar                                                                            |
| M   | YouTube % (`calc_11`) | =L1 / C1               | % fill for orange bar (make sure to format as %)                                      |

## Example code

```html expandable theme={null}
<style>
article.fancy-table {
  --color-adwords: 41,139,229;
  --color-email: 247,181,78;
  --color-facebook: 255,98,145;
  --color-organic: 29,185,185;
  --color-youtube: 255,133,21;
  --bar-height: 40px;
  --color-source: 0,0,0;
  --color-opacity: 0.1;
  --color-west: 80,144,70;
  --color-south: 79,89,218;
  --color-midwest: 210,66,58;
  --color-northeast: 176,76,186;

  & .adwords { --color-source: var(--color-adwords);}
  & .email { --color-source: var(--color-email);}
  & .facebook { --color-source: var(--color-facebook);}
  & .organic { --color-source: var(--color-organic);}
  & .youtube { --color-source: var(--color-youtube);}

  & .west { --color-tag: var(--color-west); }
  & .south { --color-tag: var(--color-south); }
  & .midwest { --color-tag: var(--color-midwest); }
  & .northeast { --color-tag: var(--color-northeast); }

  & ul {
    list-style: none;
    margin: 0;
    padding: 0;

    & li {
      padding: 0;
      margin: 0;
    }
  }
}
article.fancy-table ul.source-legend {
  display: flex;
  flex-direction: row;
  gap: 16px;
  padding: 0 0 8px 12px;

  & li {
    display: flex;
    flex-direction: row;
    gap: 4px;
    align-items: center;
    color: var(--color-text1);
    font-size: var(--font-xs);

    & span {
      display: block;
      width: 12px;
      height: 12px;
      background-color: rgb(var(--color-source));
    }
  }
}
article.fancy-table table {
  width: 100%;
  border-collapse: collapse;

  & thead { display: none;}
  & th { white-space: nowrap; }
  & td {
    padding-block: 12px;
    padding-inline: 12px;
    border-bottom: 1px dotted var(--color-border2);
    vertical-align: bottom;
  }
  & td.metrics,
  & th.metrics {
    text-align: right;
  }
  & td.metrics {
    font-size: var(--font-md);
  }
  & td.summary ul {
    display: flex;
    flex-direction: column;
    gap: 8px;
    justify-content: center;

    & .type span {
      display: inline-block;
      background: rgba(var(--color-tag),0.1);
      padding: 0px 2px;
      border-radius: 3px;
      font-size: var(--font-xxs);
      text-transform: uppercase;
      color: rgb(var(--color-tag));
    }
    & .title {
      color: var(--color-text4);
      font-size: var(--font-md);
    }
  }
  & td.sources ul {
    display: flex;
    flex-direction: row;
    height: var(--bar-height);
    gap: 2px;
    justify-content: center;

    & li {
      width: 8px;
      height: 100%;
      background-color: rgba(var(--color-source), var(--color-opacity));
      border-radius: 2px 2px 0 0;
      display: flex;
      flex-direction: column-reverse;
      position: relative;
      --tooltip-width: 100px;
      --tooltip-height: 36px;
      --translate-tip: calc(-1 * var(--tooltip-width));

      & span.bar {
        display: block;
        width: 100%;
        height: 1%;
        border-radius: 2px 2px 0 0;
        background-color: rgb(var(--color-source));
      }
      & span.tooltip-content {
        visibility: hidden;
        opacity: 0;
        position: absolute;
        z-index: 1;
        bottom: 100%;
        left: calc(0% - 8px);
        top: calc(50% - var(--bar-height) / 2);
        transform: translateX(var(--translate-tip));
        height: var(--tooltip-height);
        width: var(--tooltip-width);
        background-color: #333;
        color: white;
        text-align: center;
        border-radius: 5px;
        padding: 4px 6px;
        font-size: 10px;
        font-weight: normal;
        transition: opacity 0.15s;
        box-shadow: -2px 2px 8px rgba(0,0,0,0.2);
        line-height: 1.4;
        word-wrap: break-word;
        white-space: normal;
        border-left: 8px solid rgb(var(--color-source));
      }
      & span.tooltip-content::after {
        content: "";
        position: absolute;
        top: Calc(50% - 5px);
        right: -5px;
        margin-right: -5px;
        border-width: 5px;
        border-style: solid;
        border-color: #333 transparent transparent transparent;
        transform: rotate(-90deg);
      }
    }
    & li:hover .tooltip-content {
      visibility: visible;
      opacity: 1;
    }
  }
}
</style>

<article class="fancy-table">
<ul class="source-legend">
  <li class="adwords"><span></span>Adwords</li>
  <li class="email"><span></span>Email</li>
  <li class="facebook"><span></span>Facebook</li>
  <li class="organic"><span></span>Organic</li>
  <li class="youtube"><span></span>YouTube</li>
</ul>
<table>
  <thead>
    <tr>
      <th class="summary">Article</th>
      <th class="metrics">Total Views</th>
      <th class="sources">Source</th>
    </tr>
  </thead>
  <tbody>
{{#result}}
<tr>
  <td class="summary">
    <ul>
      <li class="type {{events.state_groups.raw}}"><span>{{events.state_groups.value}}</span></li>
      <li class="title">{{events.state.value}}</li>
    </ul>
  </td>
  <td class="metrics">{{events.count.value}}</td>
  <td class="sources">
    <ul>
      <li class="adwords">
        <span class="bar" style="height: {{calc_7.value_static}}"></span>
        <span class="tooltip-content">
          {{fields.events.count_adwords.label}}<br />
          {{events.count_adwords.value}} • {{calc_7.value_static}}</span>
      </li>
      <li class="email">
        <span class="bar" style="height: {{calc_8.value_static}}"></span>
        <span class="tooltip-content">
          {{fields.events.count_email.label}}<br />
          {{events.count_email.value}} • {{calc_8.value_static}}</span>
      </li>
      <li class="facebook">
        <span class="bar" style="height: {{calc_9.value_static}}"></span>
        <span class="tooltip-content">
          {{fields.events.count_adwords.label}}<br />
          {{events.count_adwords.value}} • {{calc_9.value_static}}</span>
      </li>
      <li class="organic">
        <span class="bar" style="height: {{calc_10.value_static}}"></span>
        <span class="tooltip-content">
          {{fields.events.count_organic.label}}<br />
          {{events.count_organic.value}} • {{calc_10.value_static}}</span>
      </li>
      <li class="youtube">
        <span class="bar"style="height: {{calc_11.value_static}}"></span>
        <span class="tooltip-content">
          {{fields.events.count_you_tube.label}}<br />
          {{events.count_you_tube.value}} • {{calc_11.value_static}}</span>
      </li>
    </ul>
  </td>
</tr>
{{/result}}
  </tbody>
</table>
</article>
```


# Team progress tracker
Source: https://docs.omni.co/showcase/visualizations/team-progress-tracker

The code for this example can be used in the Markdown visualization to create a progress chart for multiple individuals on the same timeline.

If any individuals exceed 100% of their goal, the progress line will extend to the highest value.

## Limitations

* This example uses some HTML and CSS that do not render in PDFs or PNGs. Only use this if you don't need it delivered.
* This example requires all team members have the same goal value. You could adjust the math if you need to do varying target values.
* This version adds a crown to any team member that exceeds the target.

<img alt="" />

## Setup

These charts use the Mustache iterator syntax to draw a circle on the progress tracker for each row in the results.

The following table explains each field used in the example, including the calculation formulas.

<img alt="" />

| Col | Name               | Description or formula   | Notes                                                         |
| --- | ------------------ | ------------------------ | ------------------------------------------------------------- |
| A   | Sales Rep          |                          | Name used in tooltip                                          |
| B   | Quota              | target value             | Must be the same for each individual                          |
| C   | To date            | current value            | must be > 0 but can exceed target                             |
| D   | % to quota         | =C1 / B1                 | % to goal - can be > 100%                                     |
| E   | is over quota      | =IF(D1 >= 1, "over", "") | used to add a crown if user is over quota                     |
| F   | Max dollars        | =MAX(MAX(C:C), B1)       | needed for calculating positions if anybody is over quota     |
| G   | Max %              | =MAX(MAX(D:D), 1)        | used for presentation in the tooltip                          |
| H   | Someone over quota | =IF(G1 > 1, "over", "")  | flag to change range of tracker if anybody is over quota      |
| I   | Initials           |                          | Not used in this example but could be used instead of picture |
| J   | Image              |                          | used as background of the circle                              |

## Example code

```html expandable theme={null}
<style>
article.race-tracker {
  --padding-inline: 44px;
  --track-width: 2px;
  --track-color: var(--color-border2);
  --rep-diam: 56px;
  --rep-half: calc(var(--rep-diam) / 2);
  --rep-quarter: calc(var(--rep-half) / 2);
  --track-height: calc(2.25 * var(--rep-diam));
  --zero: calc(var(--rep-diam) / 2); /* 1/2 diam */
  --quota: {{result.0.reps_to_quota.quota.raw}};
  --max: {{result.0.calc_2.raw}};

  width: 100%;
  padding: 0 var(--padding-inline);
  position: relative;
}
ol.track {
  list-style: none;
  margin: 0;
  display: flex;
  width: 100%;
  height: var(--track-height);
  position: relative;
  
  & li.track-line {
    position: absolute;
    background: var(--track-color);
    height: var(--track-width);
    width: 100%;
    top: calc(50% - var(--track-width) / 2);
    left: 0;
    z-index: 0;
  }

  & li.tick {
    --marker-width: 5ch;
    --half: calc(var(--marker-width) / 2);
    --mark: attr(data-value type(<number>));
    --quota-x-mark: calc(var(--quota) * var(--mark));
    --position: calc(var(--quota-x-mark) / var(--max) * 100%);
  
    position: absolute;
    width: 5ch;
    display: flex;
    flex-direction: column;
    justify-content: flex-end;
    align-items: center;
    height: 100%;
    top: 0;
    left: calc(var(--position) - var(--half));
    font-size: var(--font-xxs);
    
    & span.line {
      width: var(--track-width);
      background: var(--track-color);
      height: var(--rep-half);
      display: inline-blcok;
      position: absolute;
      top: calc(var(--rep-half)* 1.75);
    }
  }
  & li.tick.alt-max {
    visibility: hidden;
  }

  &.over li.tick.alt-max {
    visibility: visible;
  }
}
ol.tracker {
  list-style: none;
  margin: 0;
  display: flex;
  width: calc(100% - 2 * var(--padding-inline));
  height: var(--rep-diam);
  position: absolute;
  top: calc(var(--rep-half) * 1.25);
  left: var(--padding-inline);

  & li.rep {
    --todate: attr(data-todate type(<number>));
    --position: calc(var(--todate) / var(--max) * 100%);
    width: var(--rep-diam);
    height: var(--rep-diam);
    display: flex;
    align-items: center;
    justify-content: center;
    border-radius: 500px;
    border: 1px solid var(--color-text4);
    box-shadow: var(--elevation1);
    position: absolute;
    left: calc(var(--position) - var(--zero));
    background-color: var(--color-text1);
    background-size: var(--rep-diam);

    & .crown {
      position: absolute;
      top: calc(var(--rep-half) * -0.75);
      font-size: var(--font-xxl);
      display: none;
    }

    & ul.info-bits {
      position: absolute;
      bottom: 0;
      left: calc(-60px + var(--size4));
      top: -60px;
      list-style: none;
      margin: 0;
      padding: var(--size1) var(--size2);
      width: 120px;
      border-radius: 3px;
      height: min-content;
      background: var(--color-surface-invert);
      color: var(--color-text-inverse);
      box-shadow: var(--elevation3);
      display: none;

      & li {
        white-space: nowrap;
        font-size: var(--font-xxs);
        line-height: var(--line-height-xxs);
      }
    }
  }
  & li.rep:hover {
    box-shadow: var(--elevation3);
    z-index: 2;

    & ul.info-bits {
      display: block;
    }
  }
  & li.rep.over {
    .crown {
      display: block;
    }
  }
}
</style>
<article class="race-tracker">
<ol class="track {{result.0.calc_4.value_static}}">
  <li class="track-line"></li>
  <li class="tick t0" data-value="0"><span class="line"></span><span class="value">0%</span></li>
  <li class="tick t25" data-value="0.25"><span class="line"></span><span class="value">25%</span></li>
  <li class="tick t50" data-value="0.5"><span class="line"></span><span class="value">50%</span></li>
  <li class="tick t75" data-value="0.75"><span class="line"></span><span class="value">75%</span></li>
  <li class="tick t100" data-value="1"><span class="line"></span><span class="value">100%</span></li>
  <li class="tick alt-max" data-value="{{result._first.calc_3.raw}}"><span class="line"></span><span class="value">{{result._first.calc_3.value_static}}</span></li>
</ol>
<ol class="tracker">
{{#result}}
<li class="rep {{calc_5.raw}}" data-todate="{{reps_to_quota.to_date.raw}}" style="background-image: url('{{reps_to_quota.image.raw}}')"><span class="crown">👑</span>
<ul class="info-bits">
  <li>{{reps_to_quota.sales_rep.value_static}}</li>
  <li>{{reps_to_quota.to_date.value_static}} to date</li>
  <li>{{calc_1.value_static}} to quota</li>
</ul>  
</li>
{{/result}}
</ol>
</article>
```


# Test result cards
Source: https://docs.omni.co/showcase/visualizations/test-results-cards

Build test result card visualizations using Markdown in Omni to display consistently sized charts across tests with varying ranges.

The code for these examples can be used in the Markdown visualization to create a series of cards that show a consistently sized chart across 'tests' that can have a variety of ranges.

Inspiration for these charts were taken from blood test results where measurements for a "normal" range vary in units and min and max values.

<img alt="" />

## Setup

This query used for this example has the following structure:

* **Test name** - Title for the card
* **Normal min** - Value for the minimum "normal" range
* **Normal max** - Value for the maximum "normal" range
* **Measurement** - The current "test" result/value to plot on the chart
* **Chart min (calc\_4)** - Calculated "min" of the whole chart using the (`=B1 - ((C1 - B1) / 2)`)
* **Chart max (calc\_1)** - Calculated "max" of the whole chart using the (`=(C1 - B1) / 2 + C1`)
* **% position (calc\_2)** -
* **Result classification (calc\_5)** - calculation to use for coloring (`=IF(D1 < B1, "low", IF(D1 > C1, "high", "normal"))`)
* **Units** - For labeling
* **Notes (calc\_3)** - Additional context for the card

The calculations for the full range of the chart are done positioning the "Normal min" at the 25% mark of the bar and the "Normal max" at the 75% mark. If your data can start at 0 or go below zero, you may need to adjust these calculations.

<img alt="" />

## Example code

```html expandable theme={null}
<style>
  h3 {
    margin-top: 0;
  }
  ul.test-results {
    list-style: none;
    margin: 0;
    padding: 0;
    display: flex;
    flex-direction: column;
    gap: 16px;
  }

  li.test {
    background: var(--color-background);
    border: 1px solid var(--color-border1);
    border-radius: 5px;
    padding: 12px 12px 0 12px;
    box-shadow: var(--elevation1);
    
    & h1 { 
      font-size: var(--font-lg);
      margin: 0;
      line-height: var(--line-height-lg);
    text-transform: capitalize;
    }    
    & h2 {
      font-size: var(--font-sm);
      margin: 0;
      color: var(--color-text1);
      line-height: var(--line-height-sm);
      font-weight: normal;
    } 
    & p.notes {
      padding: 12px 24px 0 24px;
      color: var(--color-text1);      
    }
  }

  .results {
    --chart-height: 20px;
    --color-normal: #4BA14D;
    --color-not-normal: #EED558;
    
    padding: 52px 24px var(--chart-height) 24px;
    
    & ol {
      background: var(--color-not-normal);
      border: 1px solid rgba(0,0,0,0.1);
      list-style: none;
      display: flex;
      flex-direction: row;
      position: relative;
      width: 100%;
      height: var(--chart-height);
      border-radius: 2px;      
    }

    & li.normal-range {
      position: absolute;
      width: 50%;
      background: var(--color-normal);
      height: calc(100% + 2px);
      left: 25%;
      top: -1px;
    }

    & li.label {
      position: absolute;
      top: 20px;
      width: 50%;
      text-align: center;
    }
    & li.label.label-min {
      left: 0;
    }
    & li.label.label-max {
      left: 50%;
    }
    & li.measurement {
      position: absolute;
      width: 50px;
      text-align: center;
      top: -36px;
      font-weight: 500;
      border-radius: 10px;
      padding-block: 2px;

      & .pointer {
        display: block;
        position: absolute;
        left: calc(50% - 8px);
        width: 0;
        height: 0;
        border-left: 10px solid transparent;
        border-right: 10px solid transparent;
        border-top: 10px solid var(--color-results);
      }
    }
    & li.measurement.normal {
      --color-results: var(--color-normal);
      background: var(--color-normal);
      color: white;
    }
    & li.measurement.high,
    & li.measurement.low {
      --color-results: var(--color-not-normal);
      background-color: var(--color-not-normal);
    }

  }
</style>
<h3>Your test results</h3>
<ul class="test-results">
  {{#result}}
  <li class="test">
    <h1 class="test-name">{{pretend_medical_info.test_name.value_static}}</h1>
    <h2>Normal range: {{pretend_medical_info.normal_min.value_static}}-{{pretend_medical_info.normal_max.value_static}}&nbsp;{{pretend_medical_info.units.value_static}}</h2>
    <div class="results">
      <ol class="results-chart">
        <li class="label label-min">{{pretend_medical_info.normal_min.value_static}}</li>
        <li class="label label-max">{{pretend_medical_info.normal_max.value_static}}</li>
        <li class="normal-range"></li>
        <li class="measurement {{calc_5.raw}}" style="left: calc({{calc_2.value_static}} - 25px)">{{pretend_medical_info.measurement.value_static}}<span class="pointer"></span></li>
      </ol>
    </div>
    <p class="notes">{{calc_3.value_static}}</p>
    </li>
  {{/result}}
</ul>
```


# Thermometer progress indicator
Source: https://docs.omni.co/showcase/visualizations/thermometer

The code for these examples can be used in the Markdown visualization to create a fundraising-style thermometer progress indicator.

Inspiration and code for these examples from [this Codepen](https://codepen.io/Arkellys/pen/rgpNBK).

## Basic thermometer

<img alt="" />

### Setup

This query used for this example is pretty simple and needs only a single row that includes the following:

* **Value** - the current value for the thermometer. In this example, it's "Users Count".
* **Target ("calc\_1")** - The 100% value for the thermometer. In this example, it's the "target" calculation.
* **% to goal ("calc\_2")** - The calculation for the value's progress to the goal - here it is `Value / Target` (`=A1 / B1` is the actual calculation). This should be in decimal format, so 0.52 instead of 52%.

<img alt="" />

### Example code

```html expandable theme={null}
<style>
/* thermometer ripped from this awesome pen: https://codepen.io/Arkellys/pen/rgpNBK */

.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  margin: auto;
  box-sizing: content-box;
}
.thermometer {
  /* thermometer variables */
  --temperature: 70%; /* just a placeholder */
  --t-bg-color: var(--color-foreground2);
  --t-border-width: 6px;
  --t-border-color: var(--color-border1);
  --t-width: 25px;
  --t-height: 240px;
  --t-bulb-diam: calc(var(--t-width) * 2);
  --t-radius: 20px;
  --t-marker: 2px solid rgba(0,0,0,0.5);
  --t-bulb-color: #4D59E2;
  --t-temp-color: linear-gradient(#FF4994, var(--t-bulb-color)) no-repeat bottom;
  --t-border: var(--t-border-width) solid var(--t-border-color);

  /* tooltip variables */
  --tt-color: rgba(0,0,0,0.7);
  --tt-text-color: white;
  --tt-size: var(--font-xs);
  --tt-raidus: 5px;
  --tt-top-shift: 4px;
  --tt-v-padding: 4px;
  --tt-h-padding: calc(var(--tt-v-padding) * 2);
  --tt-left-shift: 125%;
  --tt-arrow-width: 1.5;
  --tt-arrow-height: 2.2;

  width: var(--t-width);
  background: var(--t-bg-color);
  height: var(--t-height);
  border: var(--t-border);
  border-radius: var(--t-radius);
  position: relative;
  z-index: 1;
  margin-bottom: var(--t-bulb-diam);
  margin-top: calc(var(--t-bulb-diam) / 2);

  & .border-cover {
    position: absolute;
    content: "";
    border-radius: 50%;
    width: 100%;
    height: calc(var(--t-width) + var(--t-border-width));
    bottom: var(--t-border-width);
    background: var(--t-bg-color);
    z-index: -1;
  }

  & .bulb {
    --bulb-bottom: calc(var(--t-bulb-diam) * -1);
    position: absolute;
    content: "{{result.0.calc_2.value_static}}";
    line-height: var(--t-bulb-diam);
    font-size: var(--font-xxs);
    text-align: center;
    color: rgba(255,255,255,0.67);
    border-radius: 50%;
    transform: translateX(-50%);
    width: var(--t-bulb-diam);
    height: var(--t-bulb-diam);
    background-color: var(--t-bulb-color);
    bottom: calc(var(--bulb-bottom) + 2 * var(--t-border-width));
    left: 50%;
    border: var(--t-border);
    z-index: -3;
  }

  .temperature {
    position: absolute;
    bottom: 0;
    background: var(--t-temp-color);
    width: 100%;
    border-radius: var(--t-radius);
    background-size: 100% var(--t-height);
    transition: all 0.2s ease-in-out;
    height: min(100%, calc(100% * {{result.0.calc_2.raw}}));

    & .tooltip {
      position: absolute;
      background: var(--tt-color);
      color: var(--tt-text-color);
      z-index: 2;
      padding: var(--tt-v-padding) var(--tt-h-padding);
      border-radius: 0 var(--tt-raidus) var(--tt-raidus);
      font-size: var(--tt-size);
      line-height: 1;
      left: calc(var(--tt-left-shift) + 1em / var(--tt-arrow-width));
      top: calc(-1em + var(--tt-top-shift) - var(--tt-v-padding));
      top: 0;
    }
    & .tooltip-arrow {
      position: absolute;
      content: "";
      border-top: calc(var(--tt-size) / var(--tt-arrow-height)) solid transparent;
      border-bottom: calc(var(--tt-size) / var(--tt-arrow-height)) solid transparent;
      border-right: calc(var(--tt-size) / var(--tt-arrow-width)) solid var(--tt-color);
      left: calc(1% + var(--tt-left-shift));
      top: 0;
    }
  }

  .markers {
    position: absolute;
    height: 59%;
    top: 20%;
    width: 50%;
    border-top: var(--t-marker);
    border-bottom: var(--t-marker);

    & .middle {
      content: "";
      height: 34%;
      width: 100%;
      top: 32%;
      position: absolute;
      border-top: var(--t-marker);
      border-bottom: var(--t-marker);
    }
  }

}

</style>

<section class="wrapper">
  <article class="thermometer">
    <div class="border-cover"></div>
    <div class="temperature">
      <div class="tooltip">{{result.0.users.count.value_static}}</div>
      <div class="tooltip-arrow"></div>
    </div>
    <div class="markers"><span class="middle"></span></div>
    <div class="bulb"></div>
  </article>
  <h6>Target: {{result.0.calc_1.value_static}}</h6>
</section>
```

## Thermometer with a celebration

<img alt="" />

### Setup

The setup for the "celebrate with stars" version includes one additional field, **Over 100%? ("calc\_3")**. This calculation is a simple calculation to see if the target has been exceeded. It will be used to assign a CSS class that exposes the stars: `=IF(C1 >= 1, "yes", "no")`

<img alt="" />

### Example code

```html expandable theme={null}
<style>
/* thermometer ripped from this awesome pen: https://codepen.io/Arkellys/pen/rgpNBK */

.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  margin: auto;
  box-sizing: content-box;
}
.thermometer {
  /* thermometer variables */
  --temperature: 70%; /* just a placeholder */
  --t-bg-color: var(--color-foreground2);
  --t-border-width: 6px;
  --t-border-color: var(--color-border1);
  --t-width: 25px;
  --t-height: 240px;
  --t-bulb-diam: calc(var(--t-width) * 2);
  --t-radius: 20px;
  --t-marker: 2px solid rgba(0,0,0,0.5);
  --t-bulb-color: #4D59E2;
  --t-temp-color: linear-gradient(#FF4994, var(--t-bulb-color)) no-repeat bottom;
  --t-border: var(--t-border-width) solid var(--t-border-color);

  /* tooltip variables */
  --tt-color: rgba(0,0,0,0.7);
  --tt-text-color: white;
  --tt-size: var(--font-xs);
  --tt-raidus: 5px;
  --tt-top-shift: 4px;
  --tt-v-padding: 4px;
  --tt-h-padding: calc(var(--tt-v-padding) * 2);
  --tt-left-shift: 125%;
  --tt-arrow-width: 1.5;
  --tt-arrow-height: 2.2;

  width: var(--t-width);
  background: var(--t-bg-color);
  height: var(--t-height);
  border: var(--t-border);
  border-radius: var(--t-radius);
  position: relative;
  z-index: 1;
  margin-bottom: var(--t-bulb-diam);
  margin-top: calc(var(--t-bulb-diam) / 2);

  & .border-cover {
    position: absolute;
    content: "";
    border-radius: 50%;
    width: 100%;
    height: calc(var(--t-width) + var(--t-border-width));
    bottom: var(--t-border-width);
    background: var(--t-bg-color);
    z-index: -1;
  }

  & .bulb {
    --bulb-bottom: calc(var(--t-bulb-diam) * -1);
    position: absolute;
    content: "{{result.0.calc_2.value_static}}";
    line-height: var(--t-bulb-diam);
    font-size: var(--font-xxs);
    text-align: center;
    color: rgba(255,255,255,0.67);
    border-radius: 50%;
    transform: translateX(-50%);
    width: var(--t-bulb-diam);
    height: var(--t-bulb-diam);
    background-color: var(--t-bulb-color);
    bottom: calc(var(--bulb-bottom) + 2 * var(--t-border-width));
    left: 50%;
    border: var(--t-border);
    z-index: -3;
  }

  .temperature {
    position: absolute;
    bottom: 0;
    background: var(--t-temp-color);
    width: 100%;
    border-radius: var(--t-radius);
    background-size: 100% var(--t-height);
    transition: all 0.2s ease-in-out;
    height: min(100%, calc(100% * {{result.0.calc_2.raw}}));

    & .tooltip {
      position: absolute;
      background: var(--tt-color);
      color: var(--tt-text-color);
      z-index: 2;
      padding: var(--tt-v-padding) var(--tt-h-padding);
      border-radius: 0 var(--tt-raidus) var(--tt-raidus);
      font-size: var(--tt-size);
      line-height: 1;
      left: calc(var(--tt-left-shift) + 1em / var(--tt-arrow-width));
      top: calc(-1em + var(--tt-top-shift) - var(--tt-v-padding));
      top: 0;
    }
    & .tooltip-arrow {
      position: absolute;
      content: "";
      border-top: calc(var(--tt-size) / var(--tt-arrow-height)) solid transparent;
      border-bottom: calc(var(--tt-size) / var(--tt-arrow-height)) solid transparent;
      border-right: calc(var(--tt-size) / var(--tt-arrow-width)) solid var(--tt-color);
      left: calc(1% + var(--tt-left-shift));
      top: 0;
    }
  }

  .markers {
    position: absolute;
    height: 59%;
    top: 20%;
    width: 50%;
    border-top: var(--t-marker);
    border-bottom: var(--t-marker);

    & .middle {
      content: "";
      height: 34%;
      width: 100%;
      top: 32%;
      position: absolute;
      border-top: var(--t-marker);
      border-bottom: var(--t-marker);
    }
  }

  .celebrate {
    --stars-width: calc(var(--t-width) * 6);
    width: var(--stars-width);
    height: var(--stars-width);
    left: calc(-1 * var(--stars-width) + var(--stars-width) / 2 + var(--t-border-width) * 2);
    top: calc(-1 * var(--t-bulb-diam));
    position: absolute;
    margin-bottom: calc(--t-height);
    font-size: 2px;
  }

  .star {
    position: absolute;
    line-height: 1;
    opacity: 0;

    &:nth-child(1) { transition-duration: 0.5s; font-size: 10px; top: 55%; left: 27%; }
    &:nth-child(2) { transition-duration: 1.2s; font-size: 15px; top: 35%; left: 8%; }
    &:nth-child(3) { transition-duration: 0.3s; font-size: 18px; top: 100%; right: 32%; }
    &:nth-child(4) { transition-duration: 0.8s; font-size: 30px; top: 75%; left: 14% }
    &:nth-child(5) { transition-duration: 1.1s; font-size: 25px; top: 53%; right: 5%; }
    &:nth-child(6) { transition-duration: 1.5s; font-size: 22px; top: 15%; left: 58%; }
    &:nth-child(7) { transition-duration: 0.5s; font-size: 18px; top: 18%; left: 24%}
    &:nth-child(8) { transition-duration: 0.7s; font-size: 13px; top: 77%; right: 17% }
  }
  .celebrate.yes .star {
    opacity: 1;
    transition-property: all;
    transition-timing-function: ease-in-out;
  }
}

</style>

<section class="wrapper">
  <article class="thermometer">
    <div class="border-cover"></div>
    <div class="temperature">
      <div class="tooltip">{{result.0.users.count.value_static}}</div>
      <div class="tooltip-arrow"></div>
    </div>
    <div class="markers"><span class="middle"></span></div>
    <div class="celebrate {{result.0.calc_3.raw}}">
      <div class="star">⭐️</div>
      <div class="star">⭐️</div>
      <div class="star">⭐️</div>
      <div class="star">⭐️</div>
      <div class="star">⭐️</div>
      <div class="star">⭐</div>
      <div class="star">⭐️</div>
      <div class="star">⭐️</div>
    </div>
    <div class="bulb"></div>
  </article>
  <h6>Target: {{result.0.calc_1.value_static}}</h6>
</section>
```


# Uptime heatmaps
Source: https://docs.omni.co/showcase/visualizations/uptime-heatmaps

The code for these examples can be used in the Markdown visualization to heatmap that colors each time slot based on a percentage value.

Typically used to show the reliability of a service over time, these can be configured for different timeframes or coloring thresholds.

## Red/green uptime heatmap

This example shows the last 30 days of data, coloring any day red if the service level percentage is anything but 100%.

<img alt="" />

### Setup

This chart has a simple structure - the time slot and a % value for each chart you want to make. [Add column totals to the query](/analyze-explore/point-click-queries#column-totals) and change the total calculation to `average` to add the average uptime below each chart.

<img alt="" />

### Example code

```html expandable theme={null}
<style>
  h3:first-of-type { margin-top: 0; }
  h3 { margin-bottom: var(--size2); }
  ul.grids {
    display: grid;
    list-style: none;
    margin: 0;
    padding: 0;
    grid-template-columns: repeat(30, 1fr);
    gap: 2px;

    & li {
      font-size: 8px;
      background: #E93323;
      display: block;
      width: 100%;
      height: 32px;
    }
    
    & li.uptime-1 {
      background: #84C982;
    }
  }

  ul.labels {
    display: flex;
    flex-direction: row;
    list-style: none;
    justify-content: space-between;
    padding: 0;
    margin: 0;
    font-size: var(--font-xs);
    color: var(--color-text2);
  }
</style>
<h3>Service A</h3>
<ul class="grids">
{{#result}}
<li class="uptime-{{uptime_data.service_a.raw}}">&nbsp;</li>
{{/result}}
</ul>
<ul class="labels">
  <li>30 days ago</li>
  <li>Service A uptime</li>
  <li>today</li>
</ul>

<h3>Service B</h3>
<ul class="grids">
{{#result}}
<li class="uptime-{{uptime_data.service_b.raw}}">&nbsp;</li>
{{/result}}
</ul>
<ul class="labels">
  <li>30 days ago</li>
  <li>Service B uptime</li>
  <li>today</li>
</ul>

<h3>Service C</h3>
<ul class="grids">
{{#result}}
<li class="uptime-{{uptime_data.service_c.raw}}">&nbsp;</li>
{{/result}}
</ul>
<ul class="labels">
  <li>30 days ago</li>
  <li>Service C uptime</li>
  <li>today</li>
</ul>
```

## Gradient uptime heatmap

This example shows the last 30 days of data, bucketing the colors along a red to yellow to green gradient. It also adds colored text to explain the current status.

<img alt="" />

### Setup

You'll need a column for the time unit, a column for the percentage measurement, and a calculation to figure out how to apply the color. The gradient in this example is bucketed into 5 possible values. Adjust the calculation for `Color tier` to control how the coloring is applied. [Add column totals to the query](/analyze-explore/point-click-queries#column-totals) and change the total calculation to `average` to add the average uptime below each chart.

Note that this example invents an uptime percentage value via a calculation.

The following table explains the query setup, including the calculation formulas.

| Col | Name                  | Description or formula                                                  | Purpose                     |
| --- | --------------------- | ----------------------------------------------------------------------- | --------------------------- |
| A   | Date                  | Time unit slot                                                          | used for drawing each box   |
| B   | Uptime (`calc_1`)     | Uptime value                                                            | 0-1 value for the time slot |
| C   | Color tier (`calc_2`) | IF(B1 > 0.75, 1, IF(B1 > 0.7, 2, IF(B1 > 0.65, 3, IF(B1 > 0.6, 4, 5)))) | Bucket-ize the uptime value |

### Example code

```html expandable theme={null}
<style>
  --l1: #76AD2D;
  --l2: #B0AB29;
  --l3: #E5A924;
  --l4: #E37F32;
  --l5: #E04345;
  
  h3 { 
    margin-block: 0 var(--size1);
    display: flex;
    flex-direction: row;
    justify-content: space-between;
    align-items: baseline;

    & .status {
      font-size: var(--font-sm);
      display: none;
    }
    & .status.level-1.operational {
      display: block;
      color: var(--l1);
    }
    & .status.level-2.impacted {
      display: block;
      color: var(--l2);
    }
    & .status.level-3.impacted{
      display: block;
      color: var(--l3);
    }
    & .status.level-4.impacted, {
      display: block;
      color: var(--l4);
    }
    & .status.level-5.down {
      display: block;
      color: var(--l5);
    }
  }
  ul.uptime {
    display: grid;
    list-style: none;
    margin: 0;
    padding: 0;
    grid-template-columns: repeat(30, 1fr);
    gap: 4px;

    & li {
      font-size: 8px;
      background: lightblue;
      display: block;
      width: 100%;
      height: 48px;
      border-radius: 2px;
    }
    
    & li.uptime-1 {
      background: var(--l1);
    }
    & li.uptime-2 {
      background: var(--l2);
    }
    & li.uptime-3 {
      background: var(--l3);
    }
    & li.uptime-4 {
      background: var(--l4);
    }
    & li.uptime-5 {
      background: var(--l5);
    }
  }

  ul.labels {
    display: flex;
    flex-direction: row;
    list-style: none;
    justify-content: space-between;
    padding: 0;
    margin: 0;
    font-size: var(--font-xs);
    color: var(--color-text2);
  }
p.notes {
  margin-top: var(--size8);
  color: var(--color-text1);
}  
</style>
<h3>Service A
  <span class="status level-{{result.29.calc_2.value}} operational">Operational</span>
  <span class="status level-{{result.29.calc_2.value}} impacted">Impacted</span>
  <span class="status level-{{result.29.calc_2.value}} down">Down</span>
</h3>
<ul class="uptime">
{{#result}}
<li class="uptime-{{calc_2.value}}">&nbsp;</li>
{{/result}}
</ul>
<ul class="labels">
  <li>30 days ago</li>
  <li>86.33 % uptime</li>
  <li>today</li>
</ul>
```


# User profile
Source: https://docs.omni.co/showcase/visualizations/user-profile

The code for this example can be used in a Markdown column to combine a user's name, email, and avatar into a single table column.

The code for these examples can be used in a Markdown column to combine a user's details—like their name, email, and an avatar—into a single [table](/visualize-present/visualizations/types/table) column.

For each example, select the column you want to format in the table visualization, set **Display as** to **Markdown**, and add the Markdown template and CSS. The fields are referenced using [Mustache syntax](/visualize-present/mustache-reference); replace them with your own fields.

## Name and email

This style stacks a bold name over a smaller, muted email in a single column.

<img alt="A table column showing each person's name in bold with their email address in smaller gray text below" />

### Setup

This example references the `name` and `email` fields from the `saas__users_detailed` view. Because the email is rendered inside the name column, you can [hide the original email column](/visualize-present/visualizations/types/table#showing-and-hiding-columns) so it doesn't appear twice in the table.

| Col | Name  | Description or formula | Purpose                        |
| --- | ----- | ---------------------- | ------------------------------ |
| A   | Name  | User's name field      | Shown as the bold primary text |
| B   | Email | User's email field     | Shown as the muted subtext     |

### Example code

**Markdown template**:

```handlebars wrap theme={null}
**{{saas__users_detailed.name.value}}**
<br>
<div style="color:#94a3b8;font-size:11px;">{{saas__users_detailed.email.value}}</div>
```

**CSS styles**:

No custom CSS is required for this example, so you can leave the **CSS style** field empty.

## Avatar with initials

This style adds a circular avatar showing each user's initials next to their name and email.

<img alt="A table column showing a colored circular avatar with each user's initials, next to their name in bold and email in smaller gray text" />

### Setup

This example adds a [calculation](/analyze-explore/calculations) that extracts the user's initials from their name—the first letter of the first name and the first letter of the last name, where column `A` is the name field. Set the initials calculation column to **Display as** **Markdown**, then hide the original name and email columns so only the combined profile renders.

The Markdown template references the initials calculation as `{{calc_1.value}}`. If your calculation has a different name, update the reference to match.

| Col | Name                | Description or formula                           | Purpose                                    |
| --- | ------------------- | ------------------------------------------------ | ------------------------------------------ |
| A   | Name                | User's name field                                | Bold primary text; source for the initials |
| B   | Email               | User's email field                               | Muted subtext                              |
| C   | Initials (`calc_1`) | `=LEFT(A5, 1) & MID(A5, (FIND(" ", A5) + 1), 1)` | First and last initial shown in the avatar |

### Example code

**Markdown template**:

```handlebars wrap theme={null}
<div style="display:flex; align-items:center; gap:10px; white-space:nowrap;">
  <div class="avatar-circle" style="display:flex; align-items:center; justify-content:center;">
    {{calc_1.value}}
  </div>
  <span style="display:flex; flex-direction:column;">
    <div class="avatar-name">{{saas__users_detailed.name.value}}</div>
    <div class="avatar-email">{{saas__users_detailed.email.value}}</div>
  </span>
</div>
```

**CSS styles**:

```css expandable theme={null}
<style>
  .avatar-row {
    display: flex;
    align-items: center;
    gap: 10px;
    white-space: nowrap;
  }

  .avatar-circle {
    width: 36px;
    height: 36px;
    min-width: 36px;
    border-radius: 50%;
    background: #6366f1;
    color: white;
    font-size: 13px;
    font-weight: 600;
    display: flex;
    align-items: center;
    justify-content: center;
    flex-shrink: 0;
  }

  .avatar-text {
    display: flex;
    flex-direction: column;
    line-height: 1.3;
  }

  .avatar-name {
    font-weight: 600;
  }

  .avatar-email {
    font-size: 12px;
    color: #888;
  }
</style>
```


# Word cloud
Source: https://docs.omni.co/showcase/visualizations/word-cloud

The code for these examples can be used in the Markdown visualization to create word cloud. In this example, text is horizontal and loosely spaced.

The presentation is more "festival poster lineup" when sorted by the sizing value, and more "cloudy" when sorted by a different value.

|                            |                                 |
| -------------------------- | ------------------------------- |
| **Sorted by sizing value** | **Sorted by a different value** |
| <img alt="" />             | <img alt="" />                  |

## Example code

Fonts are clamped between `--min-font-size` and `--max-font-size`. If you use container query units (cqw) for the max font size, the type will adjust to the width of the dashboard tile. Note that the max font size is a bit of a "magic number" meaning you'll have to adjust it based on the length of the words in your data set, the number of words in the results, and the desired size of the tile. The values in the example below were selected for this particular data set.

Example query showing calculation for percentage sizing and an example calculation for determining text color:

<img alt="" />

```html expandable theme={null}
<style>
.sky {
  --min-font-size: 10px; /* smallest text size */
  --max-font-size: 17cqw; /* biggest text sizes based on tile width */
  container-type: size;
  container-name: sky;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
}
.clouds {
  text-align: center;
  display: flex;
  gap: 0;
  flex-direction: row;
  align-items: center;
  justify-content: center;
  flex-wrap: wrap;
  font-size: var(--max-font-size);
}
.cloud {
  display: inline-block;
  padding-inline: 0.25em;
  padding-block: 0;
  margin: 0;
  vertical-align: center;
  white-space: nowrap;
}
.cloud.yes { color: darkmagenta; }
.cloud.no { color: magenta; }

</style>
<article class="sky">
  <div class="clouds">
  {{#result}}
    <p class="cloud {{calc_2.value_static}}" style="font-size: clamp(var(--min-font-size), calc(1em * {{calc_3.value_static}}), 1em); line-height: 1;">{{users.state.value}}</p>
  {{/result}}
  </div>
</article>
```


# Apps
Source: https://docs.omni.co/visualize-present/apps/index

Build bespoke, fully custom data experiences — backed by live, governed data.

Apps let you go beyond dashboards. Where a dashboard arranges charts on a grid, an app is a fully custom HTML and JavaScript interface — with its own layout, components, and interactivity — powered by live queries from your workbook.

The data behind an app is the same governed data that powers everything else in Omni. Each query the app reads lives in the workbook, where anyone with access can open it, inspect the SQL and semantic model behind it, and tune it. The app is a new way to present and interact with those results: all the flexibility of an AI-generated artifact, hosted, shareable, and governed in Omni.

<Columns>
  <Frame>
    <img alt="Diagram showing the architecture of the system" />
  </Frame>

  <Frame>
    <img alt="Diagram showing the architecture of the system" />
  </Frame>
</Columns>

## Enabling apps

Apps are enabled by default. An **Organization Admin** can toggle the **Enable apps** setting in [**Settings > Apps**](/administration/settings/app-policy) to disable them if needed.

Additionally, Organization Admins can restrict individual users or groups from creating apps through a granular permission on a [custom role](/administration/users/custom-roles#permissions-reference).

The same tab carries the [external source policy](/administration/settings/app-policy#external-source-policy), which sets the organization-wide ceiling on the external hosts any app may load resources from.

## When to use apps

Reach for an app when a dashboard's grid of tiles isn't expressive enough — when you want a custom layout, a guided interface, a calculator or tool, or a presentation that doesn't fit a standard chart.

## Creating apps

<Note>
  The **Enable apps** setting in [**Settings > Apps**](/administration/settings/app-policy) must be enabled to create apps.
</Note>

Every app is paired with a workbook. The workbook holds the queries and the app is the custom interface on top of them.

<Tabs>
  <Tab title="Omni Agent" icon="comment">
    <SideBySide alt="Describe the app you want to the Omni agent">
      The fastest way to build an app is to describe what you want to the [Omni Agent](/ai/chat). For example:

      > *"Build a sales leaderboard with a podium for the top three reps by quota attainment and a searchable ranking for everyone else"*
    </SideBySide>

    You can do this:

    * **In a chat** — Describe the interface and the data it should show in the Omni Agent. The agent generates each query the app needs against your model, writes the HTML, and wires it to the data. When it's done, the app opens in the editor, where you can keep iterating in chat or by hand.

    * **In a workbook** — Ask the [Omni Agent](/ai/queries) to turn your current workbook into an app. The app attaches to that workbook and reads its existing tabs. The agent uses every query tab unless you ask it to use a specific subset, and reports which tabs it skipped. If you reference a tab name that doesn't exist, the tool will fail and list the real tab names.

    If the workbook hasn't been saved yet, it's saved to **My documents** first.
  </Tab>

  <Tab title="Omni UI" icon="window-maximize">
    To start from scratch, open the dropdown next to the **+ Dashboard** button in a draft workbook and choose **App**. Omni creates the app with a starter template you can build on in the editor.

    <Frame>
      <img alt="Manual App Build" />
    </Frame>
  </Tab>
</Tabs>

## Editing apps

Open an app and click **Edit** in the top right corner of the workbook to enter a draft.

The editor has two panels: a live preview of your app running against real data, and a code editor for the HTML (click **Code** in the toolbar to show or hide it). If you have access to the agent, the chat split-view opens alongside the editor so you can iterate with AI as you go.

When you ask the agent to change an app, it will make targeted edits by locating the exact snippet in the code and only modifying the relevant portions. Each edit appears in chat as a diff preview showing precisely what changed.

If a partial edit can't be applied — for example, if the target code has changed — the agent will retry with more context or, as a last resort, rewrite the affected section of HTML.

The agent can also automatically detect and fix runtime errors in the app while you're working on a draft. This is possible only while you're editing the app in a draft.

### Styling apps

Apps automatically have access to Omni's design system CSS variables and your organization's custom theme styles. This allows you to build interfaces that match Omni's look and feel and your organization's branding, with automatic support for light and dark mode. See [Styling apps](/visualize-present/apps/styling) for details.

### Access Warnings

When editing a draft app, an **Access Warnings** button may appear in the edit toolbar. This button shows which tiles will be restricted for Viewer and Restricted Querier users, helping you identify accessibility issues before publishing. When clicked, a popover lists the specific tiles that will be restricted and explains why users with limited permissions won't be able to see them.

The Access Warnings button only appears when all of the following conditions are met:

* You are editing a draft app
* Restricted Queriers or Viewers have access to the underlying model
* One or more tiles in the app are restricted

See [Access Warnings](/share#access-warnings) for more information about Access Warnings and how to resolve them.

## Filters

When an app applies dynamic filters to its data (for example, when you interact with custom controls in the app interface), those filter values are automatically saved to the URL as `af--` query parameters. This gives apps the same filter persistence that dashboards have.

Reloading the app, sharing the link, or opening it in a new tab will restore the filtered state. Using your browser's back and forward buttons steps through filter changes, so you can navigate through the app's filter history.

## Writing to input columns

Apps can write values back to [input columns](/analyze-explore/input-columns) — the editable columns a workbook author adds to a query. This lets an app collect input from the people using it, such as a triage state, a review score, or a forecast override, and persist it the same way input columns persist everywhere else in Omni.

An app can write to an input column, but it can't create one yet. The workbook must already have the [input column configured](/analyze-explore/input-columns#adding-an-input-column).

Describe the behavior to the [Omni Agent](/ai/chat) when you build or edit the app. For example:

> Show open opportunities as cards. Add a **Mark as in call** button to each card that writes Yes to the `in_call` input column for that opportunity.

The agent finds the input column on the query, sends the correct key values with each write, and surfaces failures in the app.

Written values appear in the query results the next time the query runs.

Writes respect the input column's [edit mode](/analyze-explore/input-columns#edit-modes) and the viewer's row-level data access, so an app can't be used to write around either.

## Calling the Omni API

Apps can call a small allowlist of Omni API endpoints. This lets an app read Omni's own metadata — the viewer's identity, the content they can open, the models they can query — so you can build homepages, navigation portals, content catalogs, and data dictionaries that stay current on their own.

Calls run with the permissions of the person viewing the app. Two people opening the same app can get different results, and an app can never show someone more than they could see in Omni itself.

Access is read-only. An app can read metadata through these endpoints, but it can't change anything with them.

### What you can build

* **Homepages and navigation** — a branded landing page of the viewer's favorites and recents, each tile linking into the real dashboard
* **Curated content portals** — a Verified reports hub filtered by label, or a per-team portal driven by folders
* **Search experiences** — a custom search box over everything the viewer can open, styled to your brand, for embeds where Omni's own navigation isn't available
* **Data dictionaries** — a self-serve catalog of every view, dimension, and measure in a model
* **Live ERDs** — an always-current diagram of topics and their join relationships, drawn from the model itself

Describe what you want to the [Omni Agent](/ai/chat) and it will use these endpoints for you.

### Available endpoints

| Endpoint                                                                       | Returns                                                                                                                                      | Parameters                                                                                                                  |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `/api/v1/whoami`                                                               | The viewer's identity, organization role, and resolved per-model permissions                                                                 | `modelId` (comma-separated) to filter the models reported                                                                   |
| `/api/v1/content/search`                                                       | Free-text search over the dashboards the viewer can open                                                                                     | `q`, `limit`                                                                                                                |
| `/api/v1/folders`                                                              | The folders the viewer can see                                                                                                               | Paging, `sortField` (`name`, `path`)                                                                                        |
| `/api/v1/documents`                                                            | The published content the viewer can open — dashboards, workbooks, reports, and apps, each with its URL. The main browse-and-filter endpoint | Paging, `folderId`, `creatorId`, `labels`, `include` (`_count`, `labels`, `onlyFavorites`, `onlySharedWithMe`), `sortField` |
| `/api/v1/documents/<identifier>`                                               | One published dashboard's name, description, and query presentations                                                                         | None                                                                                                                        |
| `/api/v1/labels`, `/api/v1/labels/<name>`                                      | Your organization's label taxonomy, for browse and filter interfaces                                                                         | None                                                                                                                        |
| `/api/v1/ai/branding`                                                          | The AI assistant's name, logo URL, and copy, so an app can match Omni's chrome                                                               | None                                                                                                                        |
| `/api/v1/models`                                                               | The models the viewer can see                                                                                                                | Paging, `sortField` (`name`, `modelKind`, `connectionId`, `baseModelId`, `createdAt`, `updatedAt`)                          |
| `/api/v1/models/<modelId>/view`                                                | Every view in the model with its dimensions, measures, and filter-only fields                                                                | None                                                                                                                        |
| `/api/v1/models/<modelId>/topic`, `/api/v1/models/<modelId>/topic/<topicName>` | The model's topics; the detail response includes join relationships                                                                          | None                                                                                                                        |

## Inspecting app elements

When editing a draft app, an **Inspect** button appears in the edit toolbar, allowing you to select elements in the running app and send them as annotated images to the Omni Agent for context. See [Using the App inspector](/visualize-present/apps/inspect) for more information.

## Settings

Apps run in a sandboxed iframe with [strict security controls](#security) by default. App-level settings let you enable specific features on a per-app basis, giving you fine-grained control over what each app can do. For example, enabling app settings can allow you to:

* Load resources like images and fonts from a list of allowed domains
* Render map tiles using keyless providers such as Carto
* Open links to external sites or navigate to other pages inside Omni
* Copy text or values to the clipboard from a button in the app

See [App settings](/visualize-present/apps/settings) for more information.

## Embedding apps

Apps can be embedded in your own product with the same [SSO embed](/embed/setup/standard-sso) flow used for dashboards and workbooks. Point [`contentPath`](/embed/setup/url-parameters/contentPath) at the app and everything else about the session — [modes](/embed/setup/url-parameters/mode), user attributes, connection roles, filters — behaves as it does for a dashboard. Embedded apps also work with Omni's [embed events](/embed/events).

<Warning>
  You are responsible for the code in any app you embed. Omni does not review or validate app code. Before you embed an app, confirm your organization's [external source policy](/administration/settings/app-policy#external-source-policy) — it governs which external hosts apps can reach.
</Warning>

## Limitations

Apps support up to 100 wired queries per app. This limit applies to the total number of queries referenced in an app's workbook.

The following capabilities are not yet supported for apps:

* Scheduling and deliveries

## Security

<Steps>
  <Step title="Apps run in a sandboxed iframe" icon="shield">
    Each app runs inside a sandboxed iframe that blocks outbound network requests. App code can't call third-party services or open its own connection to your data — it only works with what Omni passes in, so there's no route for it to send your data anywhere. [Omni API calls](#calling-the-omni-api) are no exception: the app names an endpoint and Omni makes the request on the server, against a fixed allowlist. No API key or credential ever reaches the app.

    Specific features that require widening the iframe's security policy (such as loading map tiles, allowing navigation, or displaying externally-hosted images) can be enabled on a per-app basis through [app settings](/visualize-present/apps/settings). These settings are off by default and must be explicitly enabled by an editor.

    However, inline images can be displayed without configuring a [Safe domain allowlist](/visualize-present/apps/settings#configure-safe-domains). This includes inline base64 images (`data:` URIs) and canvas-generated images (`blob:` URIs), as they are both rendered within the iframe without making network requests.
  </Step>

  <Step title="Data access stays governed" icon="lock">
    An app can't query your warehouse directly. The only data it sees is the results of its workbook's queries, which Omni passes into the iframe. Every app inherits the access rules already in place — connection permissions, the semantic model and data permissions, and content sharing all carry over.

    The same holds for the two ways an app reaches beyond its own query results. [Input column writes](#writing-to-input-columns) respect the column's edit mode and the writer's row-level data access. [Omni API calls](#calling-the-omni-api) run with the permissions of the person viewing the app, so two people can get different results from the same app, and an app can never widen anyone's access.
  </Step>

  <Step title="Only trusted libraries can load" icon="handshake">
    Apps can load charting, styling, and font libraries from a short list of trusted CDNs, but nothing else. App editors can optionally configure [Safe domains](/visualize-present/apps/settings#safe-domains) to load resources from additional trusted hosts beyond the default CDNs, within whatever ceiling the organization's [external source policy](/administration/settings/app-policy#external-source-policy) sets.
  </Step>
</Steps>


# Inspecting App elements
Source: https://docs.omni.co/visualize-present/apps/inspect

Select elements in draft apps and send them to the Omni Agent as context.

The app inspector allows you to select elements in a draft app and send them as annotated images to the Omni Agent as context. This can be useful for focusing the agent on specific elements and resolving issues.

## Requirements

To use the inspector, you'll need:

* To be editing a draft app
* Access to the Omni Agent
* To have your organization's [**File uploads** AI setting](/ai/settings/features#file-uploads) enabled

When all of these conditions are met, an **Inspect** option will display in the app toolbar:

<Frame>
  <img />
</Frame>

## Inspecting app elements

To inspect an element:

1. Click the **Inspect** button in the toolbar to enter select mode
2. Click an element in the app to select
3. Enter a note about what you want the Agent to do

The annotated element is sent as an image to the Omni Agent, where you can ask questions or request changes:

<Frame>
  <img />
</Frame>

## Closing the inspector

Click the **Inspect** button again to leave select mode or to close an open annotation.

## Related

* [App overview](/visualize-present/apps)
* [Styling apps](/visualize-present/apps/styling)
* [App settings](/visualize-present/apps)


# App settings
Source: https://docs.omni.co/visualize-present/apps/settings

Configure per-app security and functionality settings to enable features like map rendering and link navigation in Apps.

[Apps](/visualize-present/apps) run in a sandboxed iframe with strict security controls by default. App-level settings let you enable specific features on a per-app basis, giving you fine-grained control over what each app can do.

## Requirements

**Editor permissions** or higher on a document are required to edit app settings.

## Accessing app settings

To access an app's settings:

1. In an app, click **Edit** to enter draft mode.
2. Near the top left corner of the page, click the <Icon icon="gear" /> icon (located next to <Icon icon="code" /> **Code**).

## Allow clipboard copy

Grants the app's iframe the `clipboard-write` permission. This allows apps to include copy buttons that programmatically write text or values to the user's clipboard.

Along with enabling this setting yourself, the Omni Agent can enable it automatically when you ask it to add a copy button or clipboard functionality to your app.

<Note>
  When an app with **Allow clipboard copy** enabled is itself embedded inside another product, the embedding iframe must also include `allow="clipboard-write"` for the grant to apply to the app. See [Allow copying in embed iframes](/embed/customization/iframes#allow-clipboard) for more information.
</Note>

## Allow map providers

Allows maps in your app to render tiles from keyless map providers. Along with enabling this setting yourself, the Omni Agent can enable it automatically when you ask it to add a map to your app.

When enabled, Omni widens the CSP to permit image and network requests to the following map providers' tile servers and the CDNs their libraries load from. No additional setup is needed.

| Provider      | Type                 | Library     |
| ------------- | -------------------- | ----------- |
| OpenStreetMap | Raster tiles         | Leaflet     |
| Carto         | Raster tiles         | Leaflet     |
| Carto         | Vector tiles (WebGL) | MapLibre GL |

## Safe domains

Optionally extends the app's security model by specifying additional trusted hosts for loading images, scripts, stylesheets, fonts, and network connections.

By default, apps can load resources from a curated list of trusted CDNs (e.g., Google Fonts, jsDelivr) and Omni's bundled charting, styling, and utility libraries. These are available regardless of your safe domain configuration.

<Note>
  Your organization's [external source policy](/administration/settings/app-policy#external-source-policy) sets the ceiling for this setting.
</Note>

### Configuring Safe domains

To configure safe domains for an app:

1. Open the [app's settings](#access-settings).
2. In the **Safe domains** section, toggle **Allow safe domains** on.
3. Enter one or more domains in the **Safe domains** field. Add one domain per line or separate using spaces or commas:

   <CodeGroup>
     ```text One domain per line theme={null}
      cdn.example.com
      *.assets.acme.co
     ```

     ```text Comma-separated theme={null}
     cdn.example.com, *.assets.acme.co
     ```

     ```text Space-separated theme={null}
     cdn.example.com *.assets.acme.co
     ```
   </CodeGroup>

   See [Domain formats](#domain-formats) for formatting requirements.
4. Click outside the text area to save. The domains are validated when you save.

Along with configuring safe domains yourself, the Omni Agent can configure safe domains when building or editing an app. For example, you can tell it *"load images from cdn.example.com"* and it will enable **Allow safe domains** and add the specified domain.

### Disabling Allow safe domains

If you disable **Allow safe domains**, all external access (excluding map providers if [**Allow map providers**](#allow-map-providers) is enabled) for the app will be disabled. Specified domains will be saved and can be re-enabled by toggling the setting back to on.

### Domain formats

<Tabs>
  <Tab title="Valid formats">
    **Safe domains** accepts the following formats:

    | Pattern                  | Examples                                                                                 |
    | ------------------------ | ---------------------------------------------------------------------------------------- |
    | Specific hosts           | `cdn.example.com`, `maps.acme.co`                                                        |
    | Subdomains with wildcard | `*.example.com` (matches `cdn.example.com`, `images.example.com`, but not `example.com`) |
    | Hosts with ports         | `assets.example.com:8080`                                                                |

    Each domain must:

    * Have at least two labels (e.g., `example.com` is valid, but `localhost` or `com` alone is not)
    * Use only lowercase letters, digits, hyphens, dots, and optionally a leading `*.` wildcard
    * Be 253 characters or fewer
    * Include a valid port (5 digits or fewer, numeric) if a port is specified

    For example:

    ```text Valid domains theme={null}
    cdn.example.com
    *.assets.acme.co
    tiles.mapserver.org:8080
    fonts.googleapis.com
    ```
  </Tab>
</Tabs>

## Navigation

Controls if and where an app can open links, covering both external websites and pages inside Omni.

Along with enabling these settings yourself, the [Omni Agent](/ai/chat) can enable these settings automatically when you ask it to add links or navigation to your app.

### Allow opening links

Allows the app to open external links. When enabled, you can also configure the [**Open external links in a new tab**](#open-links-new-tab) and [**Allow navigation domains**](#allow-navigation-domains) settings.

When this setting is enabled but navigation domains aren't configured, the app can open links to - and send data to - any site. Restrict where it can navigate by turning on [**Allow navigation domains**](#allow-navigation-domains) and listing trusted hosts.

#### Open external links in a new tab

Forces external links to open in a new tab, keeping the app on the current page. This is the default. The [Allow opening links](#allow-opening-links) setting must be enabled to configure this setting.

#### Allow navigation domains

Limits where the app can open links:

* **When disabled**, the app can open links to any site
* **When enabled**, the app can only open links to the hosts listed in the **Navigation domains** field. The [**Allow opening links**](#allow-opening-links) setting must be enabled to specify **Navigation domains**.

To restrict where an app can open links:

1. Open the [app's settings](#access-settings).
2. Enable [**Allow opening links**](#allow-opening-links).
3. Enable **Allow navigation domains**.
4. In the **Navigation domains** field, enter one or more hosts. Add one host per line, or separate them with commas or spaces. Wildcards like `*.example.com` are allowed:

   <CodeGroup>
     ```text One host per line theme={null}
     docs.example.com
     *.example.com
     ```

     ```text Comma-separated theme={null}
     docs.example.com, *.example.com
     ```

     ```text Space-separated theme={null}
     docs.example.com *.example.com
     ```
   </CodeGroup>

   Navigation domains follow the same formatting and validation rules as safe domains. See [Domain formats](#domain-formats) for accepted and disallowed patterns.
5. Click outside the text area to save.

### Allow internal navigation

Allows the app to navigate to other pages inside Omni — for example, a link that opens a dashboard.

This setting is independent of [**Allow opening links**](#allow-opening-links): you can allow internal navigation without allowing the app to open external links, and vice versa.

## Related

* [App overview](/visualize-present/apps)
* [Styling apps](/visualize-present/apps/styling)
* [App inspector](/visualize-present/apps/inspect)


# Styling Apps
Source: https://docs.omni.co/visualize-present/apps/styling

Use Omni's design system CSS variables and your organization's custom theme to build Apps that match your branding and adapt to light and dark mode automatically.

[Apps](/visualize-present/apps) automatically have access to Omni's design system CSS variables and your organization's [custom theme](/administration/themes/application). Referencing these variables lets you build interfaces that match Omni's look and feel, pick up your organization's branding, and adapt to light and dark mode without wiring up any of it yourself.

## How it works

The CSS variables for Omni's default theme, your organization's custom theme, and your organization's default discrete and continuous chart palettes are automatically available and optional to use in apps.

Apps that style themselves with hardcoded colors work unchanged, and Omni's variables only apply where you reference them, so they can't interfere with your own CSS.

## Using CSS variables

Reference any of these variables as a standard CSS custom property with `var()`:

```html theme={null}
<style>
  .card {
    background-color: var(--color-surface);
    color: var(--color-text4);
    border: 1px solid var(--color-border1);
    border-radius: var(--radius-md);
    padding: var(--size4);
  }

  .card__primary-action {
    background-color: var(--color-primary);
    color: var(--color-text-on-primary);
    border-radius: var(--radius-md);
  }
</style>

<div class="card">
  <p>Styled with Omni's design system.</p>
  <button class="card__primary-action">Run</button>
</div>
```

## Light and dark mode

The color variables are theme-aware: the same variable name resolves to a different value depending on the user's color scheme. When a user switches between light and dark mode in Omni, the values update automatically — you don't need to listen for any events or handle any messages.

Under the hood, Omni sets a color scheme class on the app's `<body>`:

* `prefers-light` in light mode
* `prefers-dark` in dark mode

You rarely need these classes directly, since the variables already adapt. Reach for them only when you want markup that differs beyond a color value:

```css theme={null}
body.prefers-dark .logo {
  /* show a light logo variant only in dark mode */
  filter: invert(1);
}
```

Omni also adds an `application-theme-{id}` class to `<body>` when your [organization has an active custom theme](#organization-custom-theme). This is what scopes your organization's theme overrides; you generally won't reference it yourself.

## Matching your organization's branding

When your organization has a [custom theme](/administration/themes/application), the following variables carry its brand values and fall back to sensible defaults otherwise. An app that uses these automatically matches the current Omni organization:

| Variable                  | Themed setting      |
| ------------------------- | ------------------- |
| `--color-primary`         | Primary color       |
| `--color-text-on-primary` | Primary text color  |
| `--color-notification`    | Notification color  |
| `--color-action-border`   | Action border color |
| `--color-action-text`     | Action text color   |
| `--font-body`             | Body font           |
| `--font-heading`          | Heading font        |

[Custom themes](/administration/themes/application) are configured by Organization Admins in **Settings > Theme**. If your organization hasn't set a custom theme, these variables will resolve to Omni's defaults.

You can also use your organization's [default discrete and continuous chart palettes](#charts) to build on-brand visualizations.

## Variable reference

The variables below are the recommended set for app styling. They're stable, always present, and adapt to light and dark mode.

### Backgrounds and surfaces

| Variable                   | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `--color-background`       | Page background; white in light mode                                 |
| `--color-background-alt`   | A subtly contrasting background, for sectioning                      |
| `--color-surface`          | Surfaces that sit on top of the background, such as cards and panels |
| `--color-elevated-surface` | Raised surfaces, such as menus and popovers                          |

Prefer `--color-background` for a clean look, and reach for `--color-background-alt` when contrast between sections helps the layout.

### Text

Text colors run from lower to higher contrast:

| Variable                  | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `--color-text1`           | Lowest contrast; secondary or muted text            |
| `--color-text2`           | Muted text                                          |
| `--color-text3`           | Standard body text                                  |
| `--color-text4`           | Highest contrast; headings and emphasis             |
| `--color-text`            | Black in light mode, white in dark mode             |
| `--color-text-inverse`    | Text on inverted backgrounds                        |
| `--color-text-on-primary` | Text placed on top of [`--color-primary`](#buttons) |

### Borders

| Variable          | Description     |
| ----------------- | --------------- |
| `--color-border1` | Lightest border |
| `--color-border2` | Medium border   |
| `--color-border3` | Heavy border    |
| `--color-border4` | Heaviest border |

### Buttons

| Variable          | Description                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `--color-primary` | The primary-action color. Pair it with [`--color-text-on-primary`](#text) for readable contrast. |

`--color-primary` is designed for primary buttons — avoid using it for general accents. If your design calls for a different button color, use your own value.

### Chart colors

<Note>
  These variables are optional to use and cap at 30 colors per palette. Only your organization's designated [default discrete and continuous palettes](/administration/chart-palettes/default) are accessible.
</Note>

| Variable                                                          | Description                                                                                                                                    |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--color-chart-1` through `--color-chart-N`                       | Discrete chart palette colors; limited to 30 colors. Each color resolves to a hex value from your organization's default discrete palette.     |
| `--color-chart-continuous-1` through `--color-chart-continuous-N` | Continuous chart palette colors; limited to 30 colors. Each color resolves to a hex value from your organization's default continuous palette. |

```html theme={null}
<style>
  .chart-bar {
    fill: var(--color-chart-1);
  }
  
  .chart-line {
    stroke: var(--color-chart-2);
  }
</style>

<svg width="200" height="100">
  <rect class="chart-bar" x="10" y="20" width="40" height="60" />
  <line class="chart-line" x1="60" y1="80" x2="150" y2="30" stroke-width="2" />
</svg>
```

### Fonts

| Variable         | Description                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `--font-body`    | Body font. Defaults to `system-ui, sans-serif`; overridable by your organization's theme. |
| `--font-heading` | Heading font. Defaults to `system-ui`; overridable by your organization's theme.          |
| `--font-code`    | Monospace font, for code and tabular figures                                              |

### Additional design system tokens

Omni also exposes the full design system for more advanced styling. These variables are less commonly needed but available:

* **Spacing** — `--size-unit` (the `0.25rem` base), the `--size0` through `--size24` scale, and the `--height1` through `--height8` vertical rhythm scale.
* **Border radius** — `--radius-xs`, `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`, `--radius-round`, and `--radius-none`.
* **Font sizes** — `--font-xxxs` through `--font-xxxxl`, and line heights `--line-height-xxs` through `--line-height-xxxl`.
* **Elevation (shadows)** — `--elevation0` through `--elevation4`.
* **Intent colors** — `--color-info`, `--color-success`, `--color-warn`, and `--color-critical`, each with tonal steps `1` through `4` (for example, `--color-info1` … `--color-info4`).


# Working with dashboard charts
Source: https://docs.omni.co/visualize-present/dashboards/charts

Add, edit, duplicate, hide, and configure chart tiles on Omni dashboards, including filter connections and background settings.

Chart tiles display the visualizations from your workbook queries on the dashboard. You can edit chart settings inline, hide tiles from viewers, copy them to other dashboards, and inspect the underlying queries.

## Editing charts

How you edit charts on a dashboard depends on the type of dashboard you're using:

<Tabs>
  <Tab title="New dashboard editor">
    When you select a chart item on a dashboard, the [properties panel](/visualize-present/dashboards/containers-items#accessing-the-properties-panel) will show chart settings inline, allowing you to edit visualization configuration without leaving the layout editor.

    In the properties panel, you can edit the chart's:

    * Title, subtitle, and description
    * Visualization type
    * Visualization settings such as colors, axes, stacking, and other display options

    Changes are saved automatically as you work.

    For more advanced editing capabilities, click the **Edit in workbook** button at the top of the properties panel. This opens the chart in the workbook where you have full configuration options for the visualization.
  </Tab>

  <Tab title="Classic dashboard editor">
    <Note>
      See [Upgrading classic dashboards](/visualize-present/dashboards/create#classic-dashboards) to learn how to upgrade your classic dashboard.
    </Note>

    To edit a chart on a classic dashboard, click the <Icon icon="ellipsis-vertical" type="solid" /> icon in the right corner of the tile. Then, click **Edit chart** to edit the chart on the dashboard or **Edit in workbook** to edit the chart in the workbook.
  </Tab>
</Tabs>

<Note>
  If your dashboard has filters and you're editing a chart in a workbook, note that workbook results may differ from what's on the dashboard. This is because dashboard filters aren't applied to workbook queries. However, you can easily add dashboard filters to the workbook query using the **Filters from dashboard** dropdown in the query's filter bar. See [Adding dashboard filters to workbook queries](/analyze-explore/queries/filters#adding-dashboard-filters-to-workbook-queries) for more information.
</Note>

### Adding chart subtitles and descriptions

Editing a chart on the dashboard allows you to add an optional subtitle and description to the chart.

To have Omni's AI write the subtitle or description, click the <Icon icon="star" /> icon and toggle **Let AI write the subtitle/description** to on.

You can also provide additional context to the AI to guide the results.

## Inserting query text items

Query text items display your query's name, subtitle, description, or AI-generated summary as dashboard content that maintains a live binding to the source query. Unlike static text tiles, query text items automatically update when you change the query's metadata in the workbook.

This is useful when you want dashboard titles, descriptions, or context to stay synchronized with query changes without manual updates.

To insert query text:

1. Right-click a chart tile in a container.
2. Select an option:
   * **Insert query text** - Insert the query's **title**, **subtitle**, **description**, or **All available**
   * **Insert AI summary** - Insert an inline or tooltip AI summary of the query. Use the properties panel to add additional context to the summary.
   * **Insert results** - Insert a table of the query's results

The insert behavior varies based on [container type](/visualize-present/dashboards/containers-items#containers):

| Type                                      | Description                                                                                                                                                  |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <Icon icon="grid-2" /> **Grid**           | The new item is inserted above the target item at the same horizontal position and width. Any overlapping items are automatically pushed down to make space. |
| <DashboardStackContainerIcon /> **Stack** | The new item is inserted before (above or to the left of) the target item in the stack's flow direction.                                                     |

### Converting metadata to editable text

Convert metadata items and AI summaries to editable text (or vice versa) by right-clicking on the chart and selecting **Convert to**:

<Frame>
  <img alt="Convert submenu for query metadata and AI summary items" />
</Frame>

Then, select the target:

* **Markdown text** - Converts the metadata item to a text tile with a [Mustache template](/visualize-present/dynamic-content) (e.g., `{{queries.<id>.name}}`) that preserves live binding to the query
* **AI summary** - Converts an editable text item to an AI-generated summary

Converting to editable text allows you to customize the presentation while maintaining the connection to the source query through template variables.

### Detaching and hiding query text items

Query text items can be detached from their source query or hidden from dashboard viewers.

#### Detaching query text items

When you detach a query text item from its source query, the item becomes static text that no longer updates when the underlying query metadata changes. This is different from converting to Markdown text, which preserves the live binding through Mustache templates:

* **Converting to Markdown text** - Maintains a live connection to the query via `{{queries.<id>.name}}` template syntax. The text updates automatically when query metadata changes.
* **Detaching** - Breaks the connection to the query. The text becomes static and will not update when query metadata changes.

Use detaching when you want to preserve the current text content but no longer need it to stay synchronized with query changes.

#### Hiding query text items

You can hide query text items from dashboard viewers while keeping them available for editing. This allows you to temporarily remove content from the dashboard view without deleting it.

## Hiding charts

In some cases, you may not want charts to be visible on the dashboard. The underlying data may be important for the workbook, but you don't want viewers to interact with the data. Other dashboard queries, however, can still access hidden tiles (with `XLOOKUP`).

<Note>
  Charts that are excluded from the dashboard will not run on the dashboard unless they are invoked by another query (i.e. XLOOKUP, alert, or used in a filter).
</Note>

<Tabs>
  <Tab title="New dashboard editor">
    Click the chart on the dashboard to open the properties panel. Then click the <Icon icon="trash" /> icon to remove it from the dashboard.

    Removing the chart in this way doesn't delete the underlying workbook query - it only removes the chart from the dashboard.
  </Tab>

  <Tab title="Classic dashboard editor">
    To hide a chart on a classic dashboard, click the **Charts** button near the top left corner of the page. This opens a panel on the left where you can manage the visibility of charts on the dashboard. Deselect a chart to exclude it from the dashboard:

    <img alt="" />
  </Tab>
</Tabs>

## Copying charts and links

On a chart, click the <Icon icon="ellipsis-vertical" type="solid" /> icon that displays. Then, select **Copy** to view options for copying charts and links:

* **To another dashboard or workbook**: Copy the tile to a different dashboard or workbook. This works similarly to [copying a workbook tab to an existing workbook](/analyze-explore/workbook-basics#copy-a-tab-to-an-existing-workbook).
* **Link to workbook tab**: Copy a direct link to the tile's underlying workbook tab to your clipboard

## Changing the background color of a chart tile

Tile background color is controlled at the dashboard level through [document themes](/visualize-present/dashboards/theming):

* Set the **Tiles > Background** theme value to change the background of all chart tiles on the dashboard. This accepts any CSS [background value](https://developer.mozilla.org/en-US/docs/Web/CSS/background), including solid colors and gradients.
* Set the **Page > Dashboard Background** theme value to change the color behind the tiles

## Interacting with table tiles

Dashboard tiles containing table visualizations support spreadsheet-style selection, copying, and cell interaction. Dashboard tables are read-only — editing, column reordering, and calculation features are only available in [workbook tables](/analyze-explore/point-click-queries#interacting-with-tables).

For a full list of keyboard shortcuts, see [Table shortcuts](/getting-started/keyboard-shortcuts#table-shortcuts).

### Selecting cells

* **Click** a cell to select it
* **Click and drag** across cells to select a rectangular region
* **Shift+click** a cell to select a range from the anchor to the clicked cell
* **Command+click** (Mac) or **Ctrl+click** (Windows) a cell to add or remove it from your selection
* **Click a row number** to select an entire row. Combine with **Shift** to extend the selection or **Command/Ctrl** to toggle the row.
* **Click a column header** to select an entire column. Combine with **Shift** to extend the selection or **Command/Ctrl** to toggle the column.
* **Arrow keys** to move the focused cell. Hold **Shift** to extend the selection.
* **Command+A** (Mac) or **Ctrl+A** (Windows) to select all cells
* **Escape** or **click outside** the table to clear the selection

### Copying cells

Select one or more cells, then press **Command+C** (Mac) or **Ctrl+C** (Windows) to copy the selected values to your clipboard. Copied data uses a tab-separated format, so pasting into Excel or Google Sheets automatically places values into the correct cells.

When all cells are selected with `Command` + `A` / `Ctrl` + `A`, column headers are included in the copied output.

### Context menu

Right-click a cell to open a context menu with options to drill, filter, copy, or expand the cell value.

## Inspecting chart queries

You can quickly access SQL debugging information for a chart by using the **Inspect** option. This opens the underlying workbook with the [Inspector panel](/analyze-explore/workbook-inspector) pre-opened, allowing you to view query SQL, cache status, and execution details.

To inspect a chart, click the <Icon icon="ellipsis-vertical" type="solid" /> (three dots icon) in the right corner of the tile, then click **Inspect**.

This feature requires the necessary permissions to analyze data and query SQL. For more information about viewing generated SQL, see [Inspecting query SQL](/analyze-explore/sql/generation#inspecting-query-sql).


# Building dashboard layouts with containers and items
Source: https://docs.omni.co/visualize-present/dashboards/containers-items

Organize charts, text, filters, and controls inside grid or stack containers for precise positioning.

<Note>
  **Using a classic dashboard?** [Upgrade it](/visualize-present/dashboards/create#classic-dashboards) to use the features in this guide.
</Note>

Dashboards are built from two components:

* **Items** — The charts, text, filters, and controls you place on the dashboard
* **Containers** — The regions that hold and arrange items

Containers can be nested inside other containers, letting you group related items, control spacing, and build structured layouts that go beyond the flat grid of a classic dashboard.

## Requirements

Modifying dashboard layouts requires **Editor**, **Manager**, or **Owner** permissions on the document.

<Note>
  Advanced dashboard layouts are enabled by default in embedded dashboards. If your organization needs to disable this feature for embeds, contact Omni support.
</Note>

## Working with containers

When you create a new dashboard or upgrade from a [classic dashboard](/visualize-present/dashboards/create#classic-dashboards), your existing items are placed into an initial container. From there, you can add more containers, configure how each arranges its items, and nest containers inside one another to shape your dashboard.

### Selecting a layout type

When you add a container to your dashboard, you choose between two layout types:

| Type                                      | Description                                                          | Best for                                                      |
| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
| <Icon icon="grid-2" /> **Grid**           | Free-form positioning; items can be placed at any position           | Precise control over each item's position                     |
| <DashboardStackContainerIcon /> **Stack** | Arrange items in columns or rows; you control spacing and alignment. | Structured sections such as a row of filters, a sidebar, etc. |

To add a container, click <DashboardAddItemIcon /> **Add > Layout** and select a layout type.

<Visibility>
  **Stack layout settings**

  In stack containers, you can control:

  * **Direction** - `column` (vertical) or `row` (horizontal)
  * **Gap** - Spacing between items
  * **Padding** - Spacing inside the container edges
  * **Wrap** - Controls whether items wrap to new lines when they exceed the container width (Yes = wrap, No = nowrap)
  * **Align** - How items align perpendicular to the direction (start, center, end, stretch)
  * **Justify** - How items are distributed along the direction (start, center, end, space between)
</Visibility>

### Naming containers

Each container can have a name to help you identify it while editing. To rename a container, select it and edit the **Name** field in the properties panel on the right side of the screen.

### Nesting containers

Containers can be placed inside other containers to build nested layouts. For example, place a stack container (set to row direction) inside a grid container to create a horizontal row of filters within a larger free-form layout.

### Resizing items in stack containers

<Note>
  Resize handles are currently only available for items in **column** stacks. Row stacks do not support manual resizing yet.
</Note>

Items within column stack containers can be resized by dragging resize handles, similar to resizing items in grid containers. This allows you to set specific dimensions for individual items while maintaining the automatic flow of the stack layout.

<Steps>
  <Step>
    Select the item you want to resize. Resize handles will display around the selected item.
  </Step>

  <Step>
    Drag a resize handle to adjust the item's dimensions.
  </Step>

  <Step>
    Release to apply the new size.
  </Step>
</Steps>

Resized items are sized in pixel values with a minimum size of 12px. Changes are previewed live as you drag and committed when you release the mouse.

To remove custom sizing, right-click the item and select **Reset sizing**. This removes all explicit sizing properties (width, height, and min/max constraints) and returns the item to its default automatic size.

### Locking container arrangements

You can lock a container to prevent its contents from being rearranged. Containers are unlocked by default until you explicitly lock them.

When a container is locked:

* Items inside the locked container cannot be dragged, reordered, resized, or have new items dropped into the container
* All child containers are also locked, preventing any rearrangement throughout the nested structure
* The locked container can still be moved and resized if its parent container is unlocked

#### Locking a container

<Steps>
  <Step>
    Select the container you want to lock.
  </Step>

  <Step>
    In the properties panel on the right, locate the <Icon icon="lock" /> icon.
  </Step>

  <Step>
    Click the <Icon icon="lock" /> icon to lock the container.
  </Step>
</Steps>

When you select an item inside a locked container, you'll see a lock indicator in the properties panel along with a message explaining that items in locked containers cannot be rearranged.

#### Unlocking a container

To unlock a container and allow its contents to be rearranged again, select the locked container and then click the <Icon icon="lock-open" /> icon in the properties panel.

## Adding and organizing items

Items can be added automatically — new queries from the workbook are placed on the first page, and page navigation appears when you create multiple pages — or manually from the dashboard's <DashboardAddItemIcon /> **Add** menu.

From there, you can move items between [containers](#containers), browse them in the <DashboardCatalogIcon /> **Catalog**, and edit their configuration without leaving the layout editor.

Dashboards currently support the following item types:

| Type                                         | Description                                                                                                                         |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| <DashboardChartIcon /> **Charts**            | [Visualizations](/visualize-present/dashboards/charts) from your workbook queries                                                   |
| <DashboardTextIcon /> **Text**               | Formatted text using [Markdown](/visualize-present/dashboards/text-markdown)                                                        |
| <Icon icon="filter" /> **Filters**           | [Interactive filters](/visualize-present/dashboards/filters) that control chart data                                                |
| <DashboardControlIcon /> **Controls**        | [Field controls](/visualize-present/dashboards/controls) that dynamically switch chart fields                                       |
| <DashboardPageNavIcon /> **Page navigation** | Inline page switcher for [multi-page dashboards](/visualize-present/dashboards/page-navigation)                                     |
| <DashboardPlaceholderIcon /> **Placeholder** | Wireframe element showing [placeholder content](/visualize-present/dashboards/placeholders) for queries, filters, controls, or text |
| <Icon icon="arrows-left-right" /> **Spacer** | Empty layout element for adding spacing between items                                                                               |
| <Icon icon="minus" /> **Divider**            | Separator line for creating visual divisions between items                                                                          |

### Adding items to a dashboard

Click <DashboardAddItemIcon /> **Add** in the toolbar to insert any item, a [layout container](#layout-type), or a new page.

Page navigation is automatically added when you create a second [dashboard page](/visualize-present/dashboards/pages), but you can also add it manually from the <DashboardLayoutIcon /> **Layout** submenu to place additional navigation or customize its position.

<Note>
  As pages are top-level elements, they can only be added from the toolbar <DashboardAddItemIcon /> **Add** menu, not from the **Add child** button in the properties panel.
</Note>

### Browsing items in the catalog

The catalog is a browsable library of all available items on your dashboard. Click the <DashboardCatalogIcon /> **Catalog** button in the toolbar to open it.

The catalog displays items in two groups:

* **Controls & filters** - All dashboard filters and controls, sorted alphabetically
* **Queries** - Charts and query visualizations

Use the search field at the top of the catalog to filter items by name. To place an item, click it in the catalog and then select the target container from the menu that appears.

The catalog is useful for finding items that haven't been placed yet or for quickly moving items into a specific container without selecting them on the canvas first.

<Note>
  New queries added to the workbook are automatically placed on the first page. If a query has been deleted, use the catalog to find and re-add it to the dashboard.
</Note>

### Placing items in containers

There are several ways to place items into a container:

<Tabs>
  <Tab title="Catalog">
    1. Click the <DashboardCatalogIcon /> **Catalog** button in the toolbar.
    2. Find the item you want to place. Use search to filter by name.
    3. Click the item.
    4. Select the target container from the placement menu.

    <Tip>
      Quickly add an item into an existing container by selecting the container and then using the **Add** or **Catalog** menus. You'll see an **Adds inside selection** option in the dropdown menu:

      <Frame>
        <img alt="Opened Add menu in an Omni dashboard, showing the Add inside selection option highlighted in blue" />
      </Frame>

      To instead add the item to the page root, click the <Icon icon="x" /> icon.
    </Tip>
  </Tab>

  <Tab title="Properties panel">
    1. Select the item you want to place on the canvas.
    2. In the properties panel on the right, click **Place** (for unplaced items) or **Move** (for items already in a container).
    3. A menu will appear showing all available containers.
    4. Click the target container to move the item into it.
  </Tab>

  <Tab title="Repositioning">
    You can drag items to reposition them within a container or move them between containers. This works for all [container layout types](#layout-type).

    | Within a...                                                   | Description                                                                                                                                                                         |
    | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <Icon icon="grid-2" /> **Grid container**                     | Drag items to any position and resize by dragging their edges                                                                                                                       |
    | <DashboardStackContainerIcon /> **Stack container**           | Drag items up or down (in column direction) or left and right (in row direction) to reorder them within the stack                                                                   |
    | <Icon icon="arrow-right-arrow-left" /> **Between containers** | Drag items from one container to another, regardless of container layout type. This lets you quickly reorganize your dashboard layout without using the catalog or properties panel |

    While dragging, Omni provides visual cues to help you place items:

    * Containers that can accept the item show a **colored outline** when you hover over them
    * Stack containers show a **drop indicator line** at the insertion point where the item will be placed
    * The container you're dragging from shows an outline to indicate the active drag operation
  </Tab>

  <Tab title="Re-adding">
    To re-add unplaced items to the dashboard, use the <DashboardCatalogIcon /> **Catalog**.
  </Tab>
</Tabs>

### Aligning filters and controls with tiles

When you place filters or controls directly on the page root alongside tile containers, Omni automatically applies a **Tile align** preset to ensure visual alignment. This preset adds padding to the filter or control that matches the outer spacing of tile containers, so they align cleanly as siblings on the grid.

#### Automatic preset behavior

<Note>
  The tile-align preset is only available for filters and controls. Charts and text items are not eligible for this preset.
</Note>

The tile-align preset is managed automatically based on where you place the item:

* **Auto-applied** — When you drag a filter or control into the page root grid (outside of any container), the preset is automatically applied
* **Auto-cleared** — When you move a filter or control into a tile container, the preset is automatically removed to prevent double spacing

When the preset is applied, Omni automatically adjusts the item's grid height (+1 unit) to account for the additional padding.

#### Manually changing the preset

To manually control the preset:

1. Select the filter or control on the canvas.
2. In the properties panel on the right, locate the **Preset** dropdown.
3. Select **Tile align** to apply the preset, or **None** to remove it.

### Duplicating containers and items

<Note>
  Duplication is not available for:

  * Pages - Use the [duplicate page](/visualize-present/dashboards/pages#duplicate-page) action instead
  * Filter and control items
</Note>

Duplicate existing containers and items to quickly create copies with the same configuration and styling.

You can duplicate a container or item in three ways:

* **Context menu** - Right-click the container or item and select **Duplicate**
* **Properties panel** - Select the container or item, then click the menu icon in the properties panel header and select **Duplicate**
* **Keyboard shortcut** - Select the container or item and press `⌘` + `D` (Mac) or `Ctrl` + `D` (Windows)

Where the duplicate appears depends on the parent container type:

| Parent container                          | Placement                                                                                                               |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| <DashboardStackContainerIcon /> **Stack** | The duplicate is inserted immediately after the original item                                                           |
| <Icon icon="grid-2" /> **Grid**           | The duplicate is placed directly below the original with the same dimensions, pushing down any items that would collide |

### Moving containers and items to another page

If you're working on a [multi-page dashboard](/visualize-present/dashboards/pages), you can move containers (and all they contain) and individual items to other pages on the dashboard.

Click on a container or item to select it, then click the **Move** button in the properties panel:

<Frame>
  <img alt="Opened move to page menu in the dashboard properties panel" />
</Frame>

Select **To page** and then click the page you want to move the content to.

## Accessing the properties panel

When the properties panel is closed, right-click on a dashboard item and select **Edit** from the context menu to open it.

You can also use keyboard shortcuts (`⌘` + `\` on Mac, `Ctrl` + `\` on Windows) to open the properties panel.

## Undoing and redoing layout changes

<Note>
  Only layout changes can be undone. This includes actions like adding, moving, or resizing containers and items, or adjusting container properties.
</Note>

When editing a dashboard, you can undo and redo layout changes using the **Edit** menu, toolbar buttons, or keyboard shortcuts:

* **Edit menu** - Click **Edit** > **Undo** or **Edit** > **Redo**
* **Toolbar** - Click the <Icon icon="rotate-left" /> (undo) or <Icon icon="rotate-right" /> (redo) icons in the editing toolbar
* **Keyboard shortcuts** - Press `⌘Z` (Mac) or `Ctrl+Z` (Windows) to undo, `⇧⌘Z` (Mac) or `⇧Ctrl+Z` (Windows) to redo

### History clearing

Your undo/redo history is automatically cleared when you make non-layout changes to the dashboard, such as:

* Renaming the dashboard or items
* Editing filter configurations
* Updating query definitions
* Changing dashboard settings

After a non-layout change, you won't be able to undo past that point. This ensures that layout changes and content changes remain independent and prevents conflicts between different types of edits.

## Controlling mobile behavior

Omni automatically adapts dashboard layouts for mobile devices, but you can override this behavior for individual [containers](#containers) to control how they display on smaller screens.

Each stack and grid container has an **On mobile** setting in the [properties panel](#accessing-the-properties-panel) that lets you choose how the container should behave on mobile devices:

| Option               | Description                                                                                                                                   | Available for   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| **Auto**             | Use Omni's automatic mobile layout (default)                                                                                                  | All containers  |
| **Stack vertically** | Force items to stack vertically, even if they're in a naturally-sized row. Applicable only to horizontal row layouts.                         | Row stacks only |
| **Wrap items**       | Keep items in a row layout that wraps to multiple lines. Applicable only to horizontal row layouts.                                           | Row stacks only |
| **Keep layout**      | Preserve the desktop layout exactly as designed, preventing automatic mobile adjustments. Applies to any containers nested within the parent. | All containers  |
| **Hide**             | Hide the container entirely on mobile devices                                                                                                 | All containers  |

<Tip>
  Use [mobile preview mode](/visualize-present/dashboards/preview-mode) to test how your mobile behavior settings look on smaller screens before sharing your dashboard.
</Tip>

## Next steps

* Use [pages](/visualize-present/dashboards/pages) to create multi-page dashboards, where each page has its own layout, items, and filters.
* Customize [page navigation](/visualize-present/dashboards/page-navigation) to control how viewers move between pages, including custom tabs and dynamic labels.
* Configure [filters](/visualize-present/dashboards/filter-display-options) to display filters as button toggles, multi-select dropdowns, single-day pickers, and timeframe controls.


# Dynamically displaying tile fields with controls
Source: https://docs.omni.co/visualize-present/dashboards/controls

Let dashboard viewers switch which fields appear in a tile using controls, enabling period-over-period comparisons and field swaps.

Controls allow you to choose which fields will be shown in a tile.

## Requirements

Creating and modifying controls requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Creating dashboard controls

To add a control to the dashboard, go into edit mode and click **Add > Control** in the toolbar. Configuring a control asks that you start by picking one of the underlying fields common to the tiles you want to control. Otherwise the control will have no impact (e.g. adding a field switcher between "order volume" and "total sales" to a tile that is showing "user count" will have no impact).

Like filters, when you are editing the control you can pick which tiles on the dashboard to connect by toggling the icon in the top right of each tile. You can also set default values and optionally hide the control from dashboard viewing.

## Control types

| Type                                                                         | Description                                                                                      |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| <Icon icon="shuffle" /> [**Field switcher**](#field-switcher)                | Swaps a single field for another within the same query                                           |
| <Icon icon="list-check" /> [**Multi-field picker**](#multi-field-picker)     | Selects one or more fields to show in a chart                                                    |
| <Icon icon="calendar-days" /> [**Timeframe switcher**](#timeframe-switcher)  | Controls the granularity of a date grouping                                                      |
| <Icon icon="timeline" /> [**Period over period**](#period-over-period)       | Compares metrics between time periods                                                            |
| <Icon icon="users-between-lines" /> [**Parent**](#parent)                    | Controls the toggling of multiple controls                                                       |
| <Icon icon="arrow-left-arrow-right" /> [**Dynamic filter**](#dynamic-filter) | Allows dashboard viewers to add filters to a published dashboard                                 |
| <Icon icon="ranking-star" /> [**Top N limit**](#top-n-limit)                 | Enables change the number of values (N) on a [Top N field](/analyze-explore/custom-fields/top-n) |

### Field switcher controls

Field switcher controls allow dashboard viewers to swap a single field for another field within the underlying query. When used with dimensions, this will change the grouping or breakdown of a query. For example, a field switcher with dimensions like `country`, `gender`, and `age group` allows viewers to slice the metrics in the connected tiles in different ways. When used with measures, the metric to be displayed in the connected charts will update.

Field switcher controls can have any number of fields. Typically field switchers are either all measures or dimensions, but they can be mixed. You can also add a `no field` option, which is useful when you want to offer viewers a way to see the total metric value or pick a dimension to change the grouping.

<Tip>
  The default field in a field switcher must be included as a field in your underlying query. 
</Tip>

### Multi-field picker controls

A multi-field picker control allows you to pick zero or more fields to show in a chart. While usually most useful on table visualizations, it can be connected to any chart tile on the dashboard.

#### Enable field reordering for viewers

Use the **Control manages field order** setting in the properties panel to let dashboard viewers to reorder fields they select from the control:

* **When enabled**, fields appear in the order they're selected in the control, even if the underlying query already includes them. Sorts, subtotals, pivots, fills, and transposition settings are preserved.
  **Note**: Measures cannot be placed between dimensions. If this occurs during field selection, Omni will automatically reorder the fields to place dimensions first, then measures.
* **When disabled**, fields already in the query keep their position and the control only adds or removes fields.

### Timeframe switcher controls

For date fields, you may want to provide a control to allow the viewer to change the granularity of the date grouping. For example, change a grouping from months to weeks or to days. Time frame switchers make this easy. When configuring, select the underlying date field to control and then select the time frames you want to make available.

### Period over period controls

To compare a metric between time periods, use a period over period control. When configuring, select the underlying date field that controls the time periods you want to compare. Choose the current period and one or more comparison periods. Any attached charts will break down the metric between the current and previous time period(s).

<img alt="" />

#### Mapping period over period controls to tiles

Period over period controls can only be applied to tiles that have queries with matching period over period computations. When editing a period over period control, Omni will disable the mapping option for tiles that don't include period over period computations and display a message in the properties panel.

If you need to apply a period over period control to a tile, ensure the underlying query includes period over period computations before attempting to map the control.

### Parent controls

A parent control coordinates the toggling of multiple controls at once. For example, consider a dashboard has a timeseries with a `created_at` date, another timeseries with a `received_at` date, and a timeseries with a `returned_at` date.

To coordinate the multiple timeseries fields, you would:

1. Build three timeframe switchers.
2. Add a parent control.
3. Configure the parent control's display options and connect the timeframe switchers as children.
4. Hide the child timeframe switchers.

<iframe title="Dashboard Parent Controls" />

### Dynamic fiilter controls

Dynamic filter controls let viewers add their own filters to a published dashboard without the creator having to predefine every filter option. This enables ad-hoc exploration while giving creators control over which fields viewers can filter on. See [Dynamic filter controls](/visualize-present/dashboards/dynamic-filter-controls) for more information.

### Top N limit controls

This control type allows dashboard viewers to change the number of values (N) on a [Top N field](/analyze-explore/custom-fields/top-n). Create the control and then map it directly to an existing Top N field in the tile's query.

<Warning>
  This control only works when mapped to a field that already has Top N configured. If the Top N field isn't present in the tile's query, the control will not do anything, including showing as disabled.

  If the field is present but isn't actually a Top N field, the tile's query will break. Omni's [content validator](/modeling/develop/content-validator) doesn't check this mapping - verify it manually after renaming or removing fields.
</Warning>


# Create a dashboard
Source: https://docs.omni.co/visualize-present/dashboards/create

Create a new dashboard from a workbook, or upgrade an existing classic dashboard to advanced layout.

Every dashboard starts from a workbook — the queries you've built there become the chart tiles on the dashboard. This page covers creating a new dashboard and upgrading an existing classic dashboard to the new dashboard editor. For design topics like layout, content items, and themes, see the [Dashboards overview](/visualize-present/dashboards).

## Requirements

Creating and upgrading dashboards requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Create a new dashboard

<Steps>
  <Step>
    In a **draft workbook**, click the **+ Dashboard** button in the top right corner of the document.
  </Step>

  <Step>
    Give the document a title. You can also add a description.
  </Step>

  <Step>
    Select where you want the document to be saved.
  </Step>

  <Step>
    Click **Save**. Omni redirects you to the dashboard.
  </Step>
</Steps>

To edit an existing dashboard, open it and click **Edit** in the top right corner of the document. If you're in the underlying workbook, click **Dashboard > Edit** instead.

## Edit the title or description

To update the title or description of an existing dashboard:

<Steps>
  <Step>
    Open the dashboard and click **Edit** in the top right corner to enter a draft.
  </Step>

  <Step>
    Click **Edit > Rename** from the top menu bar.
  </Step>

  <Step>
    Update the title and/or description, then save your changes.
  </Step>
</Steps>

## Upgrade a classic dashboard

On May 27, 2026, Omni released a new version of the dashboard editor. Dashboards created with the classic editor need to be upgraded before you can use layout components like containers and pages.

<Warning>
  Upgrading a classic dashboard is permanent and cannot be reverted. Test on a duplicate first by clicking **File > Duplicate**.
</Warning>

<Steps>
  <Step title="Open the dashboard in draft mode">
    Navigate to the dashboard you want to upgrade and click **Edit**.
  </Step>

  <Step title="Enable advanced layout">
    Click **File > Upgrade layout**. A confirmation dialog appears.
  </Step>

  <Step title="Confirm the upgrade">
    Click **Yes, Upgrade**. Your existing items are preserved and placed into an initial container.
  </Step>
</Steps>

## Next steps

Once your dashboard is created, head to the [Dashboards overview](/visualize-present/dashboards) for design topics — layout, content items, interactivity, and themes.


# Defining custom dashboard error and empty results messages
Source: https://docs.omni.co/visualize-present/dashboards/custom-state-message

Customize the messages that display on dashboards when queries encounter errors or don't return results.

Adding your own custom messages to dashboards allows you to not only apply your own branding, but to make the experience more friendly and intuitive for your users.

By default, Omni displays messages when a query encounters an error or doesn't return results:

<Columns>
  <Card title="No results returned">
    Default state for a query with no results returned
  </Card>

  <Card title="Error">
    Default state for a query in an error state
  </Card>
</Columns>

## Requirements

To follow the steps in this guide, you need **Editor** or **Manager** permissions on the document you want to modify.

## Steps

<Note>
  If a query has No Results and an Error state, No Results will take precedent with or without customization.
</Note>

1. Navigate to the dashboard you want to modify.

2. Click the **Edit** button in the upper right corner of the page to enter draft mode.

3. Click **Edit > Dashboard settings**.

4. Locate the **Custom messages** section:
   <img alt="" />

5. Click one of the message types to customize it.

6. Click the **Customize** toggle, which enables the Markdown editor. You can use [custom Markdown](/visualize-present/visualizations/types/markdown#using-the-markdown-editor) like the following to add and style your message:

   ```html wrap title="Example of custom Markdown No results message" theme={null}
   <style>
   div {
   display: flex;
   justify-content: center;
   align-items: center;
   }
   </style>
   <div>you don't have access to this data</div>
   <br>
   <div>![](https://github.com/RichardCzechowski/all-the-blobbies/blob/main/blobbies-slack/blobby-math.gif?raw=true)</div>
   ```

7. The preview of the message will update as you work. For example, this is the preview for the custom Markdown from the previous step:

   <img alt="" />

8. When finished, click **Update** to save your changes.

Now when a query on this example dashboard doesn't return results, this custom message will display:

<img alt="Custom message within a dashboard tile" />


# Removing a dashboard from a document
Source: https://docs.omni.co/visualize-present/dashboards/delete

Learn how to remove a dashboard from an Omni workbook document and what happens to associated schedules.

<Warning>
  Removing the dashboard from a document will also remove any schedules attached to the dashboard.
</Warning>

## Requirements

Along with the connection permissions to access the document, you'll need **Editor** or **Manager** content permissions.

## Steps

1. Click the **Edit** button on the dashboard to enter a draft of the document.
2. Navigate to **Edit > Dashboard settings**.
3. Click the **Remove** button.
4. When prompted, click **Remove dashboard** to confirm the removal.
5. Publish the document to apply the changes.


# Downloading dashboards
Source: https://docs.omni.co/visualize-present/dashboards/download

Download Omni dashboards as PDF or image files with options for paper size, orientation, zoom, and page layout customization.

If given the [ability](/share), you can download dashboards by navigating to **File > Download**.

Use the following options to customize the download:

| Name                                         | Supported formats | Description                                                                                                                                                                                                                                                     |
| -------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **File name**                                | n/a               | The name to be used for the downloaded file                                                                                                                                                                                                                     |
| **Format**                                   | n/a               | The format (file type) for the download. Includes PDF, PNG, XLSX, and CSV. For **CSV**, a ZIP folder will be created that contains a CSV for each tile on the dashboard.                                                                                        |
| **Paper size**                               | PDF               | Defines the paper format (size) of the resulting PDF                                                                                                                                                                                                            |
| **Expand tables**                            | PDF, PNG          | For table visualizations, include up to 1,000 rows in the results                                                                                                                                                                                               |
| **Arrange dashboard tiles in single column** | PDF, PNG          | Arrange dashboard tiles into a single vertical column                                                                                                                                                                                                           |
| **Hide title**                               | PDF, PNG          | Hides the content's title in the download                                                                                                                                                                                                                       |
| **Apply data formatting**                    | XLSX, CSV         | Preserve number and date formatting in the download                                                                                                                                                                                                             |
| **Exclude hidden columns**                   | XLSX, CSV         | Excludes fields marked as `hidden` from the download                                                                                                                                                                                                            |
| **Download all possible results**            | CSV               | Include all possible rows in the result, regardless of query limit                                                                                                                                                                                              |
| **Timezone override**                        | All               | Override the query timezone for the download. The picker pre-populates from your current timezone selection if the [timezone picker](/visualize-present/dashboards/timezone-override) is enabled.                                                               |
| **Pages**                                    | All               | **Applicable only to [dashboards with multiple pages](/visualize-present/dashboards/pages)**. Select the page(s) to include in the download. **Note**: PNGs can only include one page. You'll need to create multiple deliveries to output a PNG for each page. |


# Dynamic filter controls
Source: https://docs.omni.co/visualize-present/dashboards/dynamic-filter-controls

Let dashboard viewers add their own ad-hoc filters without pre-configuring every filter option.

Dynamic filter controls let viewers add their own filters to a published dashboard without the creator having to predefine every filter option. This enables ad-hoc exploration while giving creators control over which fields viewers can filter on.

<Frame>
  <img alt="Add filter field picker in an Omni dashboard" />
</Frame>

## Requirements

Creating and modifying dynamic filter controls requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Creating dynamic filter controls

<Steps>
  <Step title="Create the control">
    1. Open the dashboard in edit mode
    2. Click **Add > Control > Dynamic Filter Control** in the toolbar. The control editor panel will open on the right side of the page.
    3. Enter a **Label** and **Description**.
  </Step>

  <Step title="Define available fields">
    In the **Available fields** section, define how viewers will be able to interact with the filter:

    * **All fields** - Viewers can filter on any field in the model. New fields become available automatically.
    * **Automatically populate filter fields** - Include all fields from selected topics. Updates when selected topics are updated. When selected, you'll be prompted to choose topics to include.
    * **Manually populate filter fields** - Include only fields you select. When selected, you'll be prompted to choose fields to include.
  </Step>

  <Step title="Select display options">
    <Note>
      This step is optional.
    </Note>

    Use the options in the **Display options** section to configure how the field displays to dashboard viewers:

    * **Include view name in labels** - By default, only field names are included in filter chips. Selecting this option will also include the name of the view containing the field. This is helpful for allowing viewers to distinguish between fields with the same name from different views.
    * **Hide this control when viewing the dashboard** - Dashboard viewers will not see the control. However, the value can still be adjusted in [scheduled deliveries](/share/deliveries) and embedded links.
  </Step>
</Steps>

## Using dynamic filter controls as a viewer

When a dashboard viewer opens a published dashboard, they'll see an **Add filter** button:

<Frame>
  <img alt="Highlighted Add filter button under a dynamic filter control on an Omni dashboard" />
</Frame>

To add a filter:

1. Click **Add filter** on the dashboard.
2. Select a field from the picker. The available fields are determined by the filter's [**Available fields**](#available-fields) setting.
3. Choose filter values.

The filter will be immediately applied to all compatible tiles on the dashboard.

<Note>
  Viewer-added filters aren't saved to the dashboard.
</Note>

### Removing a filter

To remove a filter, hover over the filter and click the <Icon icon="x" /> that displays:

<Frame>
  <img alt="X removal icon displaying on a viewer-added filter in an Omni dashboard" />
</Frame>

## Limitations

* Dynamic filters are stored in the URL only and cannot be saved to the dashboard
* Filters don't apply to custom SQL queries unless they use [dynamic filtering](/analyze-explore/sql#custom-sql-filters)


# Filter display options
Source: https://docs.omni.co/visualize-present/dashboards/filter-display-options

Customize how filters appear on dashboards with button toggles, multi-select dropdowns, single-day pickers, and timeframe controls.

<Note>
  **Using a classic dashboard?** [Upgrade it](/visualize-present/dashboards/create#classic-dashboards) to use the features in this guide.
</Note>

String and date filters support additional display options beyond the standard [dashboard filter](/visualize-present/dashboards/filters) dropdown. Choose how each filter appears to viewers — as a row of button toggles, a multi-select dropdown, a single-day calendar, or a timeframe picker — to match the way they need to interact with your data.

## Requirements

Creating and modifying filters requires **Editor**, **Manager**, or **Owner** permissions on the document.

## String filter display options

String filters can be displayed in a few ways, including:

* [Buttons](#select-buttons), for both single and multiple selections
* [Dropdown list (multi-select)](#multi-value-dropdown)

### Displaying options as buttons

<Note>
  Filters must be placed inside a [container](/visualize-present/dashboards/containers-items) to use this display option.
</Note>

String filter values can be displayed as a row of buttons that users can click to select. This provides a more visual, accessible way to switch between options.

Button options can be displayed in two ways:

<Columns>
  <Card title="Inline">
    Displays inline with the dashboard content
  </Card>

  <Card title="Popover">
    Opens in an overlay when clicked
  </Card>
</Columns>

When a filter option is clicked, the queries connected to the filter will update.

By default, up to the first 50 values for the filter column are used as options. You can customize which values are included using the **Values** setting described below. Button options work best with a small number of choices, typically between two and seven.

To configure a string filter to display as buttons:

<Steps>
  <Step title="Add and configure the filter">
    1. Open a dashboard and enter draft mode by clicking **Edit**.
    2. Click **Add > Filter** to add a new filter.
    3. Configure the filter, clicking **Done** when finished.
  </Step>

  <Step title="Move the filter into a container">
    Next, you'll move the filter into a dashboard [container][containers-items]. This is required to access the filter's single selection options.

    1. At the top of the dashboard, click <DashboardCatalogIcon /> **Catalog**, then the filter. This will open the filter's properties panel on the right side of the page.
    2. In the filter properties panel, click **Move**.
    3. In the dropdown, select the container you want to move the filter to:

       <img alt="The filter properties panel with the Move dropdown open, showing available containers" />
  </Step>

  <Step title="Configure selection options">
    1. If the filter properties panel is no longer open, click the filter to open it.
    2. Configure the following fields:

       * **Filter type** - Select **Single selection** or **Multiple selection**
       * **Filter control** - Set to **Button toggle**
       * **Filter display** - Select **Inline** or **Popover**
       * **Values** - Define the options you want to include in the filter display:
         * **All values** - **Default**. Up to the first 50 values for the filter column will display.
         * **Select exact values** - Choose specific values to include. After selecting this option, a value picker will appear where you can check the values you want.
  </Step>
</Steps>

### Displaying multiple selection options as buttons

<Note>
  Filters must be placed inside a [container](/visualize-present/dashboards/containers-items) to use this display option.
</Note>

Multiple selection string filters can be displayed as a row of buttons that users can click to select. This provides a visual alternative to the multi-value dropdown, allowing users to see and select multiple filter values using button toggles.

Multiple selection button options can be displayed in two ways:

<Columns>
  <Card title="Inline">
    Displays inline with the dashboard content
  </Card>

  <Card title="Popover">
    Opens in an overlay when clicked
  </Card>
</Columns>

When filter options are clicked, the queries connected to the filter will update to include all selected values.

By default, up to the first 50 values for the filter column are used as options. You can customize which values are included using the **Values** setting described below. Button options work best with a small number of choices, typically between two and seven.

To configure a string filter for multiple selection with buttons:

<Steps>
  <Step title="Add and configure the filter">
    1. Open a dashboard and enter draft mode by clicking **Edit**.
    2. Click **Add > Filter** to add a new filter.
    3. Configure the filter, clicking **Done** when finished.
  </Step>

  <Step title="Move the filter into a container">
    Next, you'll move the filter into a dashboard [container][containers-items]. This is required to access the filter's button group options.

    1. At the top of the dashboard, click <DashboardCatalogIcon /> **Catalog**, then the filter. This will open the filter's properties panel on the right side of the page.
    2. In the filter properties panel, click **Move**.
    3. In the dropdown, select the container you want to move the filter to:

       <img alt="The filter properties panel with the Move dropdown open, showing available containers" />
  </Step>

  <Step title="Configure multiple selection button options">
    1. If the filter properties panel is no longer open, click the filter to open it.
    2. Configure the following fields:

       * **Filter type** - Set to **Multiple selection**
       * **Filter control** - Set to **Button group**
       * **Filter display** - Select **Inline** or **Popover**
       * **Values** - Define the options you want to include in the filter display:
         * **All values** - **Default**. Up to the first 50 values for the filter column will display.
         * **Select exact values** - Choose specific values to include. After selecting this option, a value picker will appear where you can check the values you want.
  </Step>
</Steps>

### Displaying multiple selection options as dropdowns

String filters can be configured to allow multiple value selection using a dropdown interface. This allows users to select several options at once, allowing viewers to filter data across multiple categories at once.

<img alt="Multiple selection filter with country options" />

Multiple selection dropdowns display inline with the dashboard content and provide a clear view of all selected values.

To configure a string filter for multiple selection:

<Steps>
  <Step title="Add and configure the filter">
    1. Open a dashboard and enter draft mode by clicking **Edit**.
    2. Click **Add > Filter** to add a new filter.
    3. Configure the filter, clicking **Done** when finished.
  </Step>

  <Step title="Configure multiple selection options">
    1. If the filter properties panel is no longer open, click the filter to open it.
    2. Configure the following fields:

       * **Filter type** - Set to **Multiple selection**
       * **Filter control** - Set to **Dropdown**. This is currently the only supported control type for multiple selection.
       * The filter will automatically display inline with your dashboard content.
  </Step>
</Steps>

## Date filter display options

Date filters can be displayed as a full range picker, a single-day calendar, or a timeframe control with preset options like "Last 7 days." Choose the interface that matches how viewers need to interact with dates in your dashboard.

### Selecting a date filter interface

When working with date filters, you can choose how the filter interface appears to users. First create the filter, then use the **Filter type** setting to choose a display option:

#### Default

The standard date filter interface with range selection and preset options:

<Frame>
  <img alt="Default (advanced) date filter with range selection and options" />
</Frame>

#### Single day

A simplified calendar interface that allows users to select a specific day. This is useful when you want to focus dashboard viewers on analyzing data for one date at a time, such as daily reports or date-specific snapshots.

<Frame>
  <img alt="Single day date filter" />
</Frame>

### Configuring timeframe selection

The timeframe filter control provides a user-friendly way to filter data by common time periods. Instead of selecting exact dates, users can choose from preset options like "Last 7 days" or "Last 30 days," and optionally define custom date ranges when needed.

This control is useful when your dashboard viewers need to quickly switch between common time windows without navigating a full date picker interface.

To configure a date filter to use the timeframe control:

<Steps>
  <Step title="Add and configure the filter">
    1. Open a dashboard and enter draft mode by clicking **Edit**.
    2. Click **Add > Filter** to add a new filter.
    3. Configure the filter with a date field, clicking **Done** when finished.
  </Step>

  <Step title="Set the filter control type">
    1. If the filter properties panel is no longer open, click the filter to open it.
    2. Set **Filter control** to **Timeframe**.
  </Step>

  <Step title="Select preset options">
    Choose which timeframe options to make available to users. You can select from Omni's preset options or create custom timeframes. The selected options will appear as choices in the filter control.
  </Step>

  <Step title="Enable custom timeframe (optional)">
    Toggle **Allow custom timeframe** to let users define their own date range when the preset options don't meet their needs.

    When enabled, a custom option appears in the filter. Selecting it will open a custom date range picker.
  </Step>
</Steps>

## Next steps

* Learn to [build dashboard layouts][containers-items] with containers and items like charts, text, filters, and controls.
* Use [pages](/visualize-present/dashboards/pages) to create multi-page dashboards, where each page has its own layout, items, and filters.
* Customize [page navigation](/visualize-present/dashboards/page-navigation) to control how viewers move between pages, including custom tabs and dynamic labels.

[containers-items]: /visualize-present/dashboards/containers-items


# Filter interactivity
Source: https://docs.omni.co/visualize-present/dashboards/filter-interactivity

Configure cross-filtering and faceted filters so viewers can interact with dashboards by clicking charts and linking related filters.

In addition to the standard [dashboard filter](/visualize-present/dashboards/filters) controls, Omni offers two ways to make filtering more interactive:

* **Cross-filtering** — viewers click chart elements to filter the rest of the dashboard
* **Faceted filters** — one filter narrows the options shown in another, for example a state filter narrowing a city filter to cities in that state

Both are off by default and configured per dashboard in the [dashboard's settings](/visualize-present/dashboards/settings).

## Requirements

Creating and modifying filters requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Cross-filtering

Cross-filtering lets viewers filter a dashboard by clicking elements in a chart. When a viewer clicks a data point, bar, or other element, they get the option to create a filter that applies across all compatible tiles.

Cross-filters apply to any tile with a joinable relationship to the filtered field through the [semantic model](/modeling). When a cross-filter is active, tiles that it can't filter will have a <Badge icon={<DisabledFilterIcon />} /> badge, which you can hover over to see why.

### Supported visualization types

Cross-filtering works with:

* Vega-Lite charts (bar, line, area, scatter, heatmap)
* Pie and donut charts
* Maps (choropleth and point)
* Data tables
* Sankey

### Enabling cross-filtering

Cross-filtering is off by default. Enable it in the [dashboard's settings](/visualize-present/dashboards/settings).

### Creating a cross-filter

There are several ways to create a cross-filter from a chart:

* **Click-to-filter** — click any chart element to filter the dashboard by that value
* **Brush selection** — on charts with a continuous axis (time series or numeric), click and drag to select a range. This creates a range filter on all compatible tiles.
* **Multi-select** — after creating a cross-filter on a discrete field, `Cmd + Click` (Mac) or `Ctrl + Click` (Windows) to add more values

### Removing a cross-filter

When a cross-filter is active, a chip appears below the dashboard filters. Click the <Icon icon="xmark" /> on the chip to remove it.

### Seeing which tiles a cross-filter affects

New cross-filters focus automatically. Click a cross-filter chip to focus it, or click it again to clear the focus.

While a cross-filter is focused, tiles it can't filter will have a <Badge icon={<DisabledFilterIcon />} /> badge. Hover over the badge to see why the tile can't be linked - for example, a SQL tile without a templated filter for that field.

### Limitations

* Cross-filters don't apply to null values
* Custom SQL queries don't automatically support cross-filtering unless they use [dynamic filtering](/analyze-explore/sql#custom-sql-filters)
* **Linked tiles** — tiles sourced from a separate workbook tab have their own query and can't receive cross-filters
* **Raw SQL tiles** — SQL-mode tiles can only be cross-filtered if they include a [templated filter](/visualize-present/dynamic-content) (`{{# fieldName }}`) for the relevant field
* Downloads do not apply cross-filter selections

## Faceted filters

Faceted filters automatically link two filters so that one narrows the values of another. For example, a `state` filter limits the `city` filter's options to only cities in the selected state. Faceted filters also work alongside [access filters](/modeling/develop/data-access-control).

### Enabling faceted filters

Faceted filters are off by default. Enable them in the [dashboard's settings](/visualize-present/dashboards/settings).

## Next steps

* [Working with dashboard filters](/visualize-present/dashboards/filters) — create filters, set defaults, and connect them to tiles
* [Filter display options](/visualize-present/dashboards/filter-display-options) — choose how filters are displayed to viewers
* [Dashboard settings](/visualize-present/dashboards/settings) — toggle cross-filtering, faceted filters, and other dashboard behaviors


# Working with dashboard filters
Source: https://docs.omni.co/visualize-present/dashboards/filters

Add filters to Omni dashboards, set defaults, connect them to tiles, and choose how viewers interact with them.

<Tip>
  Want to let dashboard viewers add their own filters? See [Dynamic filter controls](/visualize-present/dashboards/dynamic-filter-controls).
</Tip>

Dashboard filters let viewers narrow data across an entire dashboard without editing it. Each filter is based on a field, and Omni connects it to every tile that uses a matching field. When a viewer changes the filter value, the connected tiles update.

Setting up a filter generally involves three steps:

1. **Add the filter** by picking the field it's based on.
2. **Configure how it behaves** — set a default value, choose how it's displayed, or hide it from viewers.
3. **Map it to tiles** — Omni does this automatically for matching fields, but you can remap or disable per tile.

## Requirements

Creating and modifying filters requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Add a filter

<Steps>
  <Step title="Add the filter">
    1. In a dashboard in edit mode, click **Add > Filter**. The filter panel will open on the right side of the page.
    2. In the filter panel, choose the field you want the filter to be based on. The field you pick determines:

       * Where suggested filter values come from
       * Which field on each dashboard tile Omni initially maps the filter to (you can change this per tile later)
       * The type of field the filter can apply to (string, numeric, date)

       <Tip>
         If dashboard tiles already filter on specific fields, you'll see a **Recommended from queries** section above the field picker. This section lists fields that are filtered in your dashboard's tile queries, making it easy to promote them to dashboard-level filters. Clicking a recommendation automatically selects that field and switches to the relevant topic.
       </Tip>
    3. Click **Add** to create the filter.
  </Step>

  <Step title="Configure filter settings and behavior">
    In the **Settings** tab, add information about the filter and define how it should behave:

    * **Label** - The name of the filter as it displays to dashboard viewers
    * **Description** - What the filter does or how to use it. Viewers see an <Icon icon="info-circle" /> icon next to the filter name; the description displays on hover:
      <img alt="A dashboard filter with the info icon visible and the description showing on hover" />
    * **Filter type** - Defines how the [filter displays on the dashboard](#filter-display-options). Only appears when the source field is a string or date.
    * **Default value** - Defines a default value for the filter, which pre-loads when the dashboard is opened. See [Set a default value](#default-values) for more information.
    * **Apply to new queries** - When enabled, the filter will be automatically applied to new queries added to the dashboard
    * **Require a value for this filter** - When enabled, viewers must set a value before viewing data. By default, only tiles mapped to the filter are blocked. To block the entire dashboard, use the **Block all tiles until set** setting that displays when **Require a value for this filter** is enabled.
    * **Hide this filter when viewing the dashboard** - See [Hiding filters from viewers](#hide-filter)
  </Step>

  <Step title="Map to tiles">
    The **Mapping** tab in the filter editor allows you to manage the filter's connection to query tiles on the dashboard. By default, Omni automatically maps the filter to tiles that use a matching field.

    <img alt="Mapping tab in the filter editor" />

    Use the checkboxes next to the tiles to map or unmap the filter to the specific tile. Selections are saved automatically. See [Map filters to tiles](#mapping) for more information.
  </Step>
</Steps>

## Configure filter behavior

### Set a default value

Filters can have default values, which will pre-load when the dashboard opens. Default values also override any workbook-level filters on the same field.

To set a default value, open the filter editor and use the **Default value** field in the **Settings** tab. What you can select depends on how the **Filter type** is configured:

* If **Filter type** is set to **Advanced**, you can define a condition using the filter dialog:

  <img alt="Filter dialog" />

  <Tip>
    Default values can be user attributes. This is useful when you want a tailored dashboard experience for viewers — for example, a sales dashboard with a default filter set to an Account Executive (AE) name attribute, so each AE sees only their own deals when they open it.
  </Tip>

* If **Filter type** is set to any other option, the default value picker matches that filter type. For example, if a string filter is set to **Single selection**, you can only select a single option from a list of suggestions:

  <img alt="Single select filter field options" />

### Select display options

<Note>
  This feature is not available for classic dashboards.
</Note>

String and date filters can be displayed in several ways, such as a row of button toggles or a timeframe picker. See [Filter display options](/visualize-present/dashboards/filter-display-options) for more information.

### Require filter values before viewing data

To require that viewers set a filter value before they can view data, enable the **Require a value for this filter** setting in the filter's properties panel.

By default, an unset required filter blocks only the tiles it's connected to; other tiles on the dashboard run and render normally. A tile is considered connected to a filter when:

* The filter is directly mapped to a field in the tile
* The tile uses a query reference (such as `XLOOKUP` or a spreadsheet source) that depends on the filter
* The tile inherits the filter through [linked tab](/analyze-explore/workbook-basics#linked-tabs) inheritance

To block the entire dashboard instead of just mapped tiles, enable the **Require a value for this filter > Block all tiles until set** setting.

### Hide a filter from viewers

To hide a filter, enable **Hide this filter when viewing the dashboard** in the filter editor's **Settings** tab. The filter value still applies to connected tiles and the value can still be set via the dashboard's URL, but viewers won't see the filter on the dashboard.

<Note>
  Hiding a filter does not restrict data access. To restrict access to data, use [access filters](/modeling/topics/parameters/access-filters), which enforce data access at the model layer.
</Note>

## Map the filter to tiles

By default, Omni maps the filter to any tile with a matching field. You can change which field it maps to per tile, disable it on specific tiles, or map it to a calculation defined in a tile's query.

<Note>
  Filters don't automatically apply to custom-written SQL queries. See [dynamic filtering in SQL](/analyze-explore/sql#custom-sql-filters) to make a SQL tile respond to dashboard filters.
</Note>

### Map to different fields per tile

You can map a filter to a tile and select a different field for the filter to use. For example, you might want a date filter to update `user_created_at` on one tile and `orders_created_at` on another.

To change the field mapping for a tile:

1. Open the filter editor for the filter.
2. Click the **Mapping** tab.
3. Use the dropdowns next to the tile titles to select a different field:

   <img alt="Filter mapping tab" />

   The available fields will be the same type as the filter source field. For example, if the source field is a date, only date fields can be selected for the tile. For tiles built from a topic, you can only map to fields within that topic.

### Map to a calculation

In addition to view fields, you can map a filter to calculations defined in a tile's query. When editing a filter and selecting the field mapping for a tile, calculations appear in a separate **Calculations** group in the dropdown. This lets you apply a dashboard filter to a custom calculation without defining it as a field in your model:

<img alt="Highlighted Calculations section in filter field picker" />

You can also use [calculations](/analyze-explore/calculations/) as the source for a dashboard filter. See the [Filtering with calculated fields guide](/guides/dashboards/calculated-field-filter) for an example.

### Disable a filter on specific tiles

There are two ways to disable a filter on specific tiles:

* In the filter editor's **Mapping** tab, deselect the tile
* Select the filter on the dashboard, then click the <Icon icon="filter" /> icon in the upper left corner of the tile:

  <img alt="Highlighted filter icon on a tile" />

## Troubleshooting

<AccordionGroup>
  <Accordion title="A filter isn't showing options for a tile when I try to connect it">
    Field types must match — a string filter only maps to string fields, a date filter only to date fields, and so on. Fields with unknown types won't show as matches either.
  </Accordion>

  <Accordion title="A SQL tile isn't responding to a dashboard filter">
    Filters don't automatically apply to custom-written SQL. See [dynamic filtering in SQL](/analyze-explore/sql#custom-sql-filters).
  </Accordion>

  <Accordion title="A hidden tile isn't picking up a new filter">
    New filters don't automatically map to hidden tiles. Un-hide the tile, add the filter, then re-hide it.
  </Accordion>
</AccordionGroup>

## Next steps

* [Filter display options](/visualize-present/dashboards/filter-display-options) — show filters as buttons, dropdowns, single-day pickers, or timeframe controls
* [Filter interactivity](/visualize-present/dashboards/filter-interactivity) — cross-filtering and faceted filters
* [Dashboard settings](/visualize-present/dashboards/settings) — enable cross-filtering and faceted filters at the dashboard level
* [Dynamic filter controls](/visualize-present/dashboards/dynamic-filter-controls) - allow dashboard viewers to add their own filters
* [Adding dashboard filters to workbook queries](/analyze-explore/queries/filters#adding-dashboard-filters-to-workbook-queries) — easily add dashboard filters when editing in workbook using filter suggestions


# Dashboards
Source: https://docs.omni.co/visualize-present/dashboards/index

Present Omni workbook queries as interactive dashboards with filters, charts, and tiles arranged on a unified visual canvas.

A dashboard is the presentation layer for a workbook. You arrange queries, text, filters, and controls onto a shared canvas, group them into layout containers, and optionally split the dashboard across multiple pages. Viewers interact with the result through filters and controls — no editing required.

<Note>
  This page covers dashboards built with the new dashboard editor. Dashboards created before May 27, 2026 may still be on the classic editor — see [Upgrade a classic dashboard](/visualize-present/dashboards/create#classic-dashboards) for the conversion flow.
</Note>

New to dashboards? Start by [creating one](/visualize-present/dashboards/create) or check out the [Dashboard best practices guide](/guides/dashboards/dashboarding-best-practices).

## Layout

How you structure the canvas — containers, pages, and navigation between them.

<Columns>
  <Card title="Layout containers and items" icon="table-cells" href="/visualize-present/dashboards/containers-items">
    Organize charts, text, filters, and controls inside grid or stack containers for precise positioning.
  </Card>

  <Card title="Placeholders" icon="square-dashed" href="/visualize-present/dashboards/placeholders">
    Visualize structure and spacing during the design phase.
  </Card>

  <Card title="Pages" icon="copy" href="/visualize-present/dashboards/pages">
    Build multi-page dashboards where each page has its own layout, items, and filters.
  </Card>

  <Card title="Page navigation" icon="arrow-right-arrow-left" href="/visualize-present/dashboards/page-navigation">
    Customize the inline switcher viewers use to move between pages, including custom tabs and dynamic labels.
  </Card>
</Columns>

## Content items

What you place on the canvas.

<Columns>
  <Card title="Charts" icon="chart-area" href="/visualize-present/dashboards/charts">
    Add workbook query visualizations as chart tiles.
  </Card>

  <Card title="Text and Markdown" icon="a" href="/visualize-present/dashboards/text-markdown">
    Add text, images, tables, and other Markdown content.
  </Card>

  <Card title="Filters" icon="filter" href="/visualize-present/dashboards/filters">
    Let viewers narrow data across the dashboard without editing it.
  </Card>

  <Card title="Controls" icon="wrench" href="/visualize-present/dashboards/controls">
    Let viewers dynamically swap the fields shown in chart tiles.
  </Card>
</Columns>

## Interactivity and polish

Fine-tune how viewers experience the dashboard.

<Columns>
  <Card title="Filter display options" icon="sliders" href="/visualize-present/dashboards/filter-display-options">
    Show filters as button toggles, dropdowns, single-day pickers, or timeframe controls.
  </Card>

  <Card title="Filter interactivity" icon="arrow-pointer" href="/visualize-present/dashboards/filter-interactivity">
    Enable click-to-filter on charts and link filters so one narrows the options of another.
  </Card>

  <Card title="Dynamic filter controls" icon="arrow-right-arrow-left" href="/visualize-present/dashboards/dynamic-filter-controls">
    Allow dashboard viewers to add their own filters.
  </Card>

  <Card title="Themes" icon="palette" href="/visualize-present/dashboards/theming">
    Customize colors, fonts, and other visual styling.
  </Card>
</Columns>

## Test and share

<Columns>
  <Card title="Preview mode" icon="eye" href="/visualize-present/dashboards/preview-mode">
    See what viewers see without leaving edit mode.
  </Card>

  <Card title="View as" icon="user" href="/visualize-present/dashboards/view-as">
    Test user attributes and permissions by viewing the dashboard as another user.
  </Card>
</Columns>


# Migrating dashboards
Source: https://docs.omni.co/visualize-present/dashboards/migrate

Change the connection a dashboard is based on using Omni's APIs.

Instead of creating and building a new dashboard from scratch, you can use Omni's APIs to make the changes programmatically.

## Requirements

To follow the steps in this guide, you'll need:

* **Some familiarity with APIs**. This guide uses the command line to make API requests, which requires some technical know-how.

* **Permissions in Omni that allow you to**:

  * Create an API key (**Settings > API keys**)
  * Access the model IDE

* **An Omni dashboard you want to migrate**.

## Steps

<Steps>
  <Step title="Retrieve the dashboard ID">
    The first step is to retrieve the dashboard's unique ID. You can do this by:

    * **Using the dashboard's URL**. The string after `/dashboards` is the dashboard's ID; for example: `https://blobsrus.omniapp.co/dashboards/1c5e3040`

    * **Opening the document settings**. Navigate to **File > Document settings**. The [**Identifier** field](/share/#changing-document-urls-and-identifiers) contains the dashboard ID:

      <img alt="" />
  </Step>

  <Step title="Export the dashboard">
    Next, you'll export the dashboard you want to migrate. Use the following as a template for your `GET` request:

    ```json wrap title="Template for GET /api/unstable/documents/:dashboardId/export" theme={null}
    curl -L 'https://<YOUR_OMNI_ORG>.omniapp.co/api/unstable/documents/<DASHBOARD_ID>/export' \
    -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
    -H 'Content-Type: application/json'
    ```

    For example, the following request is for the `blobsrus` organization and exports the `1c5e3040` dashboard:

    ```json wrap title="GET /api/unstable/documents/:dashboardId/export" theme={null}
    curl -L 'https://blobsrus.omniapp.co/api/unstable/documents/1c5e3040/export' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json'
    ```

    A successful request will return a JSON object with the following structure:

    ```json wrap title="Successful response" theme={null}
    {
      "dashboard": {...},           // Contains details about the dashboard; truncated for simplicity
      "document": {...},
      "exportVersion": "0.1",
      "workbookModel": {...},
      "fileUploads": [...]          // Spreadsheet file data, if the dashboard contains spreadsheet tiles
    }
    ```

    If the dashboard contains spreadsheet tiles, the response will include a `fileUploads` array with the spreadsheet file data. This data is automatically included in the export and will be restored when you import the dashboard.

    Copy the response into a text editor, as you'll be editing it in the next step.
  </Step>

  <Step title="Retrieve the new model ID">
    The next step is to retrieve the ID for the model that the new dashboard should be built on.

    1. In Omni, navigate to **Settings > Model** and click the model to open it in the IDE.

    2. Locate the string between `/models/` and `/ide` in the URL:

       ```bash wrap theme={null}
       https://blobsrus.omniapp.co/models/d37d0698-4558-41aa-b7f7-66ff85e89e9d/ide
       ```

       In this example, the model ID is `d37d0698-4558-41aa-b7f7-66ff85e89e9d`.

    3. Add following `baseModelId` property to the response body from step 2 of this guide. Replace the value with the ID of the new model:

       ```json theme={null}
       "baseModelId": "<NEW_MODEL_ID>",
       ```

       The updated JSON should have the following structure:

       ```json wrap title="Example model ID" highlight={2} theme={null}
       {
         "baseModelId": "d37d0698-4558-41aa-b7f7-66ff85e89e9d",
         "dashboard": {...},
         "document": {...},
         "exportVersion": "0.1",
         "workbookModel": {...}
       }
       ```
  </Step>

  <Step title="Import the new dashboard">
    The last step is to import the dashboard. Start by using the following template to set up the API request:

    ```json wrap title="Template for POST /api/unstable/documents/import" theme={null}
    curl -L -X POST 'https://<YOUR_OMNI_ORG>.omniapp.co/api/unstable/documents/import' \
    -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
       <UPDATED_JSON_FROM_STEP_3>
    }'
    ```

    Replace `<UPDATED_JSON_FROM_STEP_3>` with the modified JSON from the previous step. Your request should look something like this:

    ```json wrap title="POST /api/unstable/documents/import" theme={null}
    curl -L -X POST 'https://blobsrus.omniapp.co/api/unstable/documents/import' \
    -H 'Authorization: Bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "baseModelId": "d37d0698-4558-41aa-b7f7-66ff85e89e9d",
      "dashboard": {...},
      "document": {...},
      "exportVersion": "0.1",
      "workbookModel": {...},
      "fileUploads": [...]
    }'
    ```

    <Note>
      If the export response includes a `fileUploads` array, include it in your import request to restore any spreadsheet tiles. The spreadsheet file data will be uploaded and linked to the imported dashboard automatically.
    </Note>

    A successful request will return a JSON object similar to the following:

    ```json wrap title="Successful response" theme={null}
    {
      "dashboard": {
         "dashboardId":"31b55e13-abd8-4ba8-b78c-c5afb0e4ed43"
      },
      "miniUuidMap": {
         "nY8mm3PM":"c_afY5V5"
      },
      "workbook": {...}       // Details about the workbook; truncated for simplicity
    }
    ```
  </Step>
</Steps>

## What's next?

At this point, you should be able to access the new dashboard. Further updates may be required, such as updating the corresponding model details to align topics, custom fields, and so on.

To learn more about the content migration APIs, refer to the API references:

* [Export a dashboard API reference](/api/content-migration/export-dashboard)
* [Import a dashboard API reference](/api/content-migration/import-dashboard)


# Building page navigation for multi-page dashboards
Source: https://docs.omni.co/visualize-present/dashboards/page-navigation

Control how viewers move between pages on multi-page dashboards, including custom tabs and dynamic labels.

<Note>
  **Using a classic dashboard?** [Upgrade it](/visualize-present/dashboards/create#classic-dashboards) to use the features in this guide.
</Note>

When you create a multi-page dashboard, Omni automatically adds page navigation to let viewers switch between pages. The page navigation item renders as an inline page switcher that viewers can interact with.

## Common questions

<AccordionGroup>
  <Accordion title="Does Omni automatically add page navigation to dashboards?">
    Yes. Omni adds page navigation automatically in three scenarios:

    * **Adding a second page** - When a dashboard goes from 1 to 2 pages, page navigation is added to both pages.
    * **Adding subsequent pages** - When you add a third or later page, the new page receives navigation matching the appearance of the previous page's navigation.
    * **Duplicating a page** - When you duplicate a page in a multi-page dashboard, page navigation is included in the duplicate.

    You can also [manually add page navigation](#manually-add-navigation) at any time.
  </Accordion>

  <Accordion title="Are new pages automatically added to page navigation?">
    Yes. New pages are automatically appended as tabs to every customized page switcher in the dashboard, so viewers always have access to newly created pages without requiring manual updates.

    * **Default (All-mode) switchers** already show all pages and aren't affected.
    * **Empty switchers** remain empty.
    * **New tabs** are added at the end of each switcher's tab list.

    This behavior maintains consistency across your dashboard and reduces the need to manually synchronize navigation items when your dashboard grows.
  </Accordion>

  <Accordion title="Can a page have multiple navigation items?">
    Yes. While Omni will automatically add navigation in certain scenarios, you can also [manually add additional navigation items](#manually-add-navigation). This is useful if you want to:

    * Add additional page navigation items (for example, at both the top and bottom of a page)
    * Customize the appearance or positioning of the auto-added navigation
    * Add page navigation to a page that doesn't have it
  </Accordion>

  <Accordion title="Can multiple navigation tabs point to the same page?">
    Yes. See [Linking multiple tabs to one page](#multiple-tabs-one-page).
  </Accordion>

  <Accordion title="How many pages can a dashboard have?">
    Dashboards can have up to **15 pages**.
  </Accordion>
</AccordionGroup>

## Requirements

Configuring page navigation in dashboards requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Manually adding page navigation

Omni will [automatically add navigation](#auto-add-nav) in certain scenarios. To manually add page navigation to a page, click **Add > Layout > Page navigation**, then place it in a container where you want the page tabs to appear.

Once added, page switchers offer rich editing capabilities to customize how viewers navigate between pages.

## Adding navigation tabs

Tabs for new pages are added to navigation items automatically, but you can also add tabs manually to include [custom URLs](#custom-url-tabs) or [link multiple tabs to one page](#multiple-tabs-one-page).

<Steps>
  <Step>
    Select the page navigation item on your dashboard. The properties panel should open on the right side of the page.
  </Step>

  <Step>
    In the **Items** section of the panel, click the <Icon icon="plus" /> icon:

    <img alt="Page navigation properties panel with the Items section and plus icon highlighted" />
  </Step>

  <Step>
    Use the menu to select one of the following:

    * **Pages** - Choose an existing page or add a new page. Pages already included in the navigation will be disabled. Adding a new page will automatically add it to the navigation.
    * **Custom** - Add a tab that navigates to an internal path or external URL. See [Custom URL tabs](#custom-url-tabs) for more information.
  </Step>
</Steps>

## Editing navigation tabs

To edit an existing tab:

<Steps>
  <Step>
    Select the page navigation item on your dashboard. The properties panel should open on the right side of the page.
  </Step>

  <Step>
    In the **Items** section of the panel, hover over the tab you want to edit and click the <Icon icon="pencil" /> that displays:

    <img alt="Tab in the Items section showing the edit pencil icon on hover" />
  </Step>

  <Step>
    A popover with configuration options will display. Select an option from the **Link to** dropdown:

    * **Page** - Allows you to select a dashboard page to link to.
    * **Custom** - Allows you to specify a custom URL. See [Custom URL tabs](#custom-url-tabs) for more information.
  </Step>

  <Step>
    In the **Label** field, define the display label for the tab. Toggle the <Icon icon="link" /> icon to connect or disconnect the label from the page's title. See [Labeling navigation tabs](#navigation-labels) for more information.
  </Step>

  <Step>
    When finished, click out of the popover.
  </Step>
</Steps>

## Labeling navigation tabs

Each tab in a page navigation item has a label that viewers see in the switcher. Labels can be connected to the linked page's title — so they track renames automatically — or disconnected to display custom text. Disconnected labels also support [dynamic references](#dynamic-labels) that pull in the current page name.

### Selecting a label mode

When you create or edit a navigation tab, you can use the <Icon icon="chain" /> icon next to the **Label** field to select how the label should behave:

| Label type       | Description                                                                                                                                               | Useful for                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Connected**    | Syncs the label with the connected page's title                                                                                                           | Consistent naming across the dashboard                        |
| **Disconnected** | Allows you to specify a custom label that's independent of the connected page's name. Required to use [dynamic page names](#dynamic-labels) in the label. | Multiple tabs pointing to the same page with different labels |

### Using dynamic page names in labels

<Note>
  This section only applies to [**disconnected labels**](#label-mode).
</Note>

When customizing a [disconnected label](#label-mode), you can use `{{page.<PAGE_KEY>.name}}` to create custom labels that automatically track page renames. This allows you to add custom text to page labels while keeping them synchronized with the actual page names.

```mustache Syntax theme={null}
{{page.<PAGE_KEY>.name}}
```

Replace `<PAGE_KEY>` with the unique key of the page you want to reference. For example, to create a label that displays "Overview — " followed by the page name:

```mustache Example custom label theme={null}
Overview — {{page.dashboard-home.name}}
```

<Tip>
  **Not sure where to find page keys?** See [Advanced page settings][page-settings] for more information.
</Tip>

You can include multiple references in a label if needed. When the dashboard renders, the reference will display the current page name.

Additionally, if you rename a page, the reference will automatically update to reference the new page and keep the label in-sync.

#### Supported properties

Only the `.name` property is supported. If you use other properties like `{{page.KEY.description}}`, the reference will be displayed as literal text rather than being expanded.

## Linking multiple tabs to one page

Page switchers support multiple tabs pointing to the same page, each with its own label. This is useful when you want to provide different entry points or contexts for the same content.

For example, you might have:

* "Overview" and "Summary" tabs both linking to your main dashboard page
* Multiple entry points labeled for different user roles or workflows

To create multiple tabs that link to the same page:

<Steps>
  <Step>
    [Add a tab](#adding-navigation-tabs) to the navigation and select the page you want to link to.
  </Step>

  <Step>
    Add another tab, linking to the same page as the tab in step 1.
  </Step>

  <Step>
    Use **disconnected** labels to give each tab a distinct name.
  </Step>
</Steps>

The tabs can then be renamed as needed, without changes to one tab impacting the other.

## Custom URL tabs

Custom URL tabs let you add navigation to internal dashboard paths or external resources directly from your page switcher.

### Creating a custom URL tab

To add a custom URL tab:

<Steps>
  <Step>
    [Add a tab](#adding-navigation-tabs) to the page navigation, selecting **Custom** as the tab type.
  </Step>

  <Step>
    Hover over the new tab in the **Items** section and click the <Icon icon="pencil" /> icon.
  </Step>

  <Step>
    In the popover that displays, fill in the following:

    * **Link to** - This should be set to **Custom**
    * **Label** - Enter the display text for the tab. Custom URL tabs are automatically created in **disconnected** mode.
    * **URL** - Enter the destination URL. See [URL support](#custom-url-support) for support information for different URL types.
  </Step>

  <Step>
    Click **Advanced** to display the following options:

    * **Target** - Choose how the URL opens:
      * **Same tab** - **Default.** Navigate in the current browser tab.
      * **New tab** - Open in a new browser tab.
      * **Custom** - Specify a custom window name for advanced window management.
    * **Forward params** - **Optional**. Toggle on to append the current URL's query string to the destination URL. This is useful for carrying over filter values or other parameters.

      <Note>
        The **Forward params** option only appends query parameters when the destination URL is same-origin (same domain). This prevents leaking filter or token state to external sites.
      </Note>
  </Step>

  <Step>
    When finished, click out of the popover.
  </Step>
</Steps>

### URL support

| Type                                        | Supported?         | Notes                         |
| ------------------------------------------- | ------------------ | ----------------------------- |
| Relative paths (e.g., `/dashboard/reports`) | <CheckIcon /> Yes  |                               |
| External URLs with `http://` or `https://`  | <CheckIcon /> Yes  |                               |
| Email links with `mailto:`                  | <CheckIcon /> Yes  |                               |
| Anchor links (e.g., `#overview`)            | <CheckIcon /> Yes  |                               |
| `javascript:` URLs                          | <XCircleIcon /> No | Not permitted due to security |
| `data:` URLs                                | <XCircleIcon /> No | Not permitted due to security |

## Reordering tabs

Tabs can be reordered using drag-and-drop to match your preferred navigation flow:

<Steps>
  <Step>
    Select the page navigation item on your dashboard. The properties panel should open on the right side of the page.
  </Step>

  <Step>
    In the **Items** section of the panel, click and hold the tab you want to move:

    <img alt="Tab being dragged to a new position in the Items section" />
  </Step>

  <Step>
    Drag the tab to your preferred position and release.
  </Step>
</Steps>

The new order persists and will be visible to all dashboard viewers.

## Removing tabs

Tabs can be removed from the page switcher without deleting the underlying page:

<Steps>
  <Step>
    Click the page navigation item.
  </Step>

  <Step>
    In the **Items** section of the panel, hover over the tab you want to edit and click the <Icon icon="x" /> that displays.
  </Step>
</Steps>

The page will still be accessible in the catalog and can be re-added to the switcher at any time using the add menu.

## Navigating in edit mode

When editing a dashboard, clicking on page switcher items displays a context menu to help prevent accidental page changes. This behavior varies by appearance type:

* **Tabs, buttons, and list**: Right-click or click to open a context menu with **Go to page** (for dashboard pages) or **Open link** (for custom URLs). Select the option to navigate.
* **Dropdown**: Navigates directly to the page.

In view mode, all page switcher appearances navigate directly when clicked.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why is {{page.KEY.name}} showing as literal text instead of the page name?">
    Page name references are displayed as literal text when:

    * **The property isn't `.name`** - Only `.name` is supported. Properties like `{{page.KEY.description}}` won't be expanded.
    * **The page key doesn't exist** - For example, `{{page.nonexistent-page.name}}` will display as-is. The dashboard won't crash, but the reference won't expand.
    * **The label is in connected mode** - References only work on custom (disconnected) labels. Connected labels automatically use the page name and can't include references.
  </Accordion>

  <Accordion title="Why isn't Forward params adding query parameters to my external URL?">
    The **Forward params** option only appends query parameters when the destination URL is same-origin (same domain). This prevents leaking filter values or token state to external sites. If you need to forward parameters to an external destination, you'll need to construct the URL manually.
  </Accordion>
</AccordionGroup>

## Next steps

* Learn to [build dashboard layouts](/visualize-present/dashboards/containers-items) with containers and items like charts, text, filters, and controls.
* Use [pages](/visualize-present/dashboards/pages) to create multi-page dashboards, where each page has its own layout, items, and filters.
* Configure [filters](/visualize-present/dashboards/filter-display-options) to display filters as button toggles, multi-select dropdowns, single-day pickers, and timeframe controls.

[page-settings]: /visualize-present/dashboards/pages#settings


# Creating multi-page dashboards
Source: https://docs.omni.co/visualize-present/dashboards/pages

Build multi-page dashboards in advanced layout to give viewers a tabbed experience.

<Note>
  **Using a classic dashboard?** [Upgrade it](/visualize-present/dashboards/create#classic-dashboards) to use the features in this guide.
</Note>

A page is a self-contained tab within a dashboard, with its own [layout, items](/visualize-present/dashboards/containers-items), and [filters](/visualize-present/dashboards/filters). Use multiple pages to break a complex dashboard into focused views, separate content for different audiences, or surface drill-downs without forcing viewers to leave the dashboard. Viewers can move between pages using a [page navigation][page-navigation] item.

## Requirements

Creating and modifying dashboard pages requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Adding pages

<Note>
  Dashboards can have up to **15 pages**.
</Note>

Brand new dashboards are created as a single page with an empty layout where you can add containers and items. To add additional pages:

<Steps>
  <Step>
    Click the **Edit** button on the dashboard to enter draft mode.
  </Step>

  <Step>
    Click **Add > Page**.
  </Step>
</Steps>

When you add a second page to a dashboard (going from 1 to 2 pages), Omni automatically adds page navigation to both pages so viewers can navigate between them. See Page navigation][page-navigation] for more information.

If you add additional pages beyond the second, Omni copies the page navigation appearance from the previous page to maintain a consistent experience across your dashboard.

## Duplicating pages

Duplicate existing pages in a dashboard to quickly create new pages with the same layout, containers, and content.

<Steps>
  <Step>
    Click the **Edit** button on the dashboard to enter draft mode.
  </Step>

  <Step>
    Select the page you want to duplicate.
  </Step>

  <Step>
    In the properties panel, click **Duplicate page**.
  </Step>
</Steps>

The new page will appear immediately after the original page in the dashboard navigation. Omni automatically generates a unique name for the duplicated page by appending `Copy` to the original page name. For example, `Dashboard Copy` or `Dashboard Copy 2`.

Going from 1 to 2 pages also adds page navigation; see [Adding pages](#add-page).

## Switching and reordering pages

To switch or reorder pages while editing, use the **page selector** in the toolbar:

* **To switch pages**, click the dropdown to see all pages and select the one you want to work on.
* **To reorder pages**, click the dropdown and then **Re-order**. Drag the pages into the desired order and click **Save**.

## Advanced page settings

To access the settings for a dashboard page:

<Steps>
  <Step>
    Click the **Edit** button on the dashboard to enter draft mode.
  </Step>

  <Step>
    Select the page you want to configure by clicking on it or using the page selector in the toolbar.
  </Step>

  <Step>
    With the page selected, click the <Icon icon="ellipsis-vertical" /> icon in the properties panel.
  </Step>

  <Step>
    Select **Advanced settings** from the menu.
  </Step>
</Steps>

The **Advanced settings** dialog will open, where you can configure the following:

### Page key

A unique identifier for the page. Keys must:

* Be unique across all pages in the dashboard
* Contain only letters, numbers, hyphens, and underscores
* Not exceed 40 characters
* Not be one of Omni's reserved system values: `chat`, `download`, `drill`, `edit`, `layout`, `monitor`, `move`, `performance`, `preview`, `publish`, `run`, `save-as`, `schedules`, `share`, `themes`, `transfer`

If you enter an empty value, invalid format, or a key that's already used by another page, you'll see a validation error and won't be able to save until the issue is resolved.

## Deleting pages

To delete a dashboard page:

<Steps>
  <Step>
    Click the **Edit** button on the dashboard to enter draft mode.
  </Step>

  <Step>
    Select the page you want to delete.
  </Step>

  <Step>
    In the properties panel, click **Delete page**.
  </Step>
</Steps>

Assets from a deleted page can be re-added to existing pages from the <DashboardCatalogIcon /> **Catalog**.

<Warning>
  Text items on a deleted page cannot be recovered from the <DashboardCatalogIcon /> **Catalog**.
</Warning>

## Next steps

* Learn to [build dashboard layouts](/visualize-present/dashboards/containers-items) with containers and items like charts, text, filters, and controls.
* Customize [page navigation](/visualize-present/dashboards/page-navigation) to control how viewers move between pages, including custom tabs and dynamic labels.
* Configure [filters](/visualize-present/dashboards/filter-display-options) to display filters as button toggles, multi-select dropdowns, single-day pickers, and timeframe controls.

[page-navigation]: /visualize-present/dashboards/page-navigation


# Analyzing dashboard performance
Source: https://docs.omni.co/visualize-present/dashboards/performance-profiler

The Performance Profiler helps you analyze how a dashboard executes queries and identify potential performance bottlenecks.

<Note>
  Content **Editor** permissions or higher are required to access a document's Dashboard performance profiler.
</Note>

The performance profiler shows whether tiles are served from cache or the data warehouse, how long queries take, and how much data they return. This view is useful for optimizing dashboard responsiveness and warehouse efficiency.

<img alt="" />

## Accessing the profiler

1. Open the desired dashboard.
2. Click **View > Performance profile**.
3. The profiler opens as a side panel displaying query-level metrics for the latest dashboard run.

## Performance metrics

The profiler summarizes performance for the most recent dashboard run, including caching behavior, query timing, and result sizes.

### Summary metrics

| Metric                           | Description                                                                                                                                           |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Total time in data warehouse** | The total execution time spent querying the data warehouse (excluding cached results).                                                                |
| **Queries cached**               | How many queries were served from cache vs. executed live. “Exact” cache means identical query reuse; “Server requery” indicates a new query was run. |
| **Total result size**            | Combined size of all query results for the dashboard run, in kilobytes (KB).                                                                          |

### Query-level metrics

| Column           | Description                                                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Query Name**   | The name of the dashboard tile or query block.                                                                       |
| **Cache Source** | Indicates if the query was fetched from cache (`Cache (exact)`) or required re-execution (`Cache (server requery)`). |
| **Size (KB)**    | The amount of data returned by the query. Larger results can slow rendering and increase memory usage.               |
| **Time (ms)**    | Time spent running the query in the data warehouse. Cached queries will show `0 ms`.                                 |


# Wireframing with placeholder content
Source: https://docs.omni.co/visualize-present/dashboards/placeholders

Add placeholder items to wireframe your dashboard layout before the actual content exists.

<Note>
  **Using a classic dashboard?** [Upgrade it](/visualize-present/dashboards/create#classic-dashboards) to use the features in this guide.
</Note>

Placeholders let you design and wireframe your dashboard layout before the real content exists, helping you visualize structure and spacing during the design phase.

Placeholders appear in both edit mode and published views, making them useful for sharing work-in-progress dashboards or communicating layout plans to dashboard viewers.

<Frame>
  <img alt="Example of a generic placeholder item with a label and description" />
</Frame>

## Requirements

Modifying dashboard layouts requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Adding placeholders

In the toolbar, click <DashboardAddItemIcon /> **Add >** <DashboardCatalogIcon /> **Layout >** <DashboardPlaceholderIcon /> **Placeholder**. New placeholders are inserted as untyped (**Generic**).

## Configuring placeholder type

Placeholders can be configured to mock specific content types, which will filter the replacement options in the **Insert** menu:

* **Query** — Limits replacement to workbook queries and charts
* **Filter & control** — Limits replacement to filters and controls from your workbook
* **Text** — Offers an option to insert a new text block

The **Generic** option will populate the replacement options with **Query** and **Filter & control** items.

To set a placeholder's type:

* Use the <Icon icon="angle-down" /> option in the placeholder
* Click the placeholder and use the **Settings > Type** option in the properties panel
* Right-click a placeholder and select **Type** from the context menu

## Customizing labels and descriptions

Placeholders display a label and optional description to help communicate their purpose.

* **Labels** - Defaults to `Placeholder <placeholder-type>`, where `<placeholder-type>` is `query`, `filter / control`, or `text`. Use the **Label** field in the properties panel to change the label text.
* **Description** - This optional field allow you to add wireframe instructions or notes. Use the **Description** field in the properties panel to edit the description.

## Replacing with real content

To replace a placeholder with real content, click the **Insert** button in the placeholder tile or the properties panel. The options in the replacement menu are dependent on the placeholder's [current type](#placeholder-type).

For **Text** placeholder types, clicking the **Insert text** button will convert the placeholder into a [Markdown text tile](/visualize-present/dashboards/text-markdown).

## Limitations

Creating brand-new queries, controls, or filters directly from a placeholder is not currently supported. Use the **Select…** button to choose from existing workbook items only. Text is the exception—you can insert a fresh text block.


# Preview mode
Source: https://docs.omni.co/visualize-present/dashboards/preview-mode

Test how your dashboard will behave for viewers without leaving the editor.

<Note>
  **Using a classic dashboard?** [Upgrade it](/visualize-present/dashboards/create#classic-dashboards) to use the features in this guide.
</Note>

Preview mode lets you see how your dashboard will behave for viewers without leaving the editor. When you enter preview mode, editing controls hide and viewer interactions like drilling, cross-filtering, and pagination become active.

## Requirements

Accessing preview mode requires **Editor**, **Manager**, or **Owner** permissions on the document.

## Entering preview mode

To enter preview mode while editing a dashboard:

<Steps>
  <Step>
    Click the **Edit** button on the dashboard to enter draft mode.
  </Step>

  <Step>
    Click the <DashboardPreviewIcon /> icon in the toolbar on the right side of the page.
  </Step>

  <Step>
    Select an option:

    * **Desktop** - Shows how the dashboard will render on desktop screens
    * **Mobile** - Shows how the dashboard will render on small screens
  </Step>
</Steps>

<Tip>
  Click the <Icon icon="up-right-and-down-left-from-center" /> icon in the preview header to enter full screen mode. In full screen mode, click <Icon icon="down-left-and-up-right-to-center" /> or press `Esc` to exit.
</Tip>

## Exiting preview mode

To exit preview mode and return to editing, click the **Exit preview** button in the preview banner at the top of the page.

You'll be returned to the editor with your state intact — selections, unsaved edits, and other editor state are all preserved.

## Preview mode vs. View As user

Unlike preview mode, the [View As user](/visualize-present/dashboards/view-as) feature lets you test how specific users will experience the dashboard based on their [user attributes](/administration/users/attributes) and access permissions.

Use preview mode to test the viewer experience of your dashboard layout and interactions. Use View As user to test how the dashboard adapts to different users' permissions and attributes.

## Next steps

* Learn to [build dashboard layouts](/visualize-present/dashboards/containers-items) with containers and items like charts, text, filters, and controls.
* Customize [page navigation](/visualize-present/dashboards/page-navigation) to control how viewers move between pages.
* Test how your dashboard appears to specific users with [View As user](/visualize-present/dashboards/view-as).


# Managing dashboard settings
Source: https://docs.omni.co/visualize-present/dashboards/settings

Configure dashboard settings such as auto-refresh, crossfiltering, faceted filters, collapsible filters, and fixed control bar.

<Note>
  **Editor**, **Manager**, or **Owner** content permissions are required to access and modify dashboard settings.
</Note>

Dashboard settings allow you to configure behaviors that apply across the entire dashboard, such as automatic data refreshing, filter interactions, and custom state messages.

## Accessing dashboard settings

In a **draft** dashboard, click **Edit > Dashboard settings**. This will open a panel on the right side of the page that contains the various settings for the dashboard.

## Updating settings

You can update one or multiple settings at a time. When finished, click **Update settings** to apply the changes.

## Available settings

### Auto-refresh

When enabled, every dashboard tile will be automatically updated with the latest query results. Auto-refresh is designed for situations where a dashboard needs to stay up-to-date on its own, such as when it’s displayed on an office TV. It automatically reruns your queries at a set interval so the dashboard always shows the latest available results.

Use the **Refresh every** dropdown to select a time interval. The selected interval determines when the dashboard refreshes **from the time it is opened** to when **it’s closed** in the browser.

For example, if set to refresh every 60 minutes and the dashboard is opened at `9:36AM`, the queries will automatically run again at `10:36AM` if the dashboard is kept open.

<Note>
  If you [manually stop running queries](/administration/running-queries#dashboard-queries), auto-refresh will be disabled until you refresh the page.
</Note>

#### Understanding potential performance impacts

Auto-refreshed queries do not return from the cache. To avoid affecting the performance of your database, consider the following when using auto-refresh:

* How often this feature is used, specifically the number of dashboards and frequency of refresh, and
* How performant the dashboard is, including the number of queries and runtime of each query

For example, you have a sales dashboard with 15 charts set to auto-refresh every 5 minutes. If this dashboard displays on a screen in four office locations, this would result in **60 queries** (15 charts × 4 locations) running on your database every five minutes.

Though auto-refresh itself does not use cache, the results from an auto-refresh triggered query can be used as cache for valid queries run manually elsewhere in Omni.

### Facet filters

When enabled, this setting automatically links filters so that one filter will limit the results of another. For instance a `state` filter will reduce the `city` options to only cities that are in that `state`. Faceted filters also work in combination with [access filters](/modeling/develop/data-access-control).

Faceted filters are disabled by default.

### Crossfiltering

When enabled, you can interactively filter an entire dashboard by clicking on chart elements. When you click on a data point, bar, or other chart element, you'll have the option to create a filter that applies across all compatible tiles on the dashboard. See [Cross-filtering](/visualize-present/dashboards/filter-interactivity#cross-filtering) for more information.

### On load, run queries for

<Note>
  This setting is not supported for [classic dashboards](/visualize-present/dashboards/create#classic-dashboards).
</Note>

Controls whether queries run for all pages or only the visible page when the dashboard loads. By default, Omni only runs queries for the currently visible page when a dashboard loads, deferring queries for other pages until you navigate to them.

* **Current page** (default) - Only queries for the visible page run when the dashboard loads. When you navigate to another page, queries for that page run automatically. This improves initial load time for dashboards with multiple pages.

  For example, if you have a dashboard with 5 pages and each page has 3 charts:

  * With **Current page**, only 3 queries run on initial load
  * With **All pages**, all 15 queries run on initial load

  **Note**: Subsequent visits to the same page during the session use cached results, if available.
* **All pages** - All queries across all pages run when the dashboard loads, regardless of which page is visible. This is useful when:
  * You need all data available immediately
  * You need to quickly switch between pages without waiting for queries to run

When deciding which option to use, consider the total number of queries and their runtime.

### Fixed control bar

When enabled, the global control bar (which contains filters and controls) remains fixed at the top of the viewport as you scroll through the dashboard. This keeps your filters and controls accessible at all times without needing to scroll back to the top.

### Collapsible filters

When enabled, filters that don't fit in a single row will be hidden. Otherwise, all filters will be shown.

#### Display all filters initially

**Only available when Collapsible filters is enabled.** When enabled, all filters will initially be displayed even if they don't fit on a single row.

### Custom messages

Allows you to customize the messages displayed on tiles for various states, such as **Error** and **No results**. See [Custom messages](/visualize-present/dashboards/custom-state-message) for more information.

### Timezone override

Controls whether users can use the timezone picker widget to change the query timezone for this dashboard. When enabled, a clock icon appears in the dashboard header and footer controls, allowing viewers to select a different timezone without changing their profile settings.

See [Using the timezone picker](/visualize-present/dashboards/timezone-override) for more information, including how to enable the picker.

## Remove dashboard from document

<Warning>
  Removing the dashboard from a document will also remove any schedules attached to the dashboard.
</Warning>

Along with the connection permissions to access the document, you'll need **Editor** or **Manager** content permissions.

1. In the **Dashboard Settings**, click the **Remove** button.
2. When prompted, click **Remove dashboard** to confirm the removal.
3. Publish the document to apply the changes.

## Related

* [Filters](/visualize-present/dashboards/filters)
* [Design dashboards](/visualize-present/dashboards/create)
* [Custom state messages](/visualize-present/dashboards/custom-state-message)


# Adding text with Markdown tiles
Source: https://docs.omni.co/visualize-present/dashboards/text-markdown

Add styled text, images, and links to your Omni dashboards using Markdown tiles for annotations, headers, and descriptions.

Text tiles put written context on a dashboard: a heading above a group of charts, a note about how a metric is calculated, or a link to related content. You write the content in Markdown, so a tile can include formatting, images, and links. A tile can also show live values from the dashboard's filters and queries.

<Tip>
  Check out the [Markdown cheat sheet](https://www.markdownguide.org/cheat-sheet/) if you need Markdown help.
</Tip>

## Adding text tiles

To add a text tile to a dashboard:

1. Click **Edit** to enter draft mode.
2. In the dashboard toolbar, click <DashboardAddItemIcon /> **Add**.
3. Select <DashboardTextIcon /> **Text**.

## Editing text tile content

While in draft mode, click into a tile's content to open the Markdown editor in the properties panel.

## Creating dynamic content with Mustache

Omni supports [Mustache syntax](https://mustache.github.io/mustache.5.html) in [Markdown visualizations](/visualize-present/visualizations/types/markdown) and Markdown tiles, making it easy to add dynamic content to your dashboards.

For example, the **Breakdown** tiles on the left side of the following image use Mustache to dynamically insert the current value of a filter:

<img alt="" />

Check out the [Dynamic dashboard content guide](/visualize-present/dynamic-content) for more information and examples.


# Applying themes to dashboards
Source: https://docs.omni.co/visualize-present/dashboards/theming

Apply reusable document themes to customize the appearance of Omni dashboards, including fonts, colors, and tile backgrounds.

Omni Admins can create document themes to customize the look and feel of dashboards. Once a theme is created, it can be reused on any dashboard. For internal dashboards it is available under File > Theming and for embedded dashboards it is available as a [URL parameter](/embed/customization/themes#customizing-document-themes).

<img alt="" />

## Creating themes

There are four main areas that can be controlled by themes: background, titles, borders, and elements. Changes are automatically applied when a user interacts with the theme builder, but are only saved by pressing the **Save** button in the bottom right-hand corner of the panel.

## Using CSS in theme components

Omni leverages the power of CSS in themes. For example themable items that use CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) syntax support any valid CSS color value:

| Named colors    | salmon                                        |
| --------------- | --------------------------------------------- |
| Hex codes       | #ff4794                                       |
| Color functions | rgb(255 71 148) or hsl(334.89deg 100% 63.92%) |

Background colors can also accept CSS [\<gradient> values](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient):

| Gradients | linear-gradient (#ff4794, #faaa6f) |
| --------- | ---------------------------------- |

## Importing themes

If you’ve already created a theme for your embedded dashboards you can import the theme by pasting the JSON into the **Import** modal.

<img alt="" />

## Setting and customizing default color palettes for themes

When creating or editing a theme, you can set default color palettes for discrete and continuous data. These settings control the default colors applied to charts in dashboards using the theme.

Both [built-in palettes](/administration/chart-palettes/omni) (such as Basic Blues, Viridis, and Category 10) and [custom palettes](/administration/chart-palettes/custom) created by your organization are available in the palette dropdowns. The selected palettes will be automatically applied to charts in the dashboard based on the data type.

<Note>
  Only palettes that are visible in your organization settings will appear in the theme editor palette selection.
</Note>

## Editing themes

To make changes to the theme, use the <Icon icon="ellipsis-vertical" type="solid" /> (three dots icon) and select **Edit**. Any changes made to the theme will impact other internal dashboards that are using the theme.

## Managing themes

Organization Admins can manage document themes in their organization by navigating to [**Settings > Themes > Document themes**](/administration/themes).

## Appearance settings

Themes are not designed to work with the **Appearance** settings for individuals. For instance if an individual user has selected dark mode, for their appearance settings, some themes might look a little off.

## Themable components

This table highlights the elements currently available (and some sneak peeks for what is going to be available soon). For a visual example, you can toggle between light and dark mode to see how the different elements are impacted by themes and how that lines up with the CSS.

| Category        | Element              | Sub-element         | Default light         | Default Dark          | Accepts                                                                                                        |
| --------------- | -------------------- | ------------------- | --------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
| Page            | Dashboard Background |                     | #FAFAFA               | #262B36               | CSS [background values](https://developer.mozilla.org/en-US/docs/Web/CSS/background)                           |
|                 | Padding              |                     | 16px                  | 16px                  | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) \[Shorthand or individual side] |
| Palettes        | Discrete             |                     |                       |                       | Any built-in or custom palette                                                                                 |
|                 | Continuous           |                     |                       |                       | Any built-in or custom palette                                                                                 |
| Tiles           | Background           |                     | #ffffff               | #161A22               | CSS [background values](https://developer.mozilla.org/en-US/docs/Web/CSS/background)                           |
|                 | Shadow               |                     |                       |                       | CSS [box-shadow values](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow)                           |
|                 | Margin               |                     | 8px                   | 8px                   | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                                 |
|                 | Titles               | Color               | #373D48               | #CCD0D7               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Font Size           | 20px                  | 20px                  | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                                 |
|                 |                      | Font Weight         | 500                   | 500                   | CSS [\<number> value](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                                 |
|                 |                      | Font Family         | system                | system                | URL to remote [woff2 file](/embed/customization/themes#retrieving-woff2-file-links-from-google-fonts)          |
|                 | Text                 | Color               | #373D48               | #CCD0D7               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Secondary Color     | #676F7E               | #B7BDC8               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Body Font Family    | system                | system                | URL to remote [woff2 file](/embed/customization/themes#retrieving-woff2-file-links-from-google-fonts)          |
|                 |                      | Code Font Family    | JetBrains Mono        | JetBrains Mono        | URL to remote [woff2 file](/embed/customization/themes#retrieving-woff2-file-links-from-google-fonts)          |
|                 | Borders              | Color               | #EAECF1               | #2d343e               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Radius              | 5px                   | 5px                   | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) \[Shorthand or individual side] |
|                 |                      | Style               | Solid                 | Solid                 | CSS [\<line-style> value](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style#line-style)            |
|                 |                      | Width               | 1px                   | 1px                   | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                                 |
| Controls        | Background           |                     | #ffffff               | #161A22               | CSS [background values](https://developer.mozilla.org/en-US/docs/Web/CSS/background)                           |
|                 | Border color         |                     | #D1D7E0               | #424857               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Text color           |                     | #070808               | #EBEDEF               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Placeholder color    |                     | #6F7780               | #8F96A3               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Label color          |                     | #070808               | #EBEDEF               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Radius               |                     | 5px                   | 5px                   | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) \[Shorthand or individual side] |
|                 | Focus outline color  |                     | #3F78E9               | #3F78E9               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
| Control popover | Background           |                     | #ffffff               | #22252A               | CSS [background values](https://developer.mozilla.org/en-US/docs/Web/CSS/background)                           |
|                 | Text color           |                     | #070808               | #EBEDEF               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Secondary text color |                     | #6F7780               | #8F96A3               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Link color           |                     | #006CBA               | #64A4DF               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Border color         |                     | #D1D7E0               | #424857               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Radius               |                     | 5px                   | 5px                   | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) \[Shorthand or individual side] |
|                 | Divider color        |                     | #E0E4EB               | #343B46               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Inputs               | Background          | #FFFFFF               | #161A22               | CSS [background values](https://developer.mozilla.org/en-US/docs/Web/CSS/background)                           |
|                 |                      | Border color        | #D1D7E0               | #424857               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Text color          | #070808               | #EBEDEF               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Placeholder color   | #6F7780               | #8F96A3               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Icon color          | #676F7E               | #B7BDC8               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Radius              | 5px                   | 5px                   | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) \[Shorthand or individual side] |
|                 |                      | Focus outline color | #3F78E9               | #3F78E9               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Accent color        | #3F78E9               | #3F78E9               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Accent invert color | #FFFFFF               | #080808               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Tokens               | Background          | #F0F6FF               | #1A2432               | CSS [background values](https://developer.mozilla.org/en-US/docs/Web/CSS/background)                           |
|                 |                      | Text color          | #070808               | #EBEDEF               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
| Buttons         | Radius               |                     | 10rem                 | 10rem                 | CSS [\<length> value](https://developer.mozilla.org/en-US/docs/Web/CSS/length) \[Shorthand or individual side] |
|                 | Primary button       | Background          | #FF4794               | #F787AD               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Text color          | #FFFFFF               | #080808               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Transparent button   | Text color          | #373D48               | #CCD0D7               | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 |                      | Hover background    | rgba(115,123,140,.08) | rgba(115,123,140,.24) | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |
|                 | Menu item            | Hover background    | rgba(115,123,140,.08) | rgba(115,123,140,.24) | CSS [\<color> value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)                             |

The table also matches the order of the **Theming** panel. It will automatically refresh as you make changes, but don't forget to press **Save** to apply the settings.

<img alt="" />

Once a theme is saved, it will appear in the **Theming** panel. Use the <Icon icon="ellipsis-vertical" type="solid" /> (three dots icon) to apply the theme to individual dashboards.

<img alt="" />

There is not a global theme setting for internal dashboards.


# Enabling timezone selection on documents
Source: https://docs.omni.co/visualize-present/dashboards/timezone-override

Override the query timezone for a document using the timezone picker, allowing viewers to change how time-based data is displayed.

The timezone picker overrides the query timezone for a single document without changing your profile settings. When enabled, a timezone menu appears in the document header and dashboard footer so you and your viewers can switch the timezone used for all queries in the document. You can also apply timezone overrides to deliveries and downloads.

## Enabling the timezone picker

To use the timezone picker, enable all the following settings:

<Steps>
  <Step title="Enable the User-specific Timezones connection setting">
    An Organization Admin or Connection Admin must enable the underlying connection's **User-specific Timezones** setting. See [Timezone conversion](/connect-data/timezones) for more information.
  </Step>

  <Step title="Enable the Timezone override organization setting">
    An Organization Admin must enable the **Timezone override** default document ability in **Settings > Content permissions**. See [Content permissions](/administration/content-permissions) for more information.
  </Step>

  <Step title="Enable the Timezone override document setting">
    A user with Editor, Manager, or Owner permissions on the document must enable the document's **Timezone override** setting. See [Dashboard settings](/visualize-present/dashboards/settings) for more information.
  </Step>
</Steps>

<Note>
  Embed users will have access to the timezone picker when all of the above settings are enabled.
</Note>

## Using the timezone picker

When all three settings are enabled, the timezone picker displays in the document's header and the footer of the dashboard:

<Frame>
  <img alt="Timezone picker highlighted on a dashboard" />
</Frame>

Use the picker to select one of the following:

* **Viewer's timezone** - Each viewer's profile timezone
* **UTC** - Coordinated Universal Time
* **A specific timezone** - For example, `America/Denver`

Your selection persists when navigating between the dashboard and workbook in the document, ensuring a consistent timezone experience as you move between viewing and editing your analysis.

<Tip>
  You can also override timezones in [deliveries](/share/deliveries), [dashboard downloads](/visualize-present/dashboards/download), and [query result downloads](/analyze-explore/point-click-queries#downloading-results).
</Tip>

## Next steps

* Learn more about [timezone conversion](/connect-data/timezones) in Omni
* Configure interactivity for your documents in [dashboard settings](/visualize-present/dashboards/settings)
* Set organization-level [content permissions](/administration/content-permissions)


# Viewing dashboards as another user
Source: https://docs.omni.co/visualize-present/dashboards/view-as

Preview dashboards and workbooks as another user to verify user attribute-based access grants and filters.

<Note>
  **Organization Admin** permissions are required to view dashboards as another user.
</Note>

While you're working, you may want to preview how your dashboard will behave for specific users. This can help you proactively address permission issues before sharing the content.

The **View as** feature temporarily applies the selected user's user attribute values to your current session for the purpose of evaluating filters, row-level security, and other attribute-driven logic.

## View As basics

<AccordionGroup>
  <Accordion title="What does View As include?">
    View As applies the selected user's:

    * **User attributes** - Variables mapped to dashboards, filters, and data access controls resolve using the selected user's attribute values. **Note**: Because only attributes are swapped, you may still see content or fields that the actual user cannot access.
    * **Access grants** - Data access rules based on user attributes apply from the selected user's perspective.

    This makes this tool useful for quickly testing that user attribute-based filters and access grants work as expected.
  </Accordion>

  <Accordion title="What does View As exclude?">
    View As is a preview mode focused on user attributes. It does not log you in as the selected user and does not change the user's permissions, roles, or connection access.

    It does not allow you to simulate:

    * **Downloads** - These actions aren't available while viewing as another user.
    * **Scheduled delivery previews** - Scheduled deliveries run as their owner, not as the selected user.
    * **Role-based restrictions** - Connection access based on user roles (like Restricted Querier permissions) is not reflected in View As.
  </Accordion>
</AccordionGroup>

## Viewing content as another user

In a dashboard or workbook, click **File > View as** and select a user.

## When to use Impersonate

For comprehensive testing that includes role-based restrictions, connection access, and all permissions, use [**Impersonate user**](/administration/users/impersonate) instead. Impersonation provides a full-session simulation where you experience Omni exactly as that user would, including all role-based restrictions and connection access controls.

Use **View As** for quick user attribute testing, and use **Impersonate** for comprehensive session simulation.


# Creating dynamic dashboard content with Mustache
Source: https://docs.omni.co/visualize-present/dynamic-content

Omni supports Mustache syntax in Markdown visualizations and dashboard Markdown tiles, making it easy to add dynamic content to your dashboards.

Mustache enables you to craft tailored dashboards by:

* Personalizing content for viewers by using their name, role, or other details
* Dynamically styling Markdown visualizations [with CSS rules](https://community.omni.co/t/tips-for-dynamic-styling-in-markdown-visualizations/170)

## Supported content

Mustache can be used in the following places:

<AccordionGroup>
  <Accordion title="Markdown visualizations" icon="chart-pie">
    In this example, Mustache tags are used to reference specific values in the query's result set. **Note**: Line breaks have been added for readability:

    ```handlebars wrap theme={null}
    There have been **{{result._totals._first.order_items.order_count.value}}**
    orders placed for **{{result._first.products.brand.value}}** in 
    **{{result._first.users.state.value}}**, and the average selling price is
    **{{result._first.order_items.sale_price_average.value}}**.

    See the 🗺📍 below for **{{result._first.products.brand.value}}** stores
    in the top selling city - **{{result._first.users.city.value}}, 
    {{result._first.users.state.value}}**. 
    ```

    <img alt="" />
  </Accordion>

  <Accordion title="Dashboard text / Markdown tiles" icon="font">
    This example demonstrates how to create a dynamic Iframe with Mustache.

    Mustache tags are used to create a Google Maps search with a dynamic URL:

    ```handlebars wrap theme={null}
    <iframe src="https://www.google.com/maps/embed/v1/search?q={{result.0.products.brand.value_static}}+in+{{result._first.users.city.value_static}},{{result._first.users.state.value_static}}&key=AIzaSyCXfF4zpXaYkgVaBzj3oZUtmcDAxpdoOGk&" width="100%" height="100%" style="border:0;" allowfullscreen="" loading="lazy" referrerpolicy="no-referrer-when-downgrade"></iframe>
    ```

    <img alt="" />
  </Accordion>

  <Accordion title="Visualization axis labels" icon="chart-bar">
    In this example, Mustache tags create a dynamic y-axis label that displays summary values and filter details.

    ```handlebars wrap theme={null}
    Order Count ({{result._totals.0.order_items.order_count.value}} Total Orders in {{result.0.users.state.value}})
    ```

    <img alt="" />
  </Accordion>
</AccordionGroup>

## Available tags

Refer to the [Mustache reference](/visualize-present/mustache-reference) for a complete list of the tags Omni currently supports.

## Escaping

All tags are escaped by default. This means that text enclosed in `{{}}` will always render, even if you intend to just display the curly braces themselves.

To return raw contents without escaping, add an extra curly brace:

```handlebars theme={null}
{{{ variable }}}
```

To escape the curly braces and have them render, use backslashes:

```handlebars theme={null}
\{\{variable\}\}
```

For more specifics on syntax and gotchas, refer to the [Mustache docs](https://mustache.github.io/mustache.5.html).


# Visualize & present
Source: https://docs.omni.co/visualize-present/index

Turn query results into charts, build interactive dashboards, and use AI to surface insights from your data.

Once you've [queried your data](/analyze-explore/querying), Omni provides tools to visualize results, assemble dashboards, and present insights to your team. This section covers everything from chart configuration to dashboard design and management.

## Chat with Content

[Chat with Content](/ai/dashboard-assistant) brings conversational AI directly into your content. Ask follow-up questions, drill into subsets, summarize results, or request new analyses — all without leaving the page.

## Visualize data

Omni includes a library of [built-in chart types](/visualize-present/visualizations/types) — bar, line, area, scatter, funnel, KPI, map, and more. Each chart supports [configuration options](/visualize-present/visualizations/configuration/color) for color, axes, series mapping, tooltips, and sizing. For advanced use cases, you can edit the underlying [Vega-Lite spec](/visualize-present/visualizations/types/custom) directly.

You can also use AI to [generate visualizations](/ai/visualizations) from your query results.

## Design dashboards

[Dashboards](/visualize-present/dashboards) are the presentation layer for your workbooks, displaying multiple queries as an interactive collection of tiles. Dashboards support:

* **[Chart and table tiles](/visualize-present/dashboards/charts)** — Display query results as visualizations or tables
* **[Text and Markdown tiles](/visualize-present/dashboards/text-markdown)** — Add context, headers, and documentation
* **[Filters](/visualize-present/dashboards/filters)** and **[controls](/visualize-present/dashboards/controls)** — Let viewers interact with the data
* **[Dynamic content](/visualize-present/dynamic-content)** — Use Mustache syntax to personalize dashboards for each viewer
* **[Theming](/visualize-present/dashboards/theming)** — Apply custom themes to match your organization's branding

## Manage dashboards

Once your dashboard is built, Omni provides tools to keep it running well:

* **[Dashboard settings](/visualize-present/dashboards/settings)** — Configure refresh behavior, default filters, and document-level options
* **[Performance profiler](/visualize-present/dashboards/performance-profiler)** — Identify slow queries and optimize load times
* **[Download](/visualize-present/dashboards/download)** and **[migrate](/visualize-present/dashboards/migrate)** dashboards as needed

## Apps <Badge>BETA</Badge>

When a dashboard's grid of tiles isn't expressive enough, [apps](/visualize-present/apps) let you build a fully custom, interactive interface — a calculator, a leaderboard, a guided tool — backed by live, governed queries from your workbook. Describe what you want to the [Omni Agent](/ai/chat) and it builds the app for you. The data stays inspectable and tunable in the workbook, just like every other surface in Omni.


# Mustache cheatsheet
Source: https://docs.omni.co/visualize-present/mustache-cheatsheet

Quick reference for Omni's supported Mustache tags

For detailed information, refer to the [Mustache syntax reference](/visualize-present/mustache-reference).

<CardGroup>
  <Card title="Query metadata">
    Returns [query metadata](/visualize-present/mustache-reference#query-metadata). Supported only in dashboard Markdown tiles.

    | Returns           | Syntax                             |
    | ----------------- | ---------------------------------- |
    | Query name        | `{{queries.query_id.name}}`        |
    | Query subtitle    | `{{queries.query_id.subtitle}}`    |
    | Query description | `{{queries.query_id.description}}` |
    | Query topic name  | `{{queries.query_id.topicName}}`   |
    | Query created at  | `{{queries.query_id.createdAt}}`   |
    | Query updated at  | `{{queries.query_id.updatedAt}}`   |
  </Card>

  <Card title="Query fields">
    Returns metadata about a [query field](/visualize-present/mustache-reference#query-fields). Supported in Markdown visualizations.

    | Returns           | Syntax                                        |
    | ----------------- | --------------------------------------------- |
    | View name         | `{{fields.view_name.field_name.view_label}}`  |
    | Field name        | `{{fields.view_name.field_name.label}}`       |
    | Field description | `{{fields.view_name.field_name.description}}` |
  </Card>

  <Card title="Query results">
    Returns a value from [query results](/visualize-present/mustache-reference#query-results). Supported in Markdown visualizations.

    | Returns                                                                         | Syntax                                                               |
    | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
    | First row                                                                       | `{{result._first.view_name.field_name.value_type}}`                  |
    | Last row                                                                        | `{{result._last.view_name.field_name.value_type}}`                   |
    | Specific row                                                                    | `{{result.row_number.view_name.field_name.value_type}}`              |
    | Column total                                                                    | `{{result._total.first.view_name.field_name.value_type}}`            |
    | Row total                                                                       | `{{result.row_number.row_total.view_name.field_name.value_type}}`    |
    | Grand total                                                                     | `{{result.totals._first.row_total.view_name.field_name.value_type}}` |
    | [Pivot column iteration](/visualize-present/mustache-reference#pivot-iteration) | `{{#result._pivots}}...{{/result._pivots}}`                          |
    | [Pivot row iteration](/visualize-present/mustache-reference#pivot-iteration)    | `{{#row._pivots}}...{{/row._pivots}}`                                |

    **Value types:** `value` (interactive), `value_static` (formatted), `raw` (plain)
  </Card>

  <Card title="Filters">
    Returns metadata about [filters](/visualize-present/mustache-reference#filters). Supported in Markdown tiles.

    **Dashboard filters** use the filter ID:

    | Returns           | Syntax                                    |
    | ----------------- | ----------------------------------------- |
    | Label             | `{{filters.filter_id.label}}`             |
    | Summary           | `{{filters.filter_id.summary}}`           |
    | Value             | `{{filters.filter_id.value}}`             |
    | URL-encoded value | `{{filters.filter_id.value_url_encoded}}` |
    | JSON              | `{{filters.filter_id.json}}`              |

    **Workbook filters** use the view and field name:

    | Returns           | Syntax                                               |
    | ----------------- | ---------------------------------------------------- |
    | Label             | `{{filters.view_name.field_name.label}}`             |
    | Summary           | `{{filters.view_name.field_name.summary}}`           |
    | Value             | `{{filters.view_name.field_name.value}}`             |
    | URL-encoded value | `{{filters.view_name.field_name.value_url_encoded}}` |
    | JSON              | `{{filters.view_name.field_name.json}}`              |
  </Card>

  <Card title="Controls">
    Returns metadata about [dashboard controls](/visualize-present/mustache-reference#controls). Supported in Markdown tiles.

    | Returns           | Syntax                                      |
    | ----------------- | ------------------------------------------- |
    | Label             | `{{controls.control_id.label}}`             |
    | Summary           | `{{controls.control_id.summary}}`           |
    | Value             | `{{controls.control_id.value}}`             |
    | URL-encoded value | `{{controls.control_id.value_url_encoded}}` |
    | JSON              | `{{controls.control_id.json}}`              |
  </Card>

  <Card title="Dashboard metadata">
    Returns [dashboard metadata](/visualize-present/mustache-reference#dashboard-metadata). Supported in Markdown tiles.

    | Returns         | Syntax                       |
    | --------------- | ---------------------------- |
    | Created at      | `{{metadata.createdAt}}`     |
    | Created by      | `{{metadata.createdBy}}`     |
    | Last updated at | `{{metadata.lastUpdatedAt}}` |
  </Card>

  <Card title="User attributes">
    Returns [user attribute data](/visualize-present/mustache-reference#user-attribute-metadata). Supported in Markdown tiles.

    | Returns          | Syntax                                                    |
    | ---------------- | --------------------------------------------------------- |
    | User email       | `{{metadata.userAttributes.omni_user_email.element}}`     |
    | User name        | `{{metadata.userAttributes.omni_user_name.element}}`      |
    | User ID          | `{{metadata.userAttributes.omni_user_id.element}}`        |
    | Is org admin?    | `{{metadata.userAttributes.omni_is_org_admin.element}}`   |
    | User groups      | `{{metadata.userAttributes.omni_user_groups.element}}`    |
    | Custom attribute | `{{metadata.userAttributes.attribute_reference.element}}` |

    **Elements:** `label` (display name), `values` (attribute value)
  </Card>

  <Card title="Inspection">
    Returns [query and user attribute metadata](/visualize-present/mustache-reference#query-and-user-attribute-inspection) as JSON. Supported in Markdown visualizations.

    ```handlebars theme={null}
    {{inspect}}
    ```
  </Card>
</CardGroup>


# Mustache syntax reference
Source: https://docs.omni.co/visualize-present/mustache-reference

Complete reference for Mustache template syntax in Omni, including tags, keys, sections, and dynamic content for dashboards.

In Mustache, a **tag** is indicated by double mustaches, for example `{{results}}`. A tag is made up of one or more **keys**, which are used to find the requested data. In the previous example, `results` is the key in `{{results}}`.

<Tip>
  Check out the [Cheatsheet](/visualize-present/mustache-cheatsheet) for a high-level summary of all Omni's currently-supported tags.
</Tip>

## Locating keys

Several Omni tags require specific keys, such as a `view_name` or a `field_name`. Refer to the following sections for help finding this information in Omni.

### view\_name and field\_name

The `view_name` and `field_name` keys are used in [Query field](#query-fields) and [Query result](#query-results) tags.

To locate the name of a view or field in a query:

1. Enter **draft** mode in a workbook.
2. In the tab of the query, open the **Results** panel.
3. In the **Fields** section, locate a field and click the <Icon icon="caret-down" /> (caret) icon.

Below the **Label** field will be the name of the view and the field. In the example image (click to enlarge), this is `main__customers.id`. `main__customers` is the `view_name`, and `id` is the `field_name`.

<Frame>
  <img alt="Using the query results panel to locate the names of a view and field" />
</Frame>

### control\_id and filter\_id

The `control_id` and `filter_id` keys are used in [Control](#controls) and [Filter](#filters) tags for dashboards.

To locate the ID of a dashboard control or filter:

1. Enter **draft** mode in a dashboard.
2. Locate the control or filter at the top of the dashboard and click the <Icon icon="pencil" /> (pencil) icon to open the **Edit** panel.
3. Locate the **ID** field at the bottom of the panel. In the example image, the ID is `8v_G12D7`.

<img alt="Highlighted ID value in the Edit control panel" />

<Tip>
  Control and filter IDs are configurable. To change an ID, edit the **ID** field in the control or filter's **Edit** panel. You'll have to update existing references - Omni won't automatically do this when you change the ID.
</Tip>

## Query metadata

<Note>
  Query metadata tags are only supported in [dashboard Markdown tiles](/visualize-present/dashboards/text-markdown). Use the **Variables** menu (<MarkdownVariablesIcon /> icon) in the Markdown editor to quickly insert fully-formed variables.
</Note>

Returns metadata about a query.

```handlebars title="Syntax" theme={null}
{{queries.query_id.element}}
```

Requires the following keys:

<ParamField>
  Accesses query metadata
</ParamField>

<ParamField>
  The ID of the query. This will be an integer, such as `4`.
</ParamField>

<ParamField>
  The data you want to retrieve, such as the name of the query. Refer to the following sections for information on what is currently supported.
</ParamField>

### Query name

Returns the name of the query.

```handlebars title="Syntax" theme={null}
{{queries.query_id.name}}
```

```handlebars title="Example" theme={null}
{{queries.4.name}}
```

### Query subtitle

Returns the subtitle of the query.

```handlebars title="Syntax" theme={null}
{{queries.query_id.subtitle}}
```

```handlebars title="Example" theme={null}
{{queries.4.subtitle}}
```

### Query description

Returns the description of the query.

```handlebars title="Syntax" theme={null}
{{queries.query_id.description}}
```

```handlebars title="Example" theme={null}
{{queries.4.description}}
```

### Query topic name

Returns the name of the topic used in the query.

```handlebars title="Syntax" theme={null}
{{queries.query_id.topicName}}
```

```handlebars title="Example" theme={null}
{{queries.4.topicName}}
```

### Query created date

Returns the date the query was created.

```handlebars title="Syntax" theme={null}
{{queries.query_id.createdAt}}
```

```handlebars title="Example" theme={null}
{{queries.4.createdAt}}
```

### Query updated date

Returns the date the query was last updated.

```handlebars title="Syntax" theme={null}
{{queries.query_id.updatedAt}}
```

```handlebars title="Example" theme={null}
{{queries.4.updatedAt}}
```

## Query fields

<Note>
  Query field tags are only supported in visualizations, meaning they can't be used in [Markdown dashboard tiles](/visualize-present/dashboards/text-markdown).
</Note>

Returns metadata about a specific query field.

```handlebars title="Syntax" theme={null}
{{fields.view_name.field_name.element}}
```

Requires the following keys:

<ParamField>
  Accesses query field data
</ParamField>

<ParamField>
  The name of the view that contains the field
</ParamField>

<ParamField>
  The name of the field
</ParamField>

<ParamField>
  The data you want to retrieve, such as the display name of the field. Refer to the following sections for information on what is currently supported.
</ParamField>

### View name

Returns the display name of the view that contains the specified field.

```handlebars title="Syntax" theme={null}
{{fields.view_name.field_name.view_label}}
```

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{fields.customers.id.view_label}}
      ```
    </div>

    <Frame>
      <img alt="Example view name" />
    </Frame>
  </Columns>
</Card>

### Field name

Returns the display name of the field.

```handlebars title="Syntax" theme={null}
{{fields.view_name.field_name.label}}
```

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{fields.customers.id.label}}
      ```
    </div>

    <Frame>
      <img alt="Example field name" />
    </Frame>
  </Columns>
</Card>

### Field description

Returns the [description](/modeling/dimensions/parameters/description) of the field as defined in the model.

```handlebars title="Syntax" theme={null}
{{fields.view_name.field_name.description}}
```

```handlebars title="Example" theme={null}
{{fields.customers.lifetime_value.description}}
```

## Query results

<Note>
  Query result tags are only supported in visualizations, meaning they can't be used in [Markdown dashboard tiles](/visualize-present/dashboards/text-markdown).
</Note>

Returns a result value from a query. The syntax varies depending on the data point you want to retrieve, but typically looks like the following:

```handlebars title="Syntax" theme={null}
{{result.data_point.view_name.field_name.value_type}}
```

The following keys must always be provided, regardless of the data point being retrieved:

<ParamField>
  Accesses query result data
</ParamField>

<ParamField>
  The type of data point you want to retrieve, such as the value of a field in the first row of query results (`_first`). Refer to the following sections for information on what's currently supported.
</ParamField>

<ParamField>
  The name of the view that contains the field
</ParamField>

<ParamField>
  The name of the field. Refer to the [Locating keys section](#view_name-and-field_name) for help finding this and the `view_name`.
</ParamField>

<ParamField>
  Determines the level of interactivity and formatting of the returned value:

  * `value` - Interactive; user can click to copy, drill, etc.
  * `value_static` - Formatting applied, no interactivity
  * `raw` - No formatting or interactivity
</ParamField>

### First row value

Returns the first value in the result set for the specified field.

```handlebars title="Syntax" theme={null}
{{result._first.view_name.field_name.value_type}}
```

This example uses `value_static`, which returns a formatted value with no interactivity:

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{result._first.customers.first_name.value_static}}
      ```
    </div>

    <Frame>
      <img alt="Example first row value" />
    </Frame>
  </Columns>
</Card>

### Last row value

Returns the last value in the result set for the specified field.

```handlebars title="Syntax" theme={null}
{{result._last.view_name.field_name.value_type}}
```

This example uses `value`, which allows dashboard users to click and interact with the value. Note the dropdown menu over the value in the example image.

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{result._last.customers.first_name.value}}
      ```
    </div>

    <Frame>
      <img alt="Example last row value" />
    </Frame>
  </Columns>
</Card>

### Specific row value

Returns a field value from the specified row (`row_number`) in the result set.

In Omni, row numbering begins at 0. When you define the variable, subtract **one** from the number of the actual row you want to reference.

```handlebars title="Syntax" theme={null}
{{result.row_number.view_name.field_name.value_type}}
```

For example, to return a value from row `11`, use `10` as the `row_number`:

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{result.10.customers.first_name.raw}}
      ```
    </div>

    <Frame>
      <img alt="Example specific row value" />
    </Frame>
  </Columns>
</Card>

### Column total

Returns the total of a specified column in the result set. Requires [**Column totals**](/analyze-explore/point-click-queries#column-totals) to be enabled in the query's **Results options** panel.

```handlebars title="Syntax" theme={null}
{{result._total.first.view_name.field_name.value_type}}
```

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{result._total.first.customers.total_price_sum.value}}
      ```
    </div>

    <Frame>
      <img alt="Example column total" />
    </Frame>
  </Columns>
</Card>

### Row total

Returns the total of a specified row (`row_number`) in a **pivoted** result set. Requires a query with at least one pivot and for [**Row totals**](/analyze-explore/point-click-queries#row-totals) to be enabled in the query's **Results options** panel.

In Omni, row numbering begins at 0. When you define the variable, subtract **one** from the number of the actual row you want to reference.

```handlebars title="Syntax" theme={null}
{{result.row_number.row_total.view_name.field_name.value_type}}
```

For example, to return values from row `6`, use `5` as the `row_number`:

```handlebars title="Example" theme={null}
{{result.5.row_total.order_items.sale_price_sum.value}}
```

### Grand total

Returns the grand total of a specified column in a **pivoted** result set. Requires a query with at least one pivot and for [**Column totals**](/analyze-explore/point-click-queries#column-totals) to be enabled in the query's **Results options** panel.

```handlebars title="Syntax" theme={null}
{{result.totals._first.row_total.view_name.field_name.value_type}}
```

```handlebars title="Example" theme={null}
{{result.totals._first.row_total.customers.total_price_sum.value}}
```

### Pivot iteration

Iterates over pivot columns in a pivoted result set without hardcoding pivot values. This allows templates to work dynamically when filters change which pivot values exist. Only applies to queries with at least one [pivot](/analyze-explore/queries/pivots).

Two iteration modes are available:

* **Column-major** (`result._pivots`) - Iterate all pivot columns, with each entry containing all row data for that column
* **Row-major** (`row._pivots`) - Iterate pivot entries within each row (used inside a `{{#result}}` loop)

Both modes exclude row-total and subtotal columns, as well as the synthetic "Previous Period" alias used in period-over-period comparisons.

```handlebars title="Syntax (column-major)" theme={null}
{{#result._pivots}}...{{/result._pivots}}
```

```handlebars title="Syntax (row-major)" theme={null}
{{#result}}
  {{#row._pivots}}...{{/row._pivots}}
{{/result}}
```

Each pivot entry exposes the following keys:

<ParamField>
  The pivot value as a single string, for example `Idaho` or `Female - UK` for multi-level pivots
</ParamField>

<ParamField>
  The pivot value(s) as an array. For single-level pivots, this is a one-element array. For multi-level pivots, this contains each level separately, for example `["Female", "UK"]`
</ParamField>

<ParamField>
  The row data for this pivot column. Each row's cells for this column are merged with that row's non-pivoted fields. Pivot dimension values are exposed as regular field entries (e.g., `users.state.value`)
</ParamField>

Like other result entries, pivot entries are decorated with the standard `_first`, `_second`, `_last`, and `_rows` accessors used elsewhere in Mustache templates.

<Note>
  The keys are prefixed with underscores (`_value`, `_values`) to prevent collisions with actual field names from your data model.
</Note>

The following column-major example uses a query pivoted on `users.state` and grouped by `users.age`. For each pivot column, the template:

1. Renders the pivot value (`{{_value}}`) as a heading, for example `Idaho`
2. Loops through that column's rows (`{{#rows}}`) and renders each row as an `age: count` pair

```handlebars title="Example: create a section for each pivot column" theme={null}
{{#result._pivots}}
### {{_value}}
{{#rows}}{{users.age.value}}: {{users.count.value}}
{{/rows}}
{{/result._pivots}}
```

Because the template never references a specific pivot value, it renders one section per pivot column no matter which states the query returns.

## Query and user attribute inspection

<Note>
  Query & user attribute inspection is only supported in Markdown visualizations.
</Note>

Returns the elements of a query and user attribute metadata in JSON format.

```handlebars title="Syntax" theme={null}
{{inspect}}
```

<img alt="" />

<img alt="" />

## Filters

Returns metadata about [dashboard](/visualize-present/dashboards/filters) and workbook filters.

The syntax differs depending on where the filter is located:

* **Dashboard filters** use the filter's ID: `{{filters.filter_id.element}}`
* **Workbook filters** use the view and field name: `{{filters.view_name.field_name.element}}`

<Tabs>
  <Tab title="Dashboard">
    ```handlebars theme={null}
    {{filters.filter_id.element}}
    ```
  </Tab>

  <Tab title="Workbook">
    ```handlebars theme={null}
    {{filters.view_name.field_name.element}}
    ```
  </Tab>
</Tabs>

Requires the following keys:

<ParamField>
  Accesses filter data
</ParamField>

<ParamField>
  The ID of a dashboard filter. Refer to the [Locating keys section](#control_id-and-filter_id) for help finding this value.
</ParamField>

<ParamField>
  The name of the view that contains the field used in a workbook filter
</ParamField>

<ParamField>
  The name of the field used in a workbook filter. Refer to the [Locating keys section](#view_name-and-field_name) for help finding this and the `view_name`.
</ParamField>

<ParamField>
  The data you want to retrieve, such as `label`. Refer to the following section for information on what's currently supported.
</ParamField>

### Label

Returns the label of the filter. In a dashboard, open the **Edit** panel for the filter and locate the **Label** field.

<Tabs>
  <Tab title="Dashboard">
    ```handlebars theme={null}
    {{filters.filter_id.label}}
    ```
  </Tab>

  <Tab title="Workbook">
    ```handlebars theme={null}
    {{filters.view_name.field_name.label}}
    ```
  </Tab>
</Tabs>

<Card title="Example (workbook)">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{filters.customers.country.label}}
      ```
    </div>

    <Frame>
      <img alt="Example filter label" />
    </Frame>
  </Columns>
</Card>

### Summary

Returns the default value (summary) of the filter. In a dashboard, open the **Edit** panel for the filter and locate the **Default value** field.

<Tabs>
  <Tab title="Dashboard">
    ```handlebars theme={null}
    {{filters.filter_id.summary}}
    ```
  </Tab>

  <Tab title="Workbook">
    ```handlebars theme={null}
    {{filters.view_name.field_name.summary}}
    ```
  </Tab>
</Tabs>

<Card title="Example (workbook)">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{filters.customers.country.summary}}
      ```
    </div>

    <Frame>
      <img alt="Example filter summary" />
    </Frame>
  </Columns>
</Card>

### Value

Returns the current value of the filter.

<Tabs>
  <Tab title="Dashboard">
    ```handlebars theme={null}
    {{filters.filter_id.value}}
    ```
  </Tab>

  <Tab title="Workbook">
    ```handlebars theme={null}
    {{filters.view_name.field_name.value}}
    ```
  </Tab>
</Tabs>

```handlebars title="Example (workbook)" theme={null}
{{filters.customers.country.value}}
```

### URL-encoded value

Returns the current value of the filter, URL-encoded. Use this when you need to include filter values in URL query parameters within Markdown links.

<Tabs>
  <Tab title="Dashboard">
    ```handlebars theme={null}
    {{filters.filter_id.value_url_encoded}}
    ```
  </Tab>

  <Tab title="Workbook">
    ```handlebars theme={null}
    {{filters.view_name.field_name.value_url_encoded}}
    ```
  </Tab>
</Tabs>

```handlebars title="Example (dashboard)" theme={null}
[View details](https://example.com/report?country={{filters.8v_G12D7.value_url_encoded}})
```

### JSON

Returns the URL-encoded JSON of the filter.

<Tabs>
  <Tab title="Dashboard">
    ```handlebars theme={null}
    {{filters.filter_id.json}}
    ```
  </Tab>

  <Tab title="Workbook">
    ```handlebars theme={null}
    {{filters.view_name.field_name.json}}
    ```
  </Tab>
</Tabs>

```handlebars title="Example (dashboard)" theme={null}
{{filters.8v_G12D7.json}}
```

## Controls

Returns metadata about [dashboard controls](/visualize-present/dashboards).

```handlebars title="Syntax" theme={null}
{{controls.control_id.element}}
```

Requires the following keys:

<ParamField>
  Accesses control data
</ParamField>

<ParamField>
  The ID of the control, located in the **Edit control** panel. Refer to the [Locating keys section](#control_id-and-filter_id) if you need help finding this panel.
</ParamField>

<ParamField>
  The data you want to retrieve, such as `label`. Refer to the following section for information on what's currently supported.
</ParamField>

### Label

Returns the label of the control. In a dashboard, open the **Edit** panel for the control and locate the **Label** field.

```handlebars title="Syntax" theme={null}
{{controls.id.label}}
```

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{controls.8v_G12D7.label}}
      ```
    </div>

    <Frame>
      <img alt="Example control label" />
    </Frame>
  </Columns>
</Card>

### Summary

Returns the default value (summary) of the control. In a dashboard, open the **Edit** panel for the control and locate the **Default value** field.

```handlebars title="Syntax" theme={null}
{{controls.id.summary}}
```

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{controls.8v_G12D7.summary}}
      ```
    </div>

    <Frame>
      <img alt="Example control summary (default value)" />
    </Frame>
  </Columns>
</Card>

### Value

Returns the full database name (`view_name.field_name`) of the field currently selected in the control.

```handlebars title="Syntax" theme={null}
{{controls.id.value}}
```

<Card title="Example">
  <Columns>
    <div>
      ```handlebars title="Input" theme={null}
      {{controls.8v_G12D7.value}}
      ```
    </div>

    <Frame>
      <img alt="Example control value" />
    </Frame>
  </Columns>
</Card>

### URL-encoded value

Returns the value of the control, URL-encoded. Use this when you need to include control values in URL query parameters within Markdown links.

```handlebars title="Syntax" theme={null}
{{controls.id.value_url_encoded}}
```

```handlebars title="Example" theme={null}
[View details](https://example.com/report?field={{controls.8v_G12D7.value_url_encoded}})
```

### JSON

Returns the URL-encoded JSON of the control.

```handlebars title="Syntax" theme={null}
{{controls.id.json}}
```

```handlebars title="Example" theme={null}
{{controls.8v_G12D7.json}}
```

```txt wrap title="Example output" theme={null}
%7B%22id%22%3A%228v_G12D7%22%2C%22kind%22%3A%22FIELD%22%2C%22type%22%3A%22FIELD_SELECTION%22%2C%22field%22%3A%22customers.birthday%5Bdate%5D%22%2C%22label%22%3A%22Control%20(Switcher)%22%2C%22options%22%3A%5B%7B%22label%22%3A%22Birthday%20Date%22%2C%22value%22%3A%22maincustomers.birthday%5Bdate%5D%22%2C%22isDimension%22%3Atrue%7D%2C%7B%22label%22%3A%22Created%20Date%20Date%22%2C%22value%22%3A%22main__customers.created_date%5Bdate%5D%22%2C%22isDimension%22%3Atrue%7D%5D%7D
```

## Dashboard metadata

Returns metadata about the dashboard itself. Available in [Markdown dashboard tiles](/visualize-present/dashboards/text-markdown).

```handlebars title="Syntax" theme={null}
{{metadata.element}}
```

Requires the following keys:

<ParamField>
  Accesses Omni metadata
</ParamField>

<ParamField>
  The data you want to retrieve. Refer to the following sections for information on what's currently supported.
</ParamField>

### Created at

Returns the timestamp when the dashboard was created.

```handlebars title="Syntax" theme={null}
{{metadata.createdAt}}
```

### Created by

Returns the name of the user who created the dashboard.

```handlebars title="Syntax" theme={null}
{{metadata.createdBy}}
```

### Last updated at

Returns the timestamp when the dashboard was last modified.

```handlebars title="Syntax" theme={null}
{{metadata.lastUpdatedAt}}
```

## User attribute metadata

Returns information about the [user attributes](/administration/users/attributes) associated with the user currently viewing the dashboard.

```handlebars theme={null}
{{metadata.userAttributes.attribute_reference.element}}
```

Requires the following keys:

<ParamField>
  Accesses Omni metadata
</ParamField>

<ParamField>
  Accesses Omni user attribute data
</ParamField>

<ParamField>
  The reference of the attribute you want to retrieve data for, for example `omni_user_email`. The following sections demonstrate some of the Omni system attributes you can use in tags. Refer to the **Reference** column in [**Settings > User attributes**](/administration/users/attributes) to locate an attribute's reference.
</ParamField>

<ParamField>
  The data you want to retrieve. Can be either of the following:

  * `label` - The display name of the attribute, for example `Omni user email`
  * `values` - The attribute value set for the user
</ParamField>

### User email

Returns the email address (`omni_user_email` value) of the user currently viewing the dashboard.

```handlebars title="Syntax" theme={null}
{{metadata.userAttributes.omni_user_email.values}}
```

### User name

Returns the user name (`omni_user_name` value) of the user currently viewing the dashboard.

```handlebars title="Syntax" theme={null}
{{metadata.userAttributes.omni_user_name.values}}
```

### User ID

Returns the user ID (`omni_user_id` value) of the user currently viewing the dashboard.

```handlebars title="Syntax" theme={null}
{{metadata.userAttributes.omni_user_id.values}}
```

### Is org admin?

Returns `true` if the user currently viewing the dashboard is an [Organization Admin](/administration/users/permissions) (`omni_is_org_admin` value). Otherwise, returns `false`.

```handlebars title="Syntax" theme={null}
{{metadata.userAttributes.omni_is_org_admin.values}}
```

### Custom user attribute

Returns the value of a [custom user attribute](/administration/users/attributes) of the user currently viewing the dashboard, where `custom_attribute_reference` is the **reference** of the custom attribute.

```handlebars title="Syntax" theme={null}
{{metadata.userAttributes.custom_attribute_reference.values}}
```

```handlebars title="Example" theme={null}
{{metadata.userAttributes.blob_entity.values}}
```

### User groups

Returns a list of [user groups](/administration/users/groups) (`omni_user_groups` value) that the user currently viewing the dashboard is a member of.

If the user is a member of more than one group, the output will be a comma-delimited list like `Group 1, Group 2`.

```handlebars title="Syntax" theme={null}
{{metadata.userAttributes.omni_user_groups.values}}
```


# Color by / Stacking
Source: https://docs.omni.co/visualize-present/visualizations/configuration/color

Configure color-by dimensions and stacking options to create multi-series charts with distinct visual groupings in Omni workbooks.

## Color options

Color sets a facet across the given data set to create individual series. Color options also include stacking controls for the visualization.

There will be slightly different options for string, date, and numeric data. Strings only offer discrete bucketing, while date and numeric data will offer both discrete (nominal) and continuous (temporal or quantitative) coloring. Note also that the palette options will change for discrete vs continuous, with discrete offering diverging color palettes and continuous offering a set of gradient color palettes.

When continuous options are not offered on an apparent date or numeric, casting the field may solve the problem.

<AccordionGroup>
  <Accordion title="String options" icon="font">
    <img alt="" />
  </Accordion>

  <Accordion title="Numeric options" icon="1">
    <img alt="" />
  </Accordion>

  <Accordion title="Date options" icon="calendar">
    <img alt="" />
  </Accordion>
</AccordionGroup>

## Palettes and color faceting

When using color faceting, Omni automatically applies the organization's [default color palette](/administration/chart-palettes/default) to your chart, using the discrete or continuous palette appropriate to the data. In the case of discrete data, colors from the palette are automatically applied based on the sort order of the query and the color order in the palette.

For continuous data, the gradient palette is automatically applied to the range of the values from the query results. Select a different option from the palette menu to update the color treatment.

<img alt="" />

Use the **Reverse colors** option to reverse the order in which colors from the palette are applied to the data.

With color faceting, the series **are not** independently configurable. For independent color configuration of a given series, [create separate measures](/analyze-explore/custom-fields/filtered-measures) for each series and refer to the section below on [series color controls](#series-color-controls).

### Custom palettes

If one of the provided palettes doesn't quite suit your visualization needs, a custom palette can be built for an individual chart. The last option in either the continuous or discrete palette menus is a **Custom** palette option. Select this option and then click the **Customize button** next to the menu. From here you can add, remove, and edit the palette colors:

<img alt="" />

Use the **Open hex code editor** button to toggle a bulk editor. This makes it easy to copy and paste a list of comma-separated hex values.

<img alt="" />

Custom palettes built for individual charts can be reused by copying and pasting the hex codes from chart to chart. If you find yourself using the same custom palette repeatedly, an administrator can [add additional palettes to the organization](/administration/chart-palettes) to make it broadly available in the palette menu.

## Gradient color scale values

When using a continuous gradient palette to color a visualization by a numeric field, you can pin specific values for the minimum, midpoint, and maximum of the color scale. This allows you to control exactly which data values map to which colors in the gradient, rather than always using the automatic data range.

A **Scale values** row appears in the color configuration panel whenever you have a quantitative (continuous numeric) color field. You can set:

* **Min** - The minimum value for the color scale. Values at or below this value will use the first color in the gradient. If left unset, defaults to the minimum value in the data.
* **Mid** - The midpoint value for the color scale. This value will use the middle color in the gradient and remain within the min and max bounds.
* **Max** - The maximum value for the color scale. Values at or above this value will use the last color in the gradient. If left unset, defaults to the maximum value in the data.

When data values fall outside the pinned range, they are clamped to the boundary colors. For example, if you set **Max** to `100` but have data values of `150`, those values will display using the same color as the `100` value.

## Series color controls

Color controls are available on a series-by-series basis when no color facet is applied (with a single measure and no color, or with multiple measures). This will offer a simple color picker for each series.

<img alt="" />

You can also map a color to a specific measure when using it as a series with the [measure's `colors` parameter](/modeling/measures/parameters/colors).

## Stacking options

Several stacking options are supported:

* **Automatic**: Omni will attempt to select the best option from the four below
* **Stack**: The series will be stacked
* **Group**: The series will appear side-by-side (only offered for bar charts)
* **Overlay**: The series will appear on top of each other. This is how points and lines frequently work, but rarely valuable for bar.
* **Stack %**: The series will be stacked, and shown as the percentage rather than the absolute values. **Note**: The tooltip will show the raw value, not the percentage, so to add percentage it's recommended to use table calculations like `% of row`.

### Stacked segment sorting

When using stacking, you can control how the stacked segments are sorted using the **Sort stack by** option. The following sorting options are available:

* **Label**: Sorts segments alphabetically by dimension value. This is the default option.
* **Value**: Sorts segments by their measure value within each individual stack. This option is only available for bar and column charts.
* **Sum**: Sorts segments by their total sum across all stacks. This is useful when you want to see which segments contribute the most overall, regardless of their value in any individual stack.
* **Unsorted**: Preserves the original data order from your query results.

<Note>
  The **Value** sorting option is only available for bar and column charts. For area and line charts, use **Sum** to sort by total contribution or **Label** for alphabetical ordering.
</Note>

## Legend options

Legends can be located on the right, left, top, or bottom of the chart. They can also be hidden.

## Dimension colors

<Note>
  Dimension color modeling isn't currently supported everywhere in the workbook. For example, dimension color mapping won't apply colors to table cells.
</Note>

Omni supports the ability to define consistent coloring for dimensions across visualizations, whether they're in the same document or in different documents. Using the [`colors` parameter in a dimension](/modeling/dimensions/parameters/colors), you can map a color to specific values.

For example, the following image shows an example of two bar charts that include a `status` field. Notice that the bars for the `Complete` status are the same color:

<img alt="" />

### Assigning colors to dimensions in the IDE

To achieve this in your own visualizations:

1. In the IDE, add the `colors` parameter to a dimension in a [view](/modeling/views) or [query view](/modeling/query-views). For example:

   ```
   dimensions:  status:    order_by_field: status_order    colors:       conditions:                      # List of conditions        - condition:                   # Required. A condition, specified using filter syntax.            is: Complete          color: green                 # Required. The color to be used in visualizations when the condition is met      else: red                        # Optional. Specifies fallback color if no condition is met
   ```

   Refer to the [Dimensions parameter reference](/modeling/dimensions/parameters/colors) for more information and examples.

2. In the **Chart** tab of the workbook, drag the dimension to the **Color** field:

   <img alt="" />


# Series configuration
Source: https://docs.omni.co/visualize-present/visualizations/configuration/series-configuration

Configure individual chart series in Omni, including chart type, axis assignment, label formatting, and data display options.

Each series / field offers configuration in addition to the axis configuration. In this area the data itself can be controlled (vs the axis or facet like color). To configure the  or  generally follow the corresponding settings.

To access the configuration menu, click the **caret** to the left of the `X` in either an X-axis or Y-axis field in the **Chart Options**:

<img alt="" />

## X-Axis series configuration

<img alt="" />

The X-Axis configuration offers controls for the label (which mirrors the x-axis label controls). Additional configuration is available for formatting of values (number, percentage, currency, and integer) as well as number of decimals. By default series will mirror formatting in the results table (auto).

## Y-Axis series configuration

<img alt="" />

The y-axis configuration will mirror the x-axis configuration with additional controls for labeling data points and trendlines.

### Visualization data labels

<img alt="" />

The **Labels** tab contains configuration options for data labels, which display as values above each point in the graph.

To make the labels more dense, check the **Show all labels** box.

By default, points are labeled with the series in use, but can also reference other fields (ie. labeling a measure-measure XY scatterplot with data labels for the dimension).

Position will move the label vis-a-vis the data point (by default overlaid).

### Trendlines / moving average / regression lines

<img alt="" />

The **Analytics** tab contains configuration options for adding moving averages to charts or regression lines. **Note**: Displaying the regression formula or r-squared isn't currently supported.

**For moving averages,** the trend line will mirror the order in the table when toggling between center and lagging, so for desired behavior the table may need to be resorted.

**For more custom trendlines and moving averages,** it's recommended to build [calculations](/analyze-explore/calculations) in the results table.


# Series mapping
Source: https://docs.omni.co/visualize-present/visualizations/configuration/series-mapping

Rearrange dimensions, measures, and pivots across chart axes and facets to build different visualization types from the same data.

Any column (dimensions, measures, or calculations) or pivot can be re-arranged in the visualization layer. This allows for the flexible construction of many different types of visualizations over the same results table.

Each facet is presented at the bottom of the visualization configuration under available fields.

<img alt="" />

### Duplicating fields across facets

Fields can be used across more than one facet by dragging from available fields into the corresponding facet. Alternatively the fields can be moved by grabbing a token and changing the chart. Here are a few examples with our original query:

<img alt="" />

<img alt="" />

<img alt="" />

<img alt="" />


# Size by
Source: https://docs.omni.co/visualize-present/visualizations/configuration/size

For scatterplots, fields can be mapped to control the size of each bubble.

<img alt="" />

## Configuration

The only configuration available is showing or hiding the size legend, which will hide the circles that correspond to size at the right. Note that you may also want to hide the color by legend, which is done under color configuration.

<img alt="" />


# Tooltips
Source: https://docs.omni.co/visualize-present/visualizations/configuration/tooltips

Customize chart tooltips in Omni by adding fields, reordering series, and controlling which data values appear on hover.

Tooltips can be adjusted by dragging series from 'Available Fields' into the tooltip section. They are not required to be visualized to show in the tooltip, and will display in the order added. For control over formatting, the series can be adjusted in the table view. If no series are present in the tooltip area, tooltips will be inactive.

<img alt="" />

## Notes

Tooltips can also be significantly adjusted in advanced mode using the [Vega lite spec](https://vega.github.io/vega-lite/docs/tooltip.html).


# X-axis configuration
Source: https://docs.omni.co/visualize-present/visualizations/configuration/x-axis

To access the configuration options for the X-axis, click the  (configuration options) icon to the right of the  label:

<img alt="" />

## Options

<Check>
  These settings control only the axis itself. To customize the [series mapped to the axis](/visualize-present/visualizations/configuration/series-configuration), use the dropdown next to the series/field.
</Check>

The settings in the **X-Axis** tab control the title, type, and sorting of the axis.

### Axis types

The **Type** setting controls the type of X-axis used in the visualization. Omni will select a default axis type depending on the data in the query, but you can override it using this setting.

Omni adjusts axis treatment for different data types and visualization types:

* **Strings** - Axes will always be ordinal, and, by default, obey sort in the results table
* **Numbers** - Bars are ordinal; line, scatter, area are quantitative (continuous)
* **Dates** - Bars are ordinal; line, scatter, area are temporal (continuous)

For the ordinal series, note that missing rows **will not** be displayed. We recommend that you [fill missing rows](/analyze-explore/point-click-queries#filling-missing-data) to retrieve these values when that is desirable.

## Labels

The settings in the **Labels** tab allow you to customize how labels associated with the X-axis display in the visualization:

* **Show labels** - If enabled, labels will display on the X-axis

* **Show axis line** - If enabled, a line representing the X-axis will display

* **Show ticks** - If enabled, ticks will display along the X-axis

* **Font** - Options for customizing the styling and color of X-axis labels

  <Check>
    When selecting axis colors, note that there aren't separate settings for light and dark mode.

    The default palette will adjust colors based on the selected mode - such as a dark axis in light mode - but when explicitly defined, the color you select will be used in both light and dark mode.
  </Check>

* **Format** - Defines the format X-axis labels use, such as `MMM-DD-YY` for dates

* **Label rotation** - Controls the degree of rotation for X-axis labels

* **Ticks** - Controls the number of ticks that display between labels

### Label spacing

Axis labels will behave differently for continuous / temporal axes (vs ordinal / string).

* **In continuous mode,** the labels will be spaced so as not to cut text, but may not align exactly with the visualization points
* **In ordinal mode,** the values will be labeled one-by-one and hidden in consistent intervals to avoid collision.

Currently, there aren't controls for label sparseness.

## Reference line

Settings in the **Reference line** tab allow you to define a reference line, which is a quick way to set targets on a chart. There is limited configuration for these, so more complex use cases may be better served with table calculations as a regular, independent series.

## Grid

Settings in the **Grid** tab control if and how grid lines display in the background of the visualization.

## Vega-lite options

Long-tail axis configuration is available in the [Vega-lite spec](https://vega.github.io/vega-lite/docs/axis.html).


# Y-axis (left axis / right axis)
Source: https://docs.omni.co/visualize-present/visualizations/configuration/y-axis

To access the configuration options for the Y-axis, click the  (configuration options) icon to the right of the  label:

<img alt="" />

## Options

<Check>
  These settings control only the axis itself. To customize the [series mapped to the axis](/visualize-present/visualizations/configuration/series-configuration), use the dropdown next to the series/field.
</Check>

The settings in the **Y-Axis** tab control the title, type, domain, scale, and stacking of the axis.

### Axis types

The **Type** setting controls the type of Y-axis used in the visualization. Omni will select a default axis type depending on the data in the query, but you can override it using this setting.

**Note**: Depending on the selected type, some settings - such as domain and scale - may become unavailable.

## Labels

The settings in the **Labels** tab allow you to customize how labels associated with the Y-axis display in the visualization:

* **Show labels** - If enabled, labels will display on the Y-axis

* **Show axis line** - If enabled, a line representing the Y-axis will display

* **Show ticks** - If enabled, ticks will display along the Y-axis

* **Font** - Options for customizing the styling and color of Y-axis labels

  <Check>
    When selecting axis colors, note that there aren't separate settings for light and dark mode.

    The default palette will adjust colors based on the selected mode - such as a dark axis in light mode - but when explicitly defined, the color you select will be used in both light and dark mode.
  </Check>

* **Format** - Defines the format Y-axis labels use, such as the number of decimals for numbers

* **Label rotation** - Controls the degree of rotation for Y-axis labels

* **Ticks** - Controls the number of ticks that display between labels

## Reference lines

<img alt="" />

Settings in the **Reference line** tab allow you to define a reference line, which is a quick way to set targets on a chart. There is limited configuration for these, so more complex use cases may be better served with table calculations as a regular, independent series.

## Grid

Settings in the **Grid** tab control if and how grid lines display in the background of the visualization.

## Vega-lite options

Long-tail axis configuration is available in the [Vega-lite spec](https://vega.github.io/vega-lite/docs/axis.html).


# Visualize data in Omni
Source: https://docs.omni.co/visualize-present/visualizations/index

Turn query results into charts, tables, KPIs, and custom visualizations in Omni workbooks.

Omni includes a library of built-in visualizations and configuration options to help you turn query results into clear, interactive charts. You can also use AI to generate visualizations automatically or build fully custom visuals with Vega-Lite.

## Chart types

Omni supports a range of [built-in chart types](/visualize-present/visualizations/types), including bar, line, area, pie, scatter, funnel, heatmap, KPI, map, sankey, boxplot, and more. Each type is designed for specific data patterns — refer to the [chart types overview](/visualize-present/visualizations/types) for guidance on when to use each one.

### Selecting a chart type

The quick chart icons in the workbook offer shortcuts to pre-configured chart types. They provide a fast way to switch between layouts like stacked vs. grouped bars, mixed bar-line charts, or toggle between table, chart, and Markdown views without digging into lower-level menus.

Omni will take a best guess at the right chart for each new query, while retaining any manual changes you've made to the configuration.

### Resetting chart settings

To clear the visualization and have Omni re-guess the best chart type, click **Tab > Reset Chart**.

## Generate visualizations with AI

[AI-generated visualizations](/ai/visualizations) let you describe the chart you want in natural language — like "show this as a bar chart grouped by region" — and Blobby will create and configure it for you. You can also use auto-suggest to let AI pick the best visualization for your data.

## Configure charts

Fine-tune the appearance and behavior of your visualizations with the [chart configuration](/visualize-present/visualizations/configuration/color) options:

* **[Color and stacking](/visualize-present/visualizations/configuration/color)** — Set color palettes, series coloring, and stacking behavior
* **[Series configuration](/visualize-present/visualizations/configuration/series-configuration)** — Control individual series display, labels, and formatting
* **[Series mapping](/visualize-present/visualizations/configuration/series-mapping)** — Map query fields to chart axes and dimensions
* **[Size](/visualize-present/visualizations/configuration/size)** — Adjust chart dimensions and responsive behavior
* **[Tooltips](/visualize-present/visualizations/configuration/tooltips)** — Customize hover information
* **[X-axis](/visualize-present/visualizations/configuration/x-axis)** and **[Y-axis](/visualize-present/visualizations/configuration/y-axis)** — Configure axis labels, scaling, and formatting

## Custom visualizations

For use cases that go beyond built-in chart types, Omni supports [custom visualizations](/visualize-present/visualizations/types/custom) using Vega-Lite specs or iframe-based Markdown tiles. This gives you full control over the rendering when you need it.


# AI summary visualization
Source: https://docs.omni.co/visualize-present/visualizations/types/ai-summary

Generate a summary of the current query's results with the AI summary visualization type.

<img alt="" />

## Requirements

To use this visualization type, you'll need:

* A query built on [topic data](/modeling/topics)
* To have the **AI Visualization Summary** setting enabled in [**AI Hub > General > Features**](/ai/settings/features#ai-visualization-summary). This is enabled by default.

## Building the query

To get the best results in the summary, keep the following in mind when building the underlying query:

* **Avoid pivoting or swapping rows/columns in the query**. This significantly reduces the context window, leaving little available for the actual data.
* **Include calculations and totals in the query if you want the summary to reference them.** This approach will provide better results over relying on the AI for calculations in the summary itself.

## Adding context

You can provide additional context in the chart's **Options** to guide the AI in generating the summary.

### Example: Specific audience and content

This example was given this context: `Explain it to me like I am a ceo and give me 3 followup questions`

<img alt="Test?" />

### Example: Specific tone

You can provide context to the AI that specifies the tone of the summary. For example, `Explain it to me like I am 5 in a pirate voice`

<img alt="Test?" />


# Area charts
Source: https://docs.omni.co/visualize-present/visualizations/types/area

Basic Area:

<img alt="" />

**Stacked Area:**

<img alt="" />

**Stack 100 Area:**

<img alt="" />

**Overlay Area:**

<img alt="" />

## Data Structures

Area charts can work with pivoted or unpivoted data, using 2 dimensions and one measure. To stack or group a chart, one series should be moved to the color facet.

**Unpivoted Data:**

<img alt="" />

**Pivoted Data**

<img alt="" />

Additionally area charts can plot using several measures at once:

<img alt="" />

## Line Configuration Notes

Area chart lines offer the same configuration as line charts:

### Line Mark

This is the line icon on each axis, and holds all of the overall configuration options.

<img alt="" />

### Show Points

Points can be toggles on/off to show alongside the lines (default contains no points).

<img alt="" />

### Dashes vs Solid Lines

Whether or not series are shown as solid lines or dashed lines is available (default solid).

<img alt="" />

### Line Thickness

The weight or thickness can be controlled (default 1).

<img alt="" />

### Line Opacity

Setting is available to make the line partially transparent (default solid).

<img alt="" />

### Point Interpolation for Lines

The method for interpolation between points can be controlled (default linear). Options include:

* Linear
* Monotone (smoothed)
* Step (point at midpoint of the step)
* Step Before
* Step After

<img alt="" />

## Overall Configuration Notes

The mark selector at the top of the configuration sets the global chart configuration (configuration across all series). Note that each series can be set independently to bar, line, scatter, area independently under their y-axis controls.

<img alt="" />

The color section controls overall stacking and grouping behavior overall. Additionally stack can be set independently on the different y-axis, under the y-axis series configuration (useful for overall grouping of two stacked grouplets):

* Automatic: we'll guess for you
* Stack: Series on same x-axis value, on top of each other
* Group: Series offset from their baseline x-axis mark into grouplets
* Overlay: Series *on top* of each other (usually very undesirable, but useful in rare cases)
* Stack %: Series rebased to 100% across each x-axis value

<img alt="" />

## Other Notes

* Time dimension axes are set to temporal with area charts, meaning points will be displayed along a continuous time axis. For charts where ordinal behavior is desired, it's recommended to toggle the individual series from a bar chart accelerator.

* With time fields, order will be automatically set to ascending; other data types will obey the table ordering when graphing

* Tooltips have two styles (see below):

  * On line charts with multiple measures, hover will highlight all available series along the x-axis vertically, vs just the series being hovered.
  * On line charts with a dimension mapped to color (and a single measure), the hover will only show the nearest point

<img alt="" />

<img alt="" />


# Bar charts
Source: https://docs.omni.co/visualize-present/visualizations/types/bar

Basic Bar:

<img alt="" />

**Group:**

<img alt="" />

**Stack:**

<img alt="" />

**Stack %:**

<img alt="" />

**Stacked Measures:**

<img alt="" />

**Grouped, Stacked Measures:**

<img alt="" />

## Data Structures

Bar charts can work with pivoted or unpivoted data, using 2 dimensions and one measure. To stack or group a chart, one series should be moved to the color facet.

**Unpivoted Data:**

<img alt="" />

**Pivoted Data**

<img alt="" />

Additionally bar charts can plot several measures at once:

<img alt="" />

## Configuration Notes

#### Setting Marks

The mark selector at the top of the configuration sets the global chart configuration (configuration across all series). Note that each series can be set independently to bar, line, scatter, area independently under their y-axis controls.

<img alt="" />

#### Stacking Settings

The color section controls overall stacking and grouping behavior overall. Additionally stack can be set independently on the different y-axis, under the y-axis series configuration (useful for overall grouping of two stacked grouplets):

* Automatic: we'll guess for you
* Stack: Series on same x-axis value, on top of each other
* Group: Series offset from their baseline x-axis mark into grouplets
* Overlay: Series *on top* of each other (usually very undesirable, but useful in rare cases)
* Stack %: Series rebased to 100% across each x-axis value

<img alt="" />

#### Show Totals Labels on Stacked Charts

For color-by stacked charts, totals can be labeled under the y-axis series configuration (Series > Labels > Simple Totals). Right now totals are not available for multiple-measure stacks. Additional configuration is provided for styling and value formatting of the labels:

* Positioning (Auto, Above, Below, Left, Right, Middle)
* Font size and color
* Bolding and italic
* Value formatting

<img alt="" />

## Other Notes

* Axes are set to ordinal with bars (vs temporal with line, scatter, and area charts). This means each bar will be labeled independently (not a continuous axis), the axes are not intelligent about time, and values that are not in the set will not be plotted. To fill missing rows, the data must be adjusted in the table - [more here](/analyze-explore/point-click-queries#filling-missing-data)
* With time fields, order will be automatically set to ascending; other data types will obey the table ordering when graphing
* Tooltips on stacked bars will be designated to the individual segment of the chart when using color by.


# Boxplots
Source: https://docs.omni.co/visualize-present/visualizations/types/boxplot

Create boxplot (box and whiskers) charts in Omni to visualize data distributions with quartiles, medians, and outliers.

Boxplot charts are a versatile and efficient way to summarize and compare data across categories. Sometimes called a box and whiskers chart, each boxplot shows the distribution of the data in that category by charting its five-number summary:

* Minimum: start of the left whisker line
* First quartile (Q1): left-edge of the box
* Median (Q2): center line
* Third quartile (Q3): right edge of the box
* Maximum value: end of the right whisker line.

To configure a boxplot in Omni, your results should have a category on the y-axis and the unaggregated numeric values on the x-axis.

<Tip>
  Looking to use dates within a Boxplot? You'll have to cast the date field to a string first!
</Tip>

<img alt="" />


# Custom visualizations
Source: https://docs.omni.co/visualize-present/visualizations/types/custom

Omni supports the most common visualization types and settings out of the box. However, if your business needs customization, you can:

* [Leverage an iframe tag in a Markdown tile](#iframe-custom-visualizations)
* [Create a Vega-Lite visualization](#vega-lite-visualizations)

## iframe custom visualizations

One way to create a custom visualization is to leverage an iframe tag in a Markdown tiles. The data in results + [postMessages](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) will render your custom iframes and provide a ton of flexibility.

For example:

```html theme={null}
<iframe src="https://example.html"></iframe>
```

**Note**: Included images won't render if they are scheduled. Additionally, the file must be hosted outside of Omni.

## Vega-Lite visualizations

Many of Omni's charts are backed by [Vega-Lite](https://vega.github.io/vega-lite/), which is a JSON-based spec for visualizations. You can directly edit a chart's code to customize it beyond what Omni provides out of the box.

If you are unfamiliar with Vega-Lite, check out the [Vega-Lite documentation](https://vega.github.io/vega-lite/docs/) before perusing the [example gallery](https://vega.github.io/vega-lite/examples/).

### Accessing the advanced editor

<Warning>
  Before opening the advanced editor, note that:

  * **The existing visualization will break**. To experiment with the advanced editor, create a copy of the query so you don't lose your work.
  * **Drill functionality will be unavailable**
</Warning>

In the **Chart** tab of any workbook query, there are two ways to access the advanced editor:

* **In the Chart selector** - Click the `{ ... }` icon to select the **Vega code** option. This will open the advanced editor, but without any pre-populated Vega code. This can be useful to start from scratch, such as with an [example from Vega](https://vega.github.io/vega-lite/examples/) or [one from the example gallery on this page](#examples).

* **In the chart editor** - For any chart powered by Vega-Lite, there will be a `{ }` icon in the chart editor. Clicking it will open a menu with the following options:

  * **View source** - Opens a dialog with the Vega-Lite JSON
  * **Open in advanced editor** - Copies the current chart code and opens it in the **Advanced editor**

<img alt="screenshot of the View Source menu" />

### Referencing data in the advanced editor

To use data from the results query, you'll need to reference the field by its view and field name as they are defined in the model. This will look like `view_name\\.field_name` in the editor.

The double forward-slashes (`\\`) are included because periods and brackets must be escaped. For example:

| Omni object               | Vega object                     |
| ------------------------- | ------------------------------- |
| `users.id`                | `users\\.id`                    |
| `users.age`               | `users\\.age`                   |
| `users.created_at`        | `users\\.created_at`            |
| `users.created_at[date]`  | `users\\.created_at\\[date\\]`  |
| `users.created_at[month]` | `users\\.created_at\\[month\\]` |
| `id`                      | `id`                            |

**Note**: In the last example, `id` would only occur from a raw SQL query as Omni will alias with the view.

### Saving and resetting changes

Custom visualizations must be manually saved. While the visualization will update as you edit, the code is not auto-saved. Periodically click the **Save** button to save your changes.

To remove all edits made to the code, click **Reset**. This will revert the code to its original version.

<img alt="Saving a Vega code visualization" />

## Examples

<Check>
  In addition to custom Vega-Lite visualizations, you can also build custom visualizations using HTML, CSS and Markdown. Check out the [Markdown visualization examples](/visualize-present/visualizations/types/markdown) for some inspiration.
</Check>

### US state map

<Warning>
  Omni recommends using the [native map visualization](/visualize-present/visualizations/types/map) for this visualization.
</Warning>

<img alt="" />

**Query fields**:

* `users.state` - Full-length state names are required for this visualization. To remove the legend, add `"legend":null` within `color{...`
* `users.user_count`

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "data": {
        "url": "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json",
        "format": {
          "type": "topojson",
          "feature": "states"
        }
      },
      "mark": {
        "fill": "lightgray",
        "type": "geoshape",
        "stroke": "black"
      }
    },
    {
      "mark": "geoshape",
      "width": "container",
      "height": "container",
      "encoding": {
        "href": {
          "type": "nominal",
          "field": "url"
        },
        "color": {
          "type": "quantitative",
          "field": "COLOR"
        },
        "shape": {
          "type": "geojson",
          "field": "geo"
        },
        "tooltip": [
          {
            "field": "STATE",
            "title": "State"
          },
          {
            "type": "quantitative",
            "field": "COLOR",
            "title": "User Count"
          }
        ]
      }
    }
  ],
  "width": "container",
  "height": "container",
  "transform": [
    {
      "as": "STATE",
      "calculate": "datum['your_view.your_state']"
    },
    {
      "as": "COLOR",
      "calculate": "datum['your_view.your_measure']"
    },
    {
      "as": "geo",
      "from": {
        "key": "properties.name",
        "data": {
          "url": "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json",
          "format": {
            "type": "topojson",
            "feature": "states"
          }
        }
      },
      "lookup": "STATE"
    },
    {
      "as": "url",
      "calculate": "'https://sandbox.proto.exploreomni.com/w/0a494c7e-3d8a-4f31-aa53-cb8d1e62f4fa/drill?ephemeral=DyXjRBEJ%2CRveZe1I6%2CZUK24UVr%2CHehug3WH%2CbuG0igrs%2CcNuuSY8a%2CnOHD__EL%2C3Dgpwy5c%2C0ta1FE8v%2CSsbC6Jdf&field=users.count&filters=%7B%7D&miniUuid=ZUK24UVr&row=%7B%22users.state%22%3A%22' + datum['users\\.state'] + '%22%2C%22state_id.state_id%22%3A%221%22%2C%22users.count%22%3A%221625%22%7D' "
    }
  ],
  "projection": {
    "type": "albersUsa"
  }
}
```

### US map with latitude and longitude

<Warning>
  Omni recommends using the [native map visualization](/visualize-present/visualizations/types/map) for this visualization.
</Warning>

<img alt="" />

**Query fields:**

* `users.zip`
* `users.zip_first_digit`
* `users.latitude_average`
* `users.longitude_average`
* `users.user_count`

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "data": {
        "url": "https://vega.github.io/editor/data/us-10m.json",
        "format": {
          "type": "topojson",
          "feature": "states"
        }
      },
      "mark": {
        "fill": "lightgray",
        "type": "geoshape",
        "stroke": "white"
      }
    },
    {
      "transform": [
        {
          "as": "LATITUDE",
          "calculate": "datum['users\\.latitude_average']"
        },
        {
          "as": "LONGITUDE",
          "calculate": "datum['users\\.longitude_average']"
        },
        {
          "as": "COLOR",
          "calculate": "datum['calc_1']"
        }
      ],
      "mark": {
        "type": "circle",
        "tooltip": true
      },
      "encoding": {
        "size": {
          "value": 5
        },
        "color": {
          "type": "nominal",
          "field": "COLOR",
          "scale": {
            "scheme": "magma"
          },
          "legend": null
        },
        "latitude": {
          "type": "quantitative",
          "field": "LATITUDE"
        },
        "longitude": {
          "type": "quantitative",
          "field": "LONGITUDE"
        }
      }
    }
  ],
  "width": "container",
  "height": "container",
  "projection": {
    "type": "albersUsa"
  }
}
```

### US map - zip code choropleth

<Warning>
  Omni recommends using the [native map visualization](/visualize-present/visualizations/types/map) for this visualization.
</Warning>

<img alt="" />

**Query fields**:

* `users.zip`
* `users.user_count`

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "data": {
        "url": "https://vega.github.io/editor/data/us-10m.json",
        "format": {
          "type": "topojson",
          "feature": "states"
        }
      },
      "mark": {
        "fill": "white",
        "type": "geoshape",
        "stroke": "black"
      }
    },
    {
      "mark": "geoshape",
      "width": "container",
      "height": "container",
      "encoding": {
        "color": {
          "type": "quantitative",
          "field": "users\\.count",
          "scale": {
            "domain": [
              0,
              20
            ],
            "scheme": "blues"
          },
          "legend": null
        },
        "shape": {
          "type": "geojson",
          "field": "geo"
        },
        "tooltip": [
          {
            "field": "ZIP"
          },
          {
            "type": "quantitative",
            "field": "COLOR",
            "title": "Users Count"
          }
        ]
      }
    }
  ],
  "transform": [
    {
      "as": "ZIP",
      "calculate": "datum['users.zip']"
    },
    {
      "as": "COLOR",
      "calculate": "datum['users.count']"
    },
    {
      "as": "geo",
      "from": {
        "key": "properties.zip",
        "data": {
          "url": "https://gist.githubusercontent.com/jefffriesen/6892860/raw/e1f82336dde8de0539a7bac7b8bc60a23d0ad788/zips_us_topo.json",
          "format": {
            "type": "topojson",
            "feature": "zip_codes_for_the_usa"
          }
        }
      },
      "lookup": "ZIP"
    }
  ],
  "projection": {
    "type": "albersUsa"
  }
}
```

### US map with labeled points

<Warning>
  Omni recommends using the native map visualization for standard geographic plotting. However, if you need to add labels directly to your map marks, you will need to use a custom Vega-Lite visualization to do so.
</Warning>

<img alt="" />

This visualization layers text marks directly inside colored coordinate points over a TopoJSON base map of the United States. It utilizes the `albersUsa` projection to automatically arrange the states appropriately.

**Query fields**:

* `view_name.latitude` - The latitude coordinate of the point.

* `view_name.longitude` - The longitude coordinate (must be a negative number for the albersUsa projection).

* `view_name.rank` - The text value to display inside the map marker.

* `view_name.category` - The categorical field used to assign colors to the points.

* `view_name.city` - Additional detail for the hover tooltip.

* `view_name.state` - Additional detail for the hover tooltip.

```json expandable title="Visualization code" theme={null}
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": { "name": "query" },
  "width": "container",
  "height": "container",
  "projection": { "type": "albersUsa" },
  "layer": [
    {
      "data": {
        "url": "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json",
        "format": { "type": "topojson", "feature": "states" }
      },
      "mark": { "type": "geoshape", "fill": "#e5e5e5", "stroke": "white", "strokeWidth": 1 }
    },
    {
      "transform": [
        { "calculate": "toNumber(datum['view_name.latitude'])", "as": "LATITUDE" },
        { "calculate": "toNumber(datum['view_name.longitude'])", "as": "LONGITUDE" },
        { "calculate": "datum['view_name.city']", "as": "CITY" },
        { "calculate": "datum['view_name.state']", "as": "STATE" },
        { "calculate": "datum['view_name.rank']", "as": "RANK" },
        { "calculate": "datum['view_name.category']", "as": "COLOR_CAT" },
        { "filter": "isValid(datum.LATITUDE) && isValid(datum.LONGITUDE)" }
      ],
      "encoding": {
        "longitude": { "field": "LONGITUDE", "type": "quantitative" },
        "latitude": { "field": "LATITUDE", "type": "quantitative" },
        "tooltip": [
          { "field": "RANK", "type": "nominal", "title": "Rank" },
          { "field": "CITY", "type": "nominal", "title": "City" },
          { "field": "STATE", "type": "nominal", "title": "State" }
        ]
      },
      "layer": [
        {
          "mark": { "type": "circle", "size": 300, "stroke": "white", "strokeWidth": 1.5, "opacity": 1 },
          "encoding": {
            "color": { 
              "field": "COLOR_CAT", 
              "type": "nominal",
              "scale": {
                "range": ["#F2B21B", "#6EC1F2"]
              },
              "legend": null 
            }
          }
        },
        {
          "mark": { "type": "text", "baseline": "middle", "align": "center", "fontWeight": "bold", "fontSize": 11 },
          "encoding": {
            "text": { "field": "RANK", "type": "nominal" },
            "color": { "value": "black" }
          }
        }
      ]
    }
  ],
  "config": { "view": { "stroke": null } }
}
```

### US state map - zip code choropleth

<img alt="" />

**Query fields:**

* `users.zip`
* `users.user_count`

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "data": {
        "url": "https://raw.githubusercontent.com/OpenDataDE/State-zip-code-GeoJSON/master/dc_district_of_columbia_zip_codes_geo.min.json",
        "format": {
          "property": "features"
        }
      },
      "mark": {
        "fill": "white",
        "type": "geoshape",
        "stroke": "black"
      }
    },
    {
      "mark": "geoshape",
      "width": "container",
      "height": "container",
      "encoding": {
        "color": {
          "type": "quantitative",
          "field": "users\\.count",
          "scale": {
            "domain": [
              0,
              20
            ],
            "scheme": "blues"
          },
          "legend": null
        },
        "shape": {
          "type": "geojson",
          "field": "geo"
        },
        "tooltip": [
          {
            "field": "users\\.zip"
          },
          {
            "type": "quantitative",
            "field": "users\\.count",
            "title": "Users Count"
          }
        ]
      }
    }
  ],
  "transform": [
    {
      "as": "geo",
      "from": {
        "key": "properties.ZCTA5CE10",
        "data": {
          "url": "https://raw.githubusercontent.com/OpenDataDE/State-zip-code-GeoJSON/master/dc_district_of_columbia_zip_codes_geo.min.json",
          "format": {
            "property": "features"
          }
        }
      },
      "lookup": "users\\.zip"
    }
  ],
  "projection": {
    "type": "albersUsa"
  }
}
```

### Radial chart

A radial chart layers in exploding pie slices using the square root of the value.

<img alt="" />

**Query Fields:**

* `products.category`
* `order_items.sale_price_sum`

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": {
        "type": "arc",
        "stroke": "#fff",
        "innerRadius": 30
      }
    },
    {
      "mark": {
        "dx": 4,
        "type": "text",
        "align": "center",
        "radiusOffset": 30
      },
      "encoding": {
        "text": {
          "type": "nominal",
          "field": "COLOR"
        }
      }
    }
  ],
  "height": "container",
  "width": "container",
  "encoding": {
    "color": {
      "type": "nominal",
      "field": "SIZE",
      "legend": null
    },
    "theta": {
      "type": "quantitative",
      "field": "SIZE",
      "stack": true
    },
    "radius": {
      "field": "SIZE",
      "scale": {
        "type": "sqrt",
        "zero": true,
        "rangeMin": 20
      }
    },
    "tooltip": [
      {
        "type": "nominal",
        "field": "COLOR",
        "title": "Category"
      },
      {
        "type": "quantitative",
        "field": "SIZE",
        "title": "Sales",
        "format": ",.2f"
      }
    ]
  },
  "transform": [
    {
      "as": "COLOR",
      "calculate": "datum['products.category']"
    },
    {
      "as": "SIZE",
      "calculate": "datum['order_items.sale_price_sum']"
    }
  ]
}
```

### Cross-filtered chart pair

This visualization aggregates the top visualization over the highlight selection. Two charts are built from the results table, stacked, and then wired together. **Note**: This visualization also uses pixel sizing, which isn't ideal for use on dashboards where `container` should be used for sizing.

<img alt="" />

**Query fields:**

* `order_items.created_at[date]` - Filtered to `2021`, the x-axis
* `products.category` - Filtered to five products, forming the color facets
* `order_items.sale_price_sum` - The y-axis
* `order_items.count` - The bubble size

```json expandable title="Visualization code" theme={null}
{
  "vconcat": [
    {
      "mark": "point",
      "width": 600,
      "height": 300,
      "params": [
        {
          "name": "brush",
          "select": {
            "type": "interval",
            "encodings": [
              "x"
            ]
          }
        }
      ],
      "encoding": {
        "x": {
          "type": "temporal",
          "field": "X_AXIS",
          "title": "Date"
        },
        "y": {
          "type": "quantitative",
          "field": "TOP_Y",
          "title": "Total Sales"
        },
        "size": {
          "type": "quantitative",
          "field": "BOTTOM_Y",
          "title": "Count of Sales"
        },
        "color": {
          "value": "lightgray",
          "condition": {
            "type": "nominal",
            "field": "COLOR",
            "param": "brush",
            "title": "Category"
          }
        }
      },
      "transform": [
        {
          "as": "X_AXIS",
          "calculate": "datum['order_items.created_at[date]']"
        },
        {
          "as": "TOP_Y",
          "calculate": "datum['order_items.sale_price_sum']"
        },
        {
          "as": "BOTTOM_Y",
          "calculate": "datum['order_items.order_count']"
        },
        {
          "as": "COLOR",
          "calculate": "datum['products.category']"
        },
        {
          "filter": {
            "param": "click"
          }
        }
      ]
    },
    {
      "mark": "bar",
      "width": 600,
      "params": [
        {
          "name": "click",
          "select": {
            "type": "point",
            "encodings": [
              "color"
            ]
          }
        }
      ],
      "encoding": {
        "x": {
          "field": "TOP_Y",
          "title": "Sales",
          "aggregate": "sum"
        },
        "y": {
          "field": "COLOR",
          "title": "Category"
        },
        "color": {
          "value": "lightgray",
          "condition": {
            "field": "COLOR",
            "param": "click"
          }
        }
      },
      "transform": [
        {
          "as": "X_AXIS",
          "calculate": "datum['order_items.created_at[date]']"
        },
        {
          "as": "TOP_Y",
          "calculate": "datum['order_items.sale_price_sum']"
        },
        {
          "as": "BOTTOM_Y",
          "calculate": "datum['order_items.order_count']"
        },
        {
          "as": "COLOR",
          "calculate": "datum['products.category']"
        },
        {
          "filter": {
            "param": "brush"
          }
        }
      ]
    }
  ]
}
```

### Flag marks scatterplot

<Warning>
  This visualization won't render if used in a [delivery or alert](/share/deliveries).
</Warning>

This chart uses data about each country's economy and a flag emoji to create a scatterplot. The flag emoji is used as the mark to represent the country. This example also uses log-scale.

<img alt="" />

**Query fields:**

* `flag` - Flag emoji
* `name` - Country name
* `rank`
* `gdp`
* `growth`
* `population`
* `gdp_per_capita`
* `gdp_percent_share`

**Example dataset**:

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "mark": {
    "type": "text",
    "fontSize": 30
  },
  "width": "container",
  "height": "container",
  "transform": [
    {
      "as": "COUNTRY",
      "calculate": "datum['users.country']"
    },
    {
      "as": "X_AXIS",
      "calculate": "datum['users.count']"
    },
    {
      "as": "Y_AXIS",
      "calculate": "datum['order_items.sale_price_sum']"
    },
    {
      "as": "ICON",
      "calculate": "datum['calc_1']"
    }
  ],
  "encoding": {
    "x": {
      "type": "quantitative",
      "field": "X_AXIS",
      "scale": {
        "type": "log"
      }
    },
    "y": {
      "axis": {
        "labelOverlap": true
      },
      "type": "quantitative",
      "field": "Y_AXIS",
      "scale": {
        "type": "log"
      }
    },
    "text": {
      "type": "nominal",
      "field": "ICON"
    },
    "tooltip": [
      {
        "sort": null,
        "type": "nominal",
        "field": "ICON"
      },
      {
        "sort": null,
        "type": "nominal",
        "field": "name",
        "title": "COUNTRY"
      },
      {
        "sort": null,
        "type": "quantitative",
        "field": "X_AXIS"
      },
      {
        "type": "quantitative",
        "field": "Y_AXIS"
      }
    ]
  }
}
```

### Waterfall

This waterfall chart requires both a custom visualization spec and some query munging. In this example, a change occurs state-by-state, at which point special bars are appended for the starting and ending values.

**Note**: The Vega spec contains a lot of calculation. This is intended to demonstrate the ability to extend the dataset to enhance the visualization.

<img alt="" />

**Query fields**:

* `label`
* `value`

#### Unioned queries

The underlying data is brought together by using a SQL `UNION` clause.

```sql theme={null}
(
  SELECT 'Begin' AS "label",
          1000 AS "amount"
   FROM users
   LIMIT 1
)
UNION ALL
( 
   SELECT "users.state",
          "amount"
   FROM orders
)
UNION ALL
(
  SELECT 'End',
          0
   FROM users
   LIMIT 1
)
```

* **Begin row**: Start value. Must be named `'Begin'` for label; this can be replaced with the first value from the dataset in the future.
* **Waterfall data set:** Build with the UI and drop in the SQL, or use the Advanced Editor to write SQL. When updating to your own query data, remember to [reference data](#referencing-data-in-the-advanced-editor) with the `view_name\\.field_name` syntax.
* **End row:** Value must be `0`. Must be named `'End'`; this can be replaced in the future since it's all implied.

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": {
        "size": 45,
        "type": "bar"
      },
      "encoding": {
        "y": {
          "type": "quantitative",
          "field": "previous_sum",
          "title": "Amount"
        },
        "y2": {
          "field": "sum"
        },
        "color": {
          "value": "#93c4aa",
          "condition": [
            {
              "test": "datum.LABEL === 'Begin' || datum.LABEL === 'End'",
              "value": "#f7e0b6"
            },
            {
              "test": "datum.sum < datum.previous_sum",
              "value": "#f78a64"
            }
          ]
        }
      }
    },
    {
      "mark": {
        "type": "rule",
        "color": "#404040",
        "opacity": 1,
        "xOffset": -22.5,
        "x2Offset": 22.5,
        "strokeWidth": 2
      },
      "encoding": {
        "y": {
          "type": "quantitative",
          "field": "sum"
        },
        "x2": {
          "field": "lead"
        }
      }
    },
    {
      "mark": {
        "dy": -4,
        "type": "text",
        "baseline": "bottom"
      },
      "encoding": {
        "y": {
          "type": "quantitative",
          "field": "sum_inc"
        },
        "text": {
          "type": "nominal",
          "field": "sum_inc",
          "format": "bigusdcurrency_2",
          "formatType": "omniNumberFormat"
        },
        "opacity": {
          "condition": {
            "test": "datum['sum_inc'] == 0",
            "value": "0"
          }
        }
      }
    },
    {
      "mark": {
        "dy": 4,
        "type": "text",
        "baseline": "top"
      },
      "encoding": {
        "y": {
          "type": "quantitative",
          "field": "sum_dec"
        },
        "text": {
          "type": "nominal",
          "field": "sum_dec",
          "format": "bigusdcurrency_2",
          "formatType": "omniNumberFormat"
        },
        "opacity": {
          "condition": {
            "test": "datum['sum_dec'] == 0",
            "value": "0"
          }
        }
      }
    },
    {
      "mark": {
        "type": "text",
        "baseline": "middle",
        "fontWeight": "bold"
      },
      "encoding": {
        "y": {
          "type": "quantitative",
          "field": "center"
        },
        "text": {
          "type": "nominal",
          "field": "AMOUNT",
          "format": "bigusdcurrency_2",
          "formatType": "omniNumberFormat"
        },
        "color": {
          "value": "white",
          "condition": [
            {
              "test": "datum.LABEL === 'Begin' || datum.LABEL === 'End'",
              "value": "#725a30"
            }
          ]
        },
        "opacity": {
          "condition": {
            "test": "datum['amount_percent'] < 0.07",
            "value": "0"
          }
        }
      }
    }
  ],
  "width": "container",
  "config": {
    "text": {
      "color": "#404040",
      "fontWeight": "bold"
    }
  },
  "height": "container",
  "encoding": {
    "x": {
      "axis": {
        "title": "Months",
        "labelAngle": 0
      },
      "sort": null,
      "type": "ordinal",
      "field": "LABEL"
    }
  },
  "transform": [
    {
      "as": "LABEL",
      "calculate": "datum['label']"
    },
    {
      "as": "AMOUNT",
      "calculate": "datum['amount']"
    },
    {
      "window": [
        {
          "as": "sum",
          "op": "sum",
          "field": "AMOUNT"
        }
      ]
    },
    {
      "window": [
        {
          "as": "lead",
          "op": "lead",
          "field": "LABEL"
        }
      ]
    },
    {
      "joinaggregate": [
        {
          "as": "total",
          "op": "sum",
          "field": "AMOUNT"
        }
      ]
    },
    {
      "as": "lead",
      "calculate": "datum.lead === null ? datum.LABEL : datum.lead"
    },
    {
      "as": "previous_sum",
      "calculate": "datum.LABEL === 'End' ? 0 : datum.sum - datum.AMOUNT"
    },
    {
      "as": "amount",
      "calculate": "datum.LABEL === 'End' ? datum.sum : datum.AMOUNT"
    },
    {
      "as": "text_amount",
      "calculate": "(datum.LABEL !== 'Begin' && datum.LABEL !== 'End' && datum.AMOUNT > 0 ? '+' : '') + datum.AMOUNT"
    },
    {
      "as": "amount_percent",
      "calculate": "abs(datum.AMOUNT) / datum.total"
    },
    {
      "as": "center",
      "calculate": "(datum.sum + datum.previous_sum) / 2"
    },
    {
      "as": "sum_dec",
      "calculate": "datum.sum < datum.previous_sum ? datum.sum : ''"
    },
    {
      "as": "sum_inc",
      "calculate": "datum.sum > datum.previous_sum ? datum.sum : ''"
    }
  ]
}
```

### Tapered funnel

A tapered funnel is used to measure a funnel using several filtered measures. This chart calculates overall dropoff and step-by-step dropoff.

You can add or remove stages by editing the `fold` section and then the subsequent steps, removing the backticks: `users\\.count` then `"measurename": "users.count"`.

<img alt="" />

**Query fields:**

* `users.count`
* `users.count_california_seniors`
* `users.count_minors`
* `users.count_california_minors`

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": {
        "type": "bar",
        "color": "transparent"
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "stagePos"
        }
      }
    },
    {
      "mark": {
        "type": "bar",
        "tooltip": true
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "negCount"
        },
        "color": {
          "field": "stage",
          "scale": {
            "scheme": {
              "name": "oranges",
              "extent": [
                0.8,
                0
              ]
            }
          },
          "legend": null
        },
        "tooltip": [
          {
            "type": "nominal",
            "field": "stage",
            "title": "Stage"
          },
          {
            "type": "quantitative",
            "field": "count",
            "title": "Count"
          }
        ]
      }
    },
    {
      "mark": {
        "dx": {
          "expr": "datum.labelLeft ? -4 : 4"
        },
        "type": "text",
        "align": {
          "expr": "datum.labelLeft ? 'right' : 'left'"
        }
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "negCount"
        },
        "text": {
          "field": "count"
        }
      }
    },
    {
      "mark": {
        "dx": 4,
        "type": "text",
        "align": "left"
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "stagePos"
        },
        "text": {
          "field": "stage"
        }
      }
    },
    {
      "mark": {
        "type": "text",
        "align": "center"
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "cumulativePos"
        },
        "text": {
          "field": "cumulativePct",
          "format": ".1%"
        }
      }
    },
    {
      "mark": {
        "type": "text",
        "align": "center"
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "conversionPos"
        },
        "text": {
          "field": "conversionPct",
          "format": ".1%"
        }
      },
      "transform": [
        {
          "filter": "isValid(datum.previousCount)"
        }
      ]
    },
    {
      "mark": {
        "dx": {
          "expr": "datum.dx"
        },
        "type": "text",
        "align": {
          "expr": "datum.align"
        }
      },
      "encoding": {
        "x": {
          "axis": "",
          "type": "quantitative",
          "field": "pos"
        },
        "y": {
          "axis": null,
          "type": "nominal",
          "datum": "0. Titles"
        },
        "text": {
          "field": "caption"
        }
      },
      "transform": [
        {
          "filter": "!isValid(datum.previousCount)"
        },
        {
          "as": "zero",
          "calculate": "0"
        },
        {
          "as": [
            "column",
            "pos"
          ],
          "fold": [
            "stagePos",
            "zero",
            "cumulativePos",
            "conversionPos"
          ]
        },
        {
          "from": {
            "key": "column",
            "data": {
              "values": [
                {
                  "dx": 4,
                  "align": "left",
                  "column": "stagePos",
                  "caption": "Stage"
                },
                {
                  "dx": -4,
                  "align": "right",
                  "column": "zero",
                  "caption": "Count"
                },
                {
                  "dx": 0,
                  "align": "center",
                  "column": "cumulativePos",
                  "caption": "Overall"
                },
                {
                  "dx": 0,
                  "align": "center",
                  "column": "conversionPos",
                  "caption": "Previous"
                }
              ]
            },
            "fields": [
              "caption",
              "align",
              "dx"
            ]
          },
          "lookup": "column"
        }
      ]
    }
  ],
  "width": "container",
  "height": "container",
  "encoding": {
    "y": {
      "axis": "",
      "type": "nominal",
      "field": "stage"
    }
  },
  "transform": [
    {
      "as": [
        "measurename",
        "count"
      ],
      "fold": [
        "users\\.count",
        "users\\.count_california_seniors",
        "users\\.count_minors",
        "users\\.count_california_minors"
      ]
    },
    {
      "from": {
        "key": "measurename",
        "data": {
          "values": [
            {
              "stage": "1. Users",
              "measurename": "users.count"
            },
            {
              "stage": "2. California ",
              "measurename": "users.count_california_seniors"
            },
            {
              "stage": "3. Minors",
              "measurename": "users.count_minors"
            },
            {
              "stage": "4. California Minors",
              "measurename": "users.count_california_minors"
            }
          ]
        },
        "fields": [
          "stage"
        ]
      },
      "lookup": "measurename"
    },
    {
      "joinaggregate": [
        {
          "as": "maxCount",
          "op": "max",
          "field": "count"
        }
      ]
    },
    {
      "sort": [
        {
          "field": "stage",
          "order": "ascending"
        }
      ],
      "window": [
        {
          "as": "previousCount",
          "op": "lag",
          "field": "count"
        }
      ]
    },
    {
      "as": "cumulativePct",
      "calculate": "datum.count / datum.maxCount"
    },
    {
      "as": "conversionPct",
      "calculate": "datum.count / datum.previousCount"
    },
    {
      "as": "countPos",
      "calculate": "datum.maxCount * 0.5"
    },
    {
      "as": "cumulativePos",
      "calculate": "datum.maxCount * 0.08"
    },
    {
      "as": "conversionPos",
      "calculate": "datum.maxCount * 0.16"
    },
    {
      "as": "stagePos",
      "calculate": "datum.maxCount * -1.2"
    },
    {
      "as": "negCount",
      "calculate": "-datum.count"
    },
    {
      "as": "labelLeft",
      "calculate": "datum.count < 0.1 * datum.maxCount"
    }
  ]
}
```

### Centered funnel

<img alt="" />

#### Funnel with currency

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": "bar",
      "encoding": {
        "x": {
          "axis": false,
          "type": "quantitative",
          "field": "AMOUNT",
          "stack": "center"
        },
        "color": {
          "type": "nominal",
          "field": "COLOR",
          "legend": null
        }
      }
    },
    {
      "layer": [
        {
          "mark": {
            "dx": 0,
            "type": "text",
            "align": "right"
          },
          "encoding": {
            "text": {
              "type": "quantitative",
              "field": "AMOUNT",
              "format": "USDCURRENCY",
              "formatType": "omniNumberFormat"
            }
          }
        },
        {
          "mark": {
            "dx": 10,
            "type": "text",
            "align": "left"
          },
          "encoding": {
            "text": {
              "type": "quantitative",
              "field": "PERCENT",
              "format": "PERCENT",
              "formatType": "omniNumberFormat",
              "condition": {
                "test": "datum['PERCENT'] > 1",
                "value": "N/A"
              }
            }
          }
        }
      ]
    }
  ],
  "transform": [
    {
      "as": "COLOR",
      "calculate": "datum['events.event_type']"
    },
    {
      "as": "AMOUNT",
      "calculate": "datum['events.count']"
    },
    {
      "window": [
        {
          "field": "AMOUNT",
          "op": "lag",
          "as": "PREVIOUS_AMOUNT"
        }
      ]
    },
    {
      "as": "PERCENT",
      "calculate": "datum.AMOUNT/datum.PREVIOUS_AMOUNT"
    }
  ],
  "width": "container",
  "height": "container",
  "encoding": {
    "y": {
      "axis": {
        "title": false
      },
      "sort": null,
      "type": "nominal",
      "field": "events\\.event_type"
    }
  }
}
```

#### Funnel with a dimension and a measure

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": "bar",
      "encoding": {
        "x": {
          "axis": false,
          "type": "quantitative",
          "field": "events\\.count",
          "stack": "center"
        },
        "color": {
          "type": "nominal",
          "field": "events\\.event_type",
          "legend": null
        }
      }
    },
    {
      "layer": [
        {
          "mark": {
            "dx": 0,
            "type": "text",
            "align": "right"
          },
          "encoding": {
            "text": {
              "type": "quantitative",
              "field": "events\\.count",
              "formatType": "omniNumberFormat"
            }
          }
        },
        {
          "mark": {
            "dx": 10,
            "type": "text",
            "align": "left"
          },
          "encoding": {
            "text": {
              "type": "nominal",
              "field": "phase"
            }
          },
          "transform": [
            {
              "as": "phase",
              "calculate": "datum.calc_1 + '%'"
            }
          ]
        }
      ]
    }
  ],
  "width": "container",
  "height": "container",
  "encoding": {
    "y": {
      "axis": {
        "title": false
      },
      "sort": null,
      "type": "nominal",
      "field": "events\\.event_type"
    }
  }
}
```

#### Funnel with three measures

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": "bar",
      "encoding": {
        "x": {
          "axis": false,
          "type": "quantitative",
          "field": "measure_value",
          "stack": "center"
        },
        "color": {
          "type": "nominal",
          "field": "measure_name",
          "legend": null
        }
      }
    },
    {
      "layer": [
        {
          "mark": {
            "dx": 0,
            "type": "text",
            "align": "right"
          },
          "encoding": {
            "text": {
              "type": "quantitative",
              "field": "measure_value",
              "formatType": "omniNumberFormat"
            }
          }
        },
        {
          "mark": {
            "dx": 10,
            "type": "text",
            "align": "left"
          },
          "encoding": {
            "text": {
              "type": "nominal",
              "field": "phase"
            }
          },
          "transform": [
            {
              "as": "phase",
              "calculate": "datum.calc_1 + '%'"
            }
          ]
        }
      ]
    }
  ],
  "width": "container",
  "height": "container",
  "encoding": {
    "y": {
      "axis": {
        "title": false
      },
      "sort": null,
      "type": "nominal",
      "field": "measure_name"
    }
  }
}
```

### Gantt (timeline) chart

This chart takes advantage of `x`, `x2` in Vega to create a start and end point for bars along a timeline for each user. It also includes config to improve the axis labels. Color could be included in an additional facet, using one more dimension to group different users together.

<img alt="" />

**Query fields:**

* `users.full_name`
* `users.created_at[date]`
* `order_items.created_at[date]`

```json expandable title="Visualization code" theme={null}
{
  "mark": "bar",
  "encoding": {
    "y": {
      "field": "DIM",
      "type": "ordinal",
      "axis": {
        "title": "Name"
      }
    },
    "x": {
      "field": "START",
      "type": "temporal",
      "axis": {
        "title": "Date"
      }
    },
    "x2": {
      "field": "END",
      "type": "temporal"
    }
  },
  "transform": [
    {
      "as": "DIM",
      "calculate": "datum['users.full_name']"
    },
    {
      "as": "START",
      "calculate": "datum['users.created_at[date]']"
    },
    {
      "as": "END",
      "calculate": "datum['order_items.created_at[date]']"
    }
  ]
}
```

### Isotope (stacked icons)

Unlike other charts, this chart requires the full granularity in the dataset to create the stacked icons. The core technique is to map the repeated values into icons and then stack them. **Note**: In this example, `users.id` is included in order to create one entry per row.

<img alt="" />

**Query fields:**

* `users.email_domain`
* `users.id`

```json expandable title="Visualization code" theme={null}
{
  "mark": {
    "type": "text",
    "baseline": "middle"
  },
  "width": "container",
  "config": {
    "view": {
      "stroke": ""
    }
  },
  "height": "container",
  "encoding": {
    "x": {
      "axis": null,
      "type": "ordinal",
      "field": "rank"
    },
    "y": {
      "type": "nominal",
      "field": "DIM",
      "title": null
    },
    "size": {
      "value": 40
    },
    "text": {
      "type": "nominal",
      "field": "emoji"
    }
  },
  "transform": [
    {
      "as": "DIM",
      "calculate": "datum['users\\.traffic_source']"
    },
    {
      "as": "COUNTER",
      "calculate": "datum['users.id']"
    },
    {
      "as": "emoji",
      "calculate": "{'Search': '\ud83d\udc04', 'Display': '\ud83d\udc0f', 'Organic': '\ud83d\udc16', 'Facebook': '\ud83d\udc22', 'Email': '\ud83d\udc22'}[datum.DIM]]"
    },
    {
      "window": [
        {
          "as": "rank",
          "op": "rank"
        }
      ],
      "groupby": [
        "DIM"
      ]
    }
  ]
}
```

### Gauge

A gauge chart resembles a speedometer or dial and is typically used to display a single value within a predefined range. This visualization is useful for evaluating progress against a goal.

<img alt="" />

**Example dataset**:

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": {
        "type": "arc",
        "color": "lightgrey",
        "theta": {
          "expr": "datum['_arc_start_radians']"
        },
        "radius": {
          "expr": "ring1_outer"
        },
        "theta2": {
          "expr": "datum['_arc_end_radians']"
        },
        "radius2": {
          "expr": "ring1_inner"
        },
        "cornerRadius": 10
      }
    },
    {
      "mark": {
        "type": "arc",
        "theta": {
          "expr": "datum['_ring_start_radians']"
        },
        "radius": {
          "expr": "ring1_outer"
        },
        "theta2": {
          "expr": "datum['_ring_end_radians']"
        },
        "radius2": {
          "expr": "ring1_inner"
        },
        "cornerRadius": 10
      },
      "name": "RING",
      "encoding": {
        "color": {
          "value": "#307E31",
          "condition": [
            {
              "test": "datum['ratio'] < 0.33",
              "value": "#880808"
            },
            {
              "test": "datum['ratio'] < 0.66",
              "value": "#E49B0F"
            }
          ]
        }
      }
    },
    {
      "mark": {
        "type": "text",
        "fontSize": 40
      },
      "encoding": {
        "text": {
          "field": "users\\.count",
          "format": "number",
          "formatType": "omniNumberFormat"
        },
        "color": {
          "value": "#307E31",
          "condition": [
            {
              "test": "datum['ratio'] < 0.33",
              "value": "#880808"
            },
            {
              "test": "datum['ratio'] < 0.66",
              "value": "#E49B0F"
            }
          ]
        }
      }
    }
  ],
  "width": "container",
  "config": {
    "concat": {
      "spacing": 0
    },
    "autosize": {
      "type": "fit",
      "resize": true,
      "contains": "padding"
    }
  },
  "height": "container",
  "params": [
    {
      "name": "ring_max",
      "value": 160
    },
    {
      "name": "ring_width",
      "value": 20
    },
    {
      "name": "ring_gap",
      "value": 5
    },
    {
      "name": "label_color",
      "value": "#000000"
    },
    {
      "name": "ring_background_opacity",
      "value": 0.3
    },
    {
      "name": "ring0_percent",
      "value": 100
    },
    {
      "expr": "ring_max+2",
      "name": "ring0_outer"
    },
    {
      "expr": "ring_max+1",
      "name": "ring0_inner"
    },
    {
      "expr": "ring0_inner-ring_gap",
      "name": "ring1_outer"
    },
    {
      "expr": "ring1_outer-ring_width",
      "name": "ring1_inner"
    },
    {
      "expr": "(ring1_outer+ring1_inner)/2",
      "name": "ring1_middle"
    },
    {
      "expr": "220",
      "name": "arc_size"
    }
  ],
  "transform": [
    {
      "as": "ratio",
      "calculate": "datum['users\\.count'] / ( datum['calc_1'] )"
    },
    {
      "as": "_arc_start_degrees",
      "calculate": "360 - ( arc_size / 2 )"
    },
    {
      "as": "_arc_end_degrees",
      "calculate": "0 + ( arc_size / 2 )"
    },
    {
      "as": "_arc_start_radians",
      "calculate": "2 * 3.14 * ( datum['_arc_start_degrees'] - 360 ) / 360"
    },
    {
      "as": "_arc_end_radians",
      "calculate": "2 * 3.14 * datum['_arc_end_degrees'] / 360"
    },
    {
      "as": "_arc_total_radians",
      "calculate": "datum['_arc_end_radians'] - datum['_arc_start_radians']"
    },
    {
      "as": "_ring_start_radians",
      "calculate": "datum['_arc_start_radians']"
    },
    {
      "as": "_ring_end_radians",
      "calculate": "datum['_arc_start_radians'] + ( datum['_arc_total_radians'] * datum['ratio'] )"
    }
  ]
}
```

### Sunburst chart

Sunburst charts display hierarchical data in an easy-to-read way. Each ring represents a level in the hierarchy, and the size of each section conveys its proportion in comparison to the whole.

In this example, the inner slices are colored by order.

<img alt="" />

**Query fields**:

* `users.gender`
* `users.traffic_source`
* `users.count`

**Example dataset**:

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": {
        "type": "arc",
        "tooltip": true,
        "innerRadius": {
          "expr": "min(width, height)/9"
        },
        "outerRadius": {
          "expr": "min(width, height)/3"
        }
      },
      "encoding": {
        "color": {
          "sort": "ascending",
          "type": "ordinal",
          "field": "OUT_IN",
          "scale": {
            "range": [
              "#1DF9B9",
              "#1DE5B9",
              "#1DD1B9",
              "#1DBDB9",
              "#1DA9B9",
              "#3DF23B",
              "#3DDA3B",
              "#3DC23B",
              "#3DAA3B",
              "#3D923B"
            ]
          },
          "title": "Inner Grouping"
        },
        "order": {
          "sort": "ascending",
          "field": "OUT_IN"
        },
        "theta": {
          "type": "quantitative",
          "field": "SIZE",
          "stack": true
        },
        "tooltip": [
          {
            "type": "nominal",
            "field": "OUTSIDE",
            "title": [
              "Outer Grouping"
            ]
          },
          {
            "type": "nominal",
            "field": "INSIDE",
            "title": [
              "Inner Grouping"
            ]
          },
          {
            "type": "quantitative",
            "field": "SIZE",
            "title": [
              "Count"
            ],
            "format": "NUMBER",
            "formatType": "omniNumberFormat"
          }
        ]
      }
    },
    {
      "mark": {
        "type": "arc",
        "tooltip": true,
        "innerRadius": {
          "expr": "min(width, height)/3"
        }
      },
      "encoding": {
        "color": {
          "sort": "ascending",
          "type": "ordinal",
          "field": "OUTSIDE",
          "scale": {
            "range": [
              "#1DD1B9",
              "#3DC23B"
            ]
          },
          "title": "Outer Grouping"
        },
        "order": {
          "sort": "ascending",
          "field": "OUTSIDE"
        },
        "theta": {
          "sort": "ascending",
          "type": "quantitative",
          "field": "total_users",
          "stack": true,
          "title": [
            "Users Count"
          ]
        },
        "tooltip": [
          {
            "type": "nominal",
            "field": "OUTSIDE",
            "title": [
              "Outer Grouping"
            ]
          },
          {
            "type": "quantitative",
            "field": "total_users",
            "title": [
              "Count"
            ],
            "format": "NUMBER",
            "formatType": "omniNumberFormat"
          }
        ]
      },
      "transform": [
        {
          "groupby": [
            "OUTSIDE"
          ],
          "aggregate": [
            {
              "as": "total_users",
              "op": "sum",
              "field": "SIZE"
            }
          ]
        }
      ]
    }
  ],
  "transform": [
    {
      "as": "OUTSIDE",
      "calculate": "datum['users.gender']"
    },
    {
      "as": "INSIDE",
      "calculate": "datum['users.traffic_source']"
    },
    {
      "as": "OUT_IN",
      "calculate": "datum.OUTSIDE + '-' + datum.INSIDE"
    },
    {
      "as": "SIZE",
      "calculate": "datum['users.count']"
    }
  ],
  "resolve": {
    "scale": {
      "color": "independent"
    },
    "legend": {
      "color": "independent"
    }
  }
}
```

### Trellis / Small Multiples / Faceted Charts

Trellis charts allow you to show a grid of smaller charts, one for each category.

<img alt="" />

To use this example, update the following values in the custom visualization code:

* `DIM` to be the x-axis value in your query
* `AMOUNT` as the y-axis value in your query
* `FACET` to be the grouping field
* `COLOR` for the mark color

You can also adjust the mark type, the width and height of each small chart, and the number of columns to draw.

**Example result set:**

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "mark": {
    "type": "line",
    "tooltip": true
  },
  "width": 200,
  "height": 50,
  "resolve": {
    "scale": {
      "x": "shared",
      "y": "independent"
    }
  },
  "encoding": {
    "x": {
      "axis": {
        "title": null,
        "format": "%b %-d, %Y",
        "formatType": "omniTimestampFormat",
        "labelOverlap": true
      },
      "sort": "ascending",
      "type": "ordinal",
      "field": "DIM",
      "title": "Date",
      "timeUnit": "utcyearmonthdate"
    },
    "y": {
      "axis": {
        "format": "bigusdcurrency_0",
        "orient": "left",
        "formatType": "omniNumberFormat",
        "labelOverlap": true
      },
      "type": "quantitative",
      "field": "AMOUNT",
      "title": "Total Sales",
      "format": "bigusdcurrency_2",
      "formatType": "omniNumberFormat"
    },
    "color": {
      "field": "COLOR",
      "title": "Category",
      "legend": null
    },
    "facet": {
      "sort": "ascending",
      "type": "ordinal",
      "field": "FACET",
      "title": null,
      "columns": 4
    }
  },
  "transform": [
    {
      "as": "DIM",
      "calculate": "datum['omni_dbt_ecomm__order_items.created_at[week]']"
    },
    {
      "as": "AMOUNT",
      "calculate": "datum['omni_dbt_ecomm__order_items.total_sale_price']"
    },
    {
      "as": "FACET",
      "calculate": "datum['omni_dbt_ecomm__products.category']"
    },
    {
      "as": "COLOR",
      "calculate": "datum['omni_dbt_ecomm__products.category']"
    }
  ]
}
```

### Word cloud

Word clouds are an eye-catching way to visualize text data by showing the most common words in a dataset. The more frequently a word appears, the bigger and bolder it is, which makes it easy to spot key themes at a glance.

<img alt="" />

To use this example, change the following values in the custom visualization code:

* `field` values should match the values in the table
* Adjust the `range` to fit your query
* Adjust the `domain` to fit your query

```sql title="Example query" theme={null}
SELECT category,
       COUNT(*) AS frequency,
       RANDOM() * (0.9 - 0.1) + 0.1 AS height,
       RANDOM() AS width
FROM productsGROUP BY 1ORDER BY 2 DESC
LIMIT 25;
```

**Example dataset**:

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "mark": "text",
  "width": "container",
  "height": "container",
  "transform": [
    {
      "as": "DIM",
      "calculate": "datum['category']"
    },
    {
      "as": "SIZE",
      "calculate": "datum['frequency']"
    },
    {
      "as": "COLOR",
      "calculate": "datum['department']"
    },
    {
      "as": "X",
      "calculate": "random() * (0.9 - 0.1) + 0.1"
    },
    {
      "as": "Y",
      "calculate": "random()"
    }
  ],
  "encoding": {
    "x": {
      "axis": null,
      "field": "X"
    },
    "y": {
      "axis": null,
      "field": "Y"
    },
    "size": {
      "field": "SIZE",
      "legend": null
    },
    "text": {
      "field": "DIM"
    },
    "color": {
      "field": "COLOR",
      "scale": {
        "scheme": "tableau20"
      },
      "legend": null
    }
  }
}
```

### Scatter Plot with Color Quadrants

Being able to show a scatter plot of values in and showing where they land within specific designated quadrants and above certain thresholds with the easy deliantion of different colors, makes it easily to see where each value lands at a glance.

<img alt="" />

To use this example, change the following values in the custom visualization code:

* `calc_1` `calc_2` `calc_3` `calc_4` set the values for your four quadrants, these can also be hard-coded or referenced from calculated fields as noted in the example
* Adjust the `users.age` to fit your query
* Adjust the `users.count` to fit your query

```sql title="Example query" theme={null}
SELECT users.age,
       users.count,
       calc_1,
       calc_2,
       calc_3,
       calc_4
FROM users
```

**Example dataset**:

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "layer": [
        {
          "mark": {
            "line": false,
            "type": "area",
            "tooltip": false
          },
          "encoding": {
            "y": {
              "type": "quantitative",
              "field": "calc_2"
            },
            "color": {
              "value": "red"
            }
          }
        },
        {
          "mark": {
            "line": false,
            "type": "area",
            "tooltip": false
          },
          "encoding": {
            "y": {
              "type": "quantitative",
              "field": "calc_3"
            },
            "color": {
              "value": "lightblue"
            }
          }
        },
        {
          "mark": {
            "line": false,
            "type": "area",
            "tooltip": false
          },
          "encoding": {
            "y": {
              "type": "quantitative",
              "field": "calc_1"
            },
            "y2": {
              "type": "quantitative",
              "field": "calc_2"
            },
            "color": {
              "value": "green"
            }
          }
        },
        {
          "mark": {
            "line": false,
            "type": "area",
            "tooltip": false
          },
          "encoding": {
            "y": {
              "type": "quantitative",
              "field": "calc_4"
            },
            "y2": {
              "type": "quantitative",
              "field": "calc_3"
            },
            "color": {
              "value": "purple"
            }
          }
        },
        {
          "mark": {
            "type": "point",
            "tooltip": true
          },
          "encoding": {
            "y": {
              "axis": {
                "title": "Users Count + (1)",
                "format": "NUMBER_0",
                "orient": "left",
                "formatType": "omniNumberFormat",
                "labelOverlap": true
              },
              "type": "quantitative",
              "field": "users\\.count",
              "title": "Users Count"
            },
            "color": {
              "datum": "Users Count"
            },
            "tooltip": [
              {
                "type": "quantitative",
                "field": "users\\.age",
                "title": "Age"
              },
              {
                "type": "quantitative",
                "field": "users\\.count",
                "title": "Users Count",
                "format": "NUMBER_0",
                "formatType": "omniNumberFormat"
              },
              {
                "type": "quantitative",
                "field": "users\\.age_max",
                "title": "Age Max"
              }
            ]
          }
        }
      ]
    },
    {
      "mark": {
        "type": "rule",
        "tooltip": true,
        "strokeDash": [
          4,
          2
        ]
      },
      "params": [
        {
          "name": "hover",
          "select": {
            "on": "mouseover",
            "type": "point",
            "clear": "mouseout",
            "nearest": true
          }
        }
      ],
      "encoding": {
        "opacity": {
          "value": 0,
          "condition": {
            "test": {
              "empty": false,
              "param": "hover"
            },
            "value": 1
          }
        },
        "tooltip": [
          {
            "type": "quantitative",
            "field": "users\\.age",
            "title": "Age"
          },
          {
            "type": "quantitative",
            "field": "users\\.count",
            "title": "Users Count",
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          }
        ]
      }
    }
  ],
  "width": "container",
  "height": "container",
  "encoding": {
    "x": {
      "axis": {
        "title": "Age",
        "labelOverlap": true
      },
      "sort": "ascending",
      "type": "ordinal",
      "field": "users\\.age",
      "title": "Age"
    },
    "color": {
      "scale": {
        "domain": [
          "Users Count",
          "Age Max"
        ],
        "scheme": "omni"
      },
      "legend": null
    }
  }
}
```

### Bullet charts

Bullet charts are used to track a metric against a target. A bar is used to measure the actual value of the metric, a vertical line or marker for the target, and background bands for adding qualitative ranges.

#### Single bullet chart

<img alt="" />

**Example dataset**

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": "bar",
      "params": [
        {
          "bind": "legend",
          "name": "omni_click",
          "select": {
            "type": "point",
            "fields": [
              "omni__measure_name"
            ]
          }
        }
      ],
      "encoding": {
        "color": {
          "field": "omni__measure_name"
        },
        "opacity": {
          "value": 0
        }
      }
    },
    {
      "layer": [
        {
          "layer": [
            {
              "mark": {
                "type": "bar",
                "tooltip": true
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Pace"
                    ]
                  }
                }
              ]
            },
            {
              "mark": {
                "type": "bar",
                "height": 7,
                "tooltip": true
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Current"
                    ]
                  }
                }
              ]
            },
            {
              "mark": {
                "type": "tick",
                "tooltip": true,
                "thickness": 3
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Target"
                    ]
                  }
                }
              ]
            }
          ],
          "encoding": {
            "x": {
              "axis": {
                "title": "Target",
                "format": "NUMBER_0",
                "orient": "bottom",
                "formatType": "omniNumberFormat",
                "labelOverlap": true
              },
              "type": "quantitative",
              "field": "omni__measure_value",
              "stack": null,
              "title": "Target + (2)"
            },
            "color": {
              "scale": {
                "range": [
                  "#000000ff",
                  "#bcbcbcff",
                  "#A66BBF"
                ],
                "domain": [
                  "Target",
                  "Pace",
                  "Current"
                ]
              }
            },
            "order": {
              "sort": "descending",
              "type": "quantitative",
              "field": "omni__key_order"
            }
          },
          "transform": [
            {
              "filter": {
                "field": "omni__measure_name",
                "oneOf": [
                  "Target",
                  "Pace",
                  "Current"
                ]
              }
            }
          ]
        }
      ],
      "encoding": {
        "y": {
          "axis": {
            "title": null,
            "labelOverlap": true
          },
          "type": "ordinal",
          "field": "CATEGORICAL",
          "title": [
            "Category"
          ]
        },
        "tooltip": [
          {
            "type": "nominal",
            "field": "CATEGORICAL",
            "title": [
              "Category"
            ]
          },
          {
            "type": "quantitative",
            "field": "CURRENT",
            "title": [
              "Current"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "type": "quantitative",
            "field": "PACE",
            "title": [
              "Pace"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "type": "quantitative",
            "field": "TARGET",
            "title": [
              "Target"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          }
        ]
      },
      "transform": [
        {
          "as": [
            "omni__measure_name",
            "omni__measure_value"
          ],
          "fold": [
            "TARGET",
            "PACE",
            "CURRENT"
          ]
        },
        {
          "as": "omni__measure_name",
          "calculate": "{\"TARGET\":\"Target\",\"PACE\":\"Pace\",\"CURRENT\":\"Current\"}[datum.omni__measure_name]"
        },
        {
          "as": "omni__key_order",
          "calculate": "indexof([\"Target\",\"Pace\",\"Current\"], datum.omni__measure_name)"
        },
        {
          "filter": {
            "param": "omni_click"
          }
        }
      ]
    }
  ],
  "width": "container",
  "height": "container",
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "transform": [
    {
      "as": "TARGET",
      "calculate": "datum['products.count']"
    },
    {
      "as": "PACE",
      "calculate": "datum['calc_2']"
    },
    {
      "as": "CURRENT",
      "calculate": "datum['calc_1']"
    },
    {
      "as": "CATEGORICAL",
      "calculate": "datum['calc_3']"
    }
  ]
}
```

#### Multiple categories

Same as the single bullet, just repeated across the categories.

<img alt="" />

**Example dataset**

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": "bar",
      "params": [
        {
          "bind": "legend",
          "name": "omni_click",
          "select": {
            "type": "point",
            "fields": [
              "omni__measure_name"
            ]
          }
        }
      ],
      "encoding": {
        "color": {
          "field": "omni__measure_name"
        },
        "opacity": {
          "value": 0
        }
      }
    },
    {
      "layer": [
        {
          "layer": [
            {
              "mark": {
                "type": "bar",
                "tooltip": true
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Pace"
                    ]
                  }
                }
              ]
            },
            {
              "mark": {
                "type": "bar",
                "height": 7,
                "tooltip": true
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Current"
                    ]
                  }
                }
              ]
            },
            {
              "mark": {
                "type": "tick",
                "tooltip": true,
                "thickness": 3
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Target"
                    ]
                  }
                }
              ]
            }
          ],
          "encoding": {
            "x": {
              "axis": {
                "title": "Target",
                "format": "NUMBER_0",
                "orient": "bottom",
                "formatType": "omniNumberFormat",
                "labelOverlap": true
              },
              "type": "quantitative",
              "field": "omni__measure_value",
              "stack": null,
              "title": "Target + (2)"
            },
            "color": {
              "scale": {
                "range": [
                  "#000000ff",
                  "#bcbcbcff",
                  "#A66BBF"
                ],
                "domain": [
                  "Target",
                  "Pace",
                  "Current"
                ]
              }
            },
            "order": {
              "sort": "descending",
              "type": "quantitative",
              "field": "omni__key_order"
            }
          },
          "transform": [
            {
              "filter": {
                "field": "omni__measure_name",
                "oneOf": [
                  "Target",
                  "Pace",
                  "Current"
                ]
              }
            }
          ]
        }
      ],
      "encoding": {
        "y": {
          "axis": {
            "title": null,
            "labelOverlap": true
          },
          "type": "ordinal",
          "field": "CATEGORICAL",
          "title": [
            "Category"
          ]
        },
        "tooltip": [
          {
            "type": "nominal",
            "field": "CATEGORICAL",
            "title": [
              "Category"
            ]
          },
          {
            "type": "quantitative",
            "field": "CURRENT",
            "title": [
              "Current"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "type": "quantitative",
            "field": "PACE",
            "title": [
              "Pace"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "type": "quantitative",
            "field": "TARGET",
            "title": [
              "Target"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          }
        ]
      },
      "transform": [
        {
          "as": [
            "omni__measure_name",
            "omni__measure_value"
          ],
          "fold": [
            "TARGET",
            "PACE",
            "CURRENT"
          ]
        },
        {
          "as": "omni__measure_name",
          "calculate": "{\"TARGET\":\"Target\",\"PACE\":\"Pace\",\"CURRENT\":\"Current\"}[datum.omni__measure_name]"
        },
        {
          "as": "omni__key_order",
          "calculate": "indexof([\"Target\",\"Pace\",\"Current\"], datum.omni__measure_name)"
        },
        {
          "filter": {
            "param": "omni_click"
          }
        }
      ]
    }
  ],
  "width": "container",
  "height": "container",
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "transform": [
    {
      "as": "TARGET",
      "calculate": "datum['products.count']"
    },
    {
      "as": "PACE",
      "calculate": "datum['calc_2']"
    },
    {
      "as": "CURRENT",
      "calculate": "datum['calc_1']"
    },
    {
      "as": "CATEGORICAL",
      "calculate": "datum['products.category']"
    }
  ]
}
```

#### Multiple categories with conditional coloring

Using the same result set as the multiple categories, the bars are colored by whether they are above or below the pacing.

<img alt="" />

**Example dataset**

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "layer": [
    {
      "mark": "bar",
      "params": [
        {
          "bind": "legend",
          "name": "omni_click",
          "select": {
            "type": "point",
            "fields": [
              "omni__measure_name"
            ]
          }
        }
      ],
      "encoding": {
        "color": {
          "field": "omni__measure_name"
        },
        "opacity": {
          "value": 0
        }
      }
    },
    {
      "layer": [
        {
          "layer": [
            {
              "mark": {
                "type": "bar",
                "tooltip": true
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Pace"
                    ]
                  }
                }
              ]
            },
            {
              "mark": {
                "type": "bar",
                "height": 7
              },
              "encoding": {
                "color": {
                  "value": "darkred",
                  "condition": {
                    "test": "datum.ON_PACE == true",
                    "value": "darkgreen"
                  }
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Current"
                    ]
                  }
                }
              ]
            },
            {
              "mark": {
                "type": "tick",
                "tooltip": true,
                "thickness": 3
              },
              "encoding": {
                "color": {
                  "field": "omni__measure_name",
                  "legend": null
                }
              },
              "transform": [
                {
                  "filter": {
                    "field": "omni__measure_name",
                    "oneOf": [
                      "Target"
                    ]
                  }
                }
              ]
            }
          ],
          "encoding": {
            "x": {
              "axis": {
                "title": "Target",
                "format": "NUMBER_0",
                "orient": "bottom",
                "formatType": "omniNumberFormat",
                "labelOverlap": true
              },
              "type": "quantitative",
              "field": "omni__measure_value",
              "stack": null,
              "title": "Target + (2)"
            },
            "color": {
              "scale": {
                "range": [
                  "#000000ff",
                  "#bcbcbcff",
                  "#A66BBF",
                  "#b50000ff"
                ],
                "domain": [
                  "Target",
                  "Pace",
                  "Current",
                  "On Pace"
                ]
              }
            },
            "order": {
              "sort": "descending",
              "type": "quantitative",
              "field": "omni__key_order"
            }
          },
          "transform": [
            {
              "filter": {
                "field": "omni__measure_name",
                "oneOf": [
                  "Target",
                  "Pace",
                  "Current"
                ]
              }
            }
          ]
        }
      ],
      "encoding": {
        "y": {
          "axis": {
            "title": null,
            "labelOverlap": true
          },
          "type": "ordinal",
          "field": "CATEGORICAL",
          "title": [
            "Category"
          ]
        },
        "tooltip": [
          {
            "type": "nominal",
            "field": "CATEGORICAL",
            "title": [
              "Category"
            ]
          },
          {
            "type": "quantitative",
            "field": "CURRENT",
            "title": [
              "Current"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "type": "quantitative",
            "field": "PACE",
            "title": [
              "Pace"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "type": "quantitative",
            "field": "TARGET",
            "title": [
              "Target"
            ],
            "format": "NUMBER_0",
            "formatType": "omniNumberFormat"
          },
          {
            "field": "ON_PACE"
          }
        ]
      },
      "transform": [
        {
          "as": [
            "omni__measure_name",
            "omni__measure_value"
          ],
          "fold": [
            "TARGET",
            "PACE",
            "CURRENT",
            "ON_PACE"
          ]
        },
        {
          "as": "omni__measure_name",
          "calculate": "{\"TARGET\":\"Target\",\"PACE\":\"Pace\",\"CURRENT\":\"Current\",\"ON_PACE\":\"On Pace\"}[datum.omni__measure_name]"
        },
        {
          "as": "omni__key_order",
          "calculate": "indexof([\"Target\",\"Pace\",\"Current\",\"On Pace\"], datum.omni__measure_name)"
        },
        {
          "filter": {
            "param": "omni_click"
          }
        }
      ]
    }
  ],
  "width": "container",
  "height": "container",
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "transform": [
    {
      "as": "TARGET",
      "calculate": "datum['products.count']"
    },
    {
      "as": "PACE",
      "calculate": "datum['calc_2']"
    },
    {
      "as": "CURRENT",
      "calculate": "datum['calc_1']"
    },
    {
      "as": "CATEGORICAL",
      "calculate": "datum['products.category']"
    },
    {
      "as": "ON_PACE",
      "calculate": "datum.CURRENT > datum.PACE"
    }
  ]
}
```

#### Bullet chart inside a table

Additional detail per column, row banding, conditional coloring and sizing. Fancy!

<img alt="" />

**Example dataset**:

<img alt="" />

```json expandable title="Visualization code" theme={null}
{
  "data": {
    "name": "bullet_chart_data"
  },
  "width": 640,
  "config": {
    "bar": {
      "binSpacing": 10
    },
    "axis": {
      "grid": false
    },
    "view": {
      "stroke": null
    }
  },
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "vconcat": [
    {
      "height": 40,
      "hconcat": [
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "width": 120,
          "encoding": {
            "x": {
              "value": 60
            },
            "y": {
              "value": 20
            },
            "text": {
              "value": "Campaign"
            },
            "color": {
              "value": "#1a7e83"
            }
          }
        },
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "width": 60,
          "encoding": {
            "x": {
              "value": 30
            },
            "y": {
              "value": 20
            },
            "text": {
              "value": "Length"
            },
            "color": {
              "value": "#1a7e83"
            }
          }
        },
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "width": 80,
          "encoding": {
            "x": {
              "value": 40
            },
            "y": {
              "value": 20
            },
            "text": {
              "value": "Flight"
            },
            "color": {
              "value": "#1a7e83"
            }
          }
        },
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "width": 360,
          "encoding": {
            "x": {
              "value": 180
            },
            "y": {
              "value": 20
            },
            "text": {
              "value": ""
            },
            "color": {
              "value": "#1a7e83"
            }
          }
        }
      ],
      "spacing": 0
    },
    {
      "layer": [
        {
          "mark": "rect",
          "encoding": {
            "x": {
              "value": 0
            },
            "y": {
              "axis": null,
              "sort": "ascending",
              "type": "ordinal",
              "field": "row_id"
            },
            "x2": {
              "value": 660
            },
            "color": {
              "type": "nominal",
              "field": "is_even_row",
              "scale": {
                "range": [
                  "#f5f5f5",
                  "white"
                ]
              },
              "legend": null
            }
          }
        },
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "encoding": {
            "x": {
              "value": 60
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            },
            "text": {
              "field": "campaign_display"
            }
          }
        },
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "encoding": {
            "x": {
              "value": 150
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            },
            "text": {
              "field": "bullet_chart_data\\.creative_length"
            }
          }
        },
        {
          "mark": {
            "type": "text",
            "align": "center",
            "baseline": "middle"
          },
          "encoding": {
            "x": {
              "value": 220
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            },
            "text": {
              "field": "bullet_chart_data\\.flight"
            }
          }
        },
        {
          "mark": {
            "size": 35,
            "type": "bar",
            "tooltip": true
          },
          "encoding": {
            "x": {
              "axis": null,
              "type": "quantitative",
              "field": "bullet_chart_data\\.goal",
              "scale": {
                "range": [
                  270,
                  620
                ]
              }
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            },
            "color": {
              "value": "#a0cfd2"
            }
          }
        },
        {
          "mark": {
            "size": 10,
            "type": "bar"
          },
          "encoding": {
            "x": {
              "type": "quantitative",
              "field": "bullet_chart_data\\.delivery__pacing_behind_",
              "scale": {
                "range": [
                  250,
                  620
                ]
              }
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            },
            "color": {
              "value": "#f97068"
            }
          }
        },
        {
          "mark": {
            "size": 20,
            "type": "bar"
          },
          "encoding": {
            "x": {
              "type": "quantitative",
              "field": "bullet_chart_data\\.delivery__pacing_ahead_",
              "scale": {
                "range": [
                  250,
                  620
                ]
              }
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            },
            "color": {
              "value": "#096184"
            }
          }
        },
        {
          "mark": {
            "type": "tick",
            "color": "#ffbb61",
            "orient": "vertical",
            "thickness": 4
          },
          "encoding": {
            "x": {
              "type": "quantitative",
              "field": "flight_marker",
              "scale": {
                "range": [
                  250,
                  620
                ]
              }
            },
            "y": {
              "axis": null,
              "type": "ordinal",
              "field": "row_id"
            }
          }
        },
        {
          "mark": {
            "dx": 5,
            "type": "text",
            "align": "left",
            "baseline": "middle"
          },
          "encoding": {
            "x": {
              "type": "quantitative",
              "field": "bullet_chart_data\\.goal",
              "scale": {
                "range": [
                  250,
                  620
                ]
              }
            },
            "y": {
              "axis": null,
              "sort": "ascending",
              "type": "ordinal",
              "field": "row_id"
            },
            "text": {
              "field": "pacing_percentage",
              "format": ".0%"
            }
          }
        }
      ],
      "height": 420
    }
  ],
  "transform": [
    {
      "sort": [
        {
          "field": "bullet_chart_data\\.campaign",
          "order": "ascending"
        },
        {
          "field": "bullet_chart_data\\.creative_length",
          "order": "ascending"
        }
      ],
      "window": [
        {
          "as": "row_id",
          "op": "row_number"
        },
        {
          "as": "prev_campaign",
          "op": "lag",
          "field": "bullet_chart_data\\.campaign"
        }
      ]
    },
    {
      "as": "campaign_display",
      "calculate": "datum['bullet_chart_data.campaign'] === datum.prev_campaign ? '' : datum['bullet_chart_data.campaign']"
    },
    {
      "sort": [
        {
          "field": "bullet_chart_data\\.campaign",
          "order": "ascending"
        }
      ],
      "window": [
        {
          "as": "campaign_band_group",
          "op": "dense_rank",
          "field": "bullet_chart_data\\.campaign"
        }
      ]
    },
    {
      "as": "is_even_row",
      "calculate": "datum.campaign_band_group % 2 === 0"
    },
    {
      "as": "flight_marker",
      "calculate": "datum['bullet_chart_data.goal'] * datum['bullet_chart_data.flight_completion__']"
    },
    {
      "as": "pacing_percentage",
      "calculate": "(datum['bullet_chart_data.delivery__pacing_behind_'] + datum['bullet_chart_data.delivery__pacing_ahead_']) / datum['bullet_chart_data.goal']"
    }
  ],
  "description": "Campaign table with suppressed duplicate campaign names and banded rows grouped by campaign."
}
```


# Funnel charts
Source: https://docs.omni.co/visualize-present/visualizations/types/funnel

Funnel charts visualize sequential stages in a process, showing conversion rates and drop-off between each step.

A funnel chart displays values across sequential stages, with each stage represented as a progressively narrower segment. The width of each segment corresponds to its value, making it easy to identify where drop-off occurs in a process.

<img alt="" />

<Tip>
  Recreate this chart in Omni by downloading the [sample data](https://github.com/exploreomni/doc-sample-data/blob/main/visualizations/funnel.csv) and then [uploading the CSV as a source table](/analyze-explore/data-input-csvs)!
</Tip>

## Use cases

Funnel charts are particularly useful for visualizing:

* Conversion funnels showing user progression through a workflow
* Sales pipelines tracking deals from lead to close
* Customer journey stages from awareness to purchase
* Application processes with multiple steps
* Any sequential process where you want to highlight drop-off between stages

## Data structure

Funnel charts require at least one dimension and one measure:

* **Stage** - The sequential steps in your process (dimension)
* **Value** - The count or value at each stage (measure)

The funnel chart option becomes available once you have the required fields in your query.

When setting up your query, keep the following in mind:

* Stages should be ordered sequentially to accurately represent the flow
* Values typically decrease at each stage, though this is not required
* Use measures that make sense to compare across stages (e.g., user count, deal value)

## Configuration

To view the configuration options for a funnel chart, open the **Chart options** panel in a workbook:

<img alt="" />

### Orientation and alignment

The **Orientation** setting controls how the funnel is displayed:

* **Vertical** - Stages arranged top to bottom with the widest segment at the top
* **Horizontal** - Stages arranged left to right with the widest segment on the left

And the **Alignment** setting controls the vertical positioning of the funnel:

* **Left** - Aligns the funnel to the left
* **Center** - Aligns the funnel in the center
* **Right** - Aligns the funnel to the right

### Gap spacing

The **Gap** setting controls the amount of whitespace (in pixels) between each stage in the funnel.

### Color

Funnel charts support standard color configuration options:

* Assign colors to individual stages
* Use color palettes for automatic coloring
* Apply [modeled colors](/visualize-present/visualizations/configuration/color#dimension-colors) when defined

When coloring by a continuous numeric field, you can pin gradient color scale values (minimum, midpoint, and maximum) instead of using automatic data ranges. See [Gradient color scale values](/visualize-present/visualizations/configuration/color#gradient-color-scale-values) for more information.

### Labels

Toggle data labels to display stage names and values on the chart.

Access the following label options by clicking the <Icon icon="sliders" /> icon above the **Color and legend** and **Value** sections. Click the **Data labels** checkbox to enable label visibility, which will display some label configuration options:

<img alt="" />

* **Position** - Where labels appear relative to each segment. Available positions depend on the funnel orientation:
  * **Horizontal** - Top, bottom, or middle
  * **Vertical** - Left, right, or middle
* **Font styling** - Adjust the label text size, color, and styling (bold, italic)
* **Format** - Number formatting options, such as currency or percentage and decimal places
* **% change** - Display a conversion percentage alongside each label. Options include:
  * **None** - No percentage will display
  * **Percent of first** - Each stage's value as a percentage of the first stage
  * **Percent of previous** - Each stage's value as a percentage of the preceding stage
* **% change format** - Control how many decimal places appear in the percentage value

### Tooltips

Tooltips appear when hovering over funnel segments and display information about each stage. By default, tooltips show both the percent of first and percent of previous stage values for each segment. You can format or hide these values individually.

Use the [tooltip configuration](/visualize-present/visualizations/configuration/tooltips) to further customize what information appears and add additional fields.

## Next steps

* Learn more about [color configuration](/visualize-present/visualizations/configuration/color)
* Explore [tooltip customization](/visualize-present/visualizations/configuration/tooltips)
* Review other [chart types](/visualize-present/visualizations/types/index)


# Heatmap Charts
Source: https://docs.omni.co/visualize-present/visualizations/types/heatmap

Create heatmap visualizations in Omni to display data density and patterns using color gradients across two-dimensional grids.

## Examples

**Heatmap:**

<img alt="" />

## Data Structures

Heatmaps can work with pivoted or unpivoted data, using 2 dimensions and one measure, or with all dimensions where there is a numeric available for the color facet. They often use two time facets, for example:

* `date` & `hour_of_day`
* `week` & `day_of_week`
* `month` & `year`

<img alt="" />

## Configuration

There is no heatmap specific configuration, but [color](/visualize-present/visualizations/configuration/color) and [tooltip](/visualize-present/visualizations/configuration/tooltips) controls may be relevant.

Heatmaps support gradient color scale value pins for the color field. You can pin specific minimum, midpoint, and maximum values for the color scale instead of using automatic data ranges. This is useful when you want to maintain consistent color mapping across multiple heatmaps or time periods.

For details on configuring gradient color scales, see [Gradient color scale values](/visualize-present/visualizations/configuration/color#gradient-color-scale-values).


# Overview
Source: https://docs.omni.co/visualize-present/visualizations/types/index

Browse all built-in Omni visualization types, including bar, line, area, map, pie, KPI, table, and custom Vega-Lite charts.

Omni has many visualizations types out of the box for presenting data. Each chart type supports configuration options across the overall visualization, series, and chart facets like axes if applicable.

Additionally, for configuration beyond the UI controls, any of the visualizations built from Vega-lite have an [advanced option](/visualize-present/visualizations/types/custom) to allow full customization of the Vega-lite spec.

## Built-in visualizations

* [AI summary](/visualize-present/visualizations/types/ai-summary)
* [Area charts](/visualize-present/visualizations/types/area)
* [Bar charts](/visualize-present/visualizations/types/bar)
* [Boxplot](/visualize-present/visualizations/types/boxplot)
* [Funnel charts](/visualize-present/visualizations/types/funnel)
* [Heatmap](/visualize-present/visualizations/types/heatmap)
* [KPIs](/visualize-present/visualizations/types/kpi)
* [Line charts](/visualize-present/visualizations/types/line)
* [Maps](/visualize-present/visualizations/types/map)
* [Markdown tiles](/visualize-present/visualizations/types/markdown)
* [Pie & donut charts](/visualize-present/visualizations/types/pie)
* [Sankey charts](/visualize-present/visualizations/types/sankey)
* [Scatterplots](/visualize-present/visualizations/types/scatterplot)
* [Single record](/visualize-present/visualizations/types/single-record)
* [Tables](/visualize-present/visualizations/types/table)

<Tip>
  You can also build [custom visualizations](/visualize-present/visualizations/types/custom) with Vega!
</Tip>

## Configuring visualizations

* [Series mapping](/visualize-present/visualizations/configuration/series-mapping)
* [Series configuration](/visualize-present/visualizations/configuration/series-configuration)
* [X-Axis](/visualize-present/visualizations/configuration/x-axis)
* [Y-Axis (Left Axis, Right Axis)](/visualize-present/visualizations/configuration/y-axis)
* [Color](/visualize-present/visualizations/configuration/color)
* [Size](/visualize-present/visualizations/configuration/size)
* [Tooltips](/visualize-present/visualizations/configuration/tooltips)


# KPI
Source: https://docs.omni.co/visualize-present/visualizations/types/kpi

KPI visualizations highlight the metrics that matter most, with components for single values, comparisons, progress to a goal, sparklines, text, and images.

KPI visualizations spotlight key metrics and data points, from a single headline number to side-by-side comparisons and progress toward a goal. Each KPI is built from one or more rows, and every row can be a different component type, giving you fine-grained control over layout and presentation.

<img alt="Overview of a KPI visualization showing several component types" />

## Adding components

KPIs support several types of components, allowing you to customize the content and layout of your visualization. Click the **Add** button in the visualization to add a new component.

## Customizing components

To customize the display of a component, click the component in the visualization editor. Use the **KPI Builder** tab in the chart configuration options to make changes to the component.

## Component types

KPIs support several component types, each suited to a different way of presenting data. You can mix and match them within a single visualization.

### Number

Highlights a single value.

<Frame>
  <img alt="A KPI number component highlighting a single value" />
</Frame>

<Tip>
  Automatically scale the text size of number components by setting **KPI numbers** to **Dynamic size** in the chart configuration's **Style** tab. When set, numbers will dynamically change size as tiles are resized or dashboard layouts are changed. **Not supported for classic dashboards.**
</Tip>

### Comparison

Comparison components compare one value to another and support comparing across columns and pivots. Select the same column for both comparison fields to compare two rows within a dataset.

<Frame>
  <img alt="A KPI comparison component comparing one value to another" />
</Frame>

### Progress

Compares two values. Useful for showing progress to a goal. Can be displayed as a bar (shown) or a circle.

<Frame>
  <img alt="A KPI progress component shown as a bar" />
</Frame>

<Tip>
  Compare to a static number - like a goal - by adding a column to the query that always returns the same number.
</Tip>

### Chart

Chart components display a mini sparkline, bar, or line chart. Renders a sparkline by default.

<Frame>
  <img alt="A KPI chart component rendered as a sparkline" />
</Frame>

### Text

[Markdown](https://www.markdownguide.org/cheat-sheet/) enabled free text. Useful for titles, headings, and descriptions.

For complex layouts, use the [Markdown visualization](/visualize-present/visualizations/types/markdown).

<Frame>
  <img alt="A KPI text component displaying Markdown-formatted text" />
</Frame>

### Image

Images display an inline image. Configured by providing a URL to a publicly accessible image.

<Frame>
  <img alt="A KPI image component displaying an inline image" />
</Frame>

<Tip>
  Use [Mustache](/visualize-present/mustache-reference) to parameterize the URL. For example, `https://en.gravatar.com/{{result._first.users.img_link}}`
</Tip>

## Styling options

Use the **Style** tab in the chart configuration options to customize the alignment and text sizes for KPI components.

<Frame>
  <img alt="The Style tab of the KPI chart configuration options" />
</Frame>

## Converting to raw Markdown

If you want to customize a KPI beyond Omni's built-in options, you can convert the visualization directly to Markdown by changing the visualization type to **Markdown**.

To undo changes, use the back button in your browser.


# Line charts
Source: https://docs.omni.co/visualize-present/visualizations/types/line

Build line chart visualizations in Omni to display trends, time series, and comparisons with multi-series and stacking options.

## Examples

**Basic Lines:**

<img alt="" />

**Stack 100:**

<img alt="" />

**Monotone:**

<img alt="" />

**Dashed:**

<img alt="" />

**Dual Axes:**

<img alt="" />

## Data Structures

Line charts can work with pivoted or unpivoted data, using 2 dimensions and one measure. To stack or group a chart, one series should be moved to the color facet.

**Unpivoted Data:**

<img alt="" />

**Pivoted Data**

<img alt="" />

Additionally line charts can plot using several measures at once:

<img alt="" />

## Line Configuration Notes

Several configuration options are offered for how lines appear, including showing points, style, weight, interpolation, points

### Line Mark

This is the line icon on each axis, and holds all of the overall configuration options.

<img alt="" />

### Show Points

Points can be toggles on/off to show alongside the lines (default contains no points).

<img alt="" />

### Dashes vs Solid Lines

Whether or not series are shown as solid lines or dashed lines is available (default solid).

<img alt="" />

### Line Thickness

The weight or thickness can be controlled (default 1).

<img alt="" />

### Line Opacity

Setting is available to make the line partially transparent (default solid).

<img alt="" />

### Point Interpolation for Lines

The method for interpolation between points can be controlled (default linear). Options include:

* Linear
* Monotone (smoothed)
* Step (point at midpoint of the step)
* Step Before
* Step After

<img alt="" />

## Overall Configuration Notes

The mark selector at the top of the configuration sets the global chart configuration (configuration across all series). Note that each series can be set independently to bar, line, scatter, area independently under their y-axis controls.

<img alt="" />

The color section controls overall stacking and grouping behavior overall. Additionally stack can be set independently on the different y-axis, under the y-axis series configuration (useful for overall grouping of two stacked grouplets):

* Automatic: we'll guess for you
* Stack: Series on same x-axis value, ontop of each other
* Group: Series offset from their baseline x-axis mark into grouplets
* Overlay: Series *ontop* of each other (usually very undesirable, but useful in rare cases)
* Stack %: Series rebased to 100% across each x-axis value

<img alt="" />

## Other Notes

* Time dimension axes are set to temporal with lines, meaning points will be displayed along a continuous time axis. For charts where ordinal behavior is desired, it's recommended to toggle the individual series from a bar chart accelerator.

* With time fields, order will be automatically set to ascending; other data types will obey the table ordering when graphing

* Tooltips have two styles (see below):

  * On line charts with multiple measures, hover will highlight all available series along the x-axis vertically, vs just the series being hovered.
  * On line charts with a dimension mapped to color (and a single measure), the hover will only show the nearest point

<img alt="" />

<img alt="" />


# Maps
Source: https://docs.omni.co/visualize-present/visualizations/types/map

Omni currently supports point and region map types.

## Point maps

Data with latitude-longitude pairs can be visualized as a point map. Points can be sized and colored by additional properties in the dataset.

**Map with Color Pins**

<img alt="" />

**Map with Sized Pins:**

<img alt="" />

## Region maps

Data with region-based location information can be visualized as a region map. Omni offers region-based mappings for countries and US states out of the box, and offers a custom region option for greater flexibility.

### Built-in countries

Country region data can be mapped against your dataset by either country name, 2-digit country code or 3-digit country code.

| Dataset        | Map            |
| -------------- | -------------- |
| <img alt="" /> | <img alt="" /> |

### Built-in US States

US state region data can be mapped against your dataset by either name or 2-digit code.

| Dataset        | Map            |
| -------------- | -------------- |
| <img alt="" /> | <img alt="" /> |

### Custom Regions

Omni allows you to specify your own region data via URL. You can specify an endpoint that returns region data complying to either the [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) or [TileJSON](https://github.com/mapbox/tilejson-spec/blob/84008d750e54f37739e24785276596f40ccafeab/3.0.0/README.md) specifications.

In order to use custom regions, you'll need to set your region type to "Custom" and then fill out the following fields:

* **Source type** - specify whether your region source is GeoJSON or TileJSON
* **Source URL** - the URL from which to load your GeoJSON or TileJSON data
* **Source layer** (TileJSON only) - the layer within the TileJSON specification you want to map against
* **Region property** - the property in the GeoJSON or TileJSON data that you want to map against

| Dataset        | Map            |
| -------------- | -------------- |
| <img alt="" /> | <img alt="" /> |

## Color configuration

Both region maps (filled maps) and point maps support gradient color scale value pins when coloring by continuous numeric fields. This allows you to pin specific minimum, midpoint, and maximum values for the color scale instead of always using the automatic data range.

For example, if you want to ensure that a specific value always maps to the same color across different time periods or regions, you can pin the min and max values of the color scale to maintain consistent color mapping.

For more information about configuring gradient color scales and pinning values, see [Gradient color scale values](/visualize-present/visualizations/configuration/color#gradient-color-scale-values).

## Projection types

Point and region maps support 2D (mercator) and 3D (globe) projections.

| 2D (Mercator)  | 3D (Globe)     |
| -------------- | -------------- |
| <img alt="" /> | <img alt="" /> |

Point maps also support heatmap projections:

<img alt="" />

## Initial viewport

When working in the workbook editor, you can save a fixed map viewport (center and zoom level) for both point and region maps. Once saved, the map will maintain your chosen view instead of automatically fitting to the data.

To set an initial viewport, pan and zoom the map to your desired view, then click the **Set current view as initial view** control in the map toolbar. The map will display **Fixed view** in the visualization settings once a viewport is saved.

When an initial viewport is set, the map will maintain that view even when data or filters change. To restore the default auto-fit behavior, click **Reset to fit data** in the visualization settings, or use the **Reset map** control on the map itself.

<Note>
  The initial viewport feature is only available in the workbook editor. It is not available on dashboards or in embedded/read-only sessions.
</Note>

## Custom visualizations

More complex map visualizations can be unlocked using [advanced visualization](/visualize-present/visualizations/types/custom).


# Markdown visualizations
Source: https://docs.omni.co/visualize-present/visualizations/types/markdown

Build custom Markdown visualizations in Omni that combine text, images, links, iframes, and live query data in a single tile.

Markdown visualizations allow for a combination of Markdown elements and query variables. You can use it to create a visualization that includes text, images, links, data, iframes, and more.

## Creating Markdown with AI

You can use the [Query Helper](/ai/queries) to generate markdown visualizations based on natural language prompts. The AI will create rich, flexible data displays that combine HTML, CSS, Mustache template variables, and [custom Omni components](#adding-visual-components) like `<Sparkline>` and `<ChangeArrow>`.

To create a Markdown visualization with AI:

<Steps>
  <Step>
    Create a query in a workbook.
  </Step>

  <Step>
    Open the Query Helper.
  </Step>

  <Step>
    Ask Blobby to create a custom layout (e.g., "Create a custom HTML layout for this data" or "Show this as a formatted text display with sparklines")
  </Step>

  <Step>
    Review and refine the generated Markdown visualization as needed.
  </Step>
</Steps>

Once generated, you can continue to refine the visualization through the chat or manually edit it using the Markdown editor. To learn more about building visualizations with AI, refer to [Generating visualizations with AI](/ai/visualizations).

## Using the Markdown editor

When you select **Markdown** as the visualization type, a Markdown editor will display in the chart's **Options** pane. As changes are made, the chart area will automatically update.

At the top of the editor is a toolbar to help you generate correct [Markdown syntax](https://www.Markdownguide.org/cheat-sheet/) for common formatting actions.

<img alt="The Markdown editor in the Options pane with a formatting toolbar at the top" />

You can also access the Markdown editor in a draft dashboard by clicking the <Icon icon="ellipsis-vertical" /> icon on a Markdown tile and selecting **Edit in chart**. The tile will update as you make changes in the editor.

<img alt="Editing a Markdown tile from a draft dashboard using the Edit in chart option" />

### Including HTML

The Markdown editor interprets Markdown first and foremost. While it is possible to incorporate HTML, it helps to think of these more as text documents than true HTML files.

When formatting your code, keep the following in mind:

* **Indentation is interpreted as a code block**. Keep your code flush to the left to prevent unintended code blocks.
* **Empty lines may cause odd behavior**. In Markdown, these are paragraph indicators. This occurs because the `div` is included in a code block as plain text, which will strand its closing tag.

<Note>
  Omni sanitizes your HTML and CSS to prevent potential security vulnerabilities. This includes removing JavaScript and interactive elements such as `<form>`, `<input>`, and `<script>`.

  When an element is removed for security reasons, a message will appear in the Markdown: *“This element is considered dangerous and will not be rendered.”*
</Note>

#### Best practices

While you can use HTML, try to use it sparingly to simplify things. If you do need to use HTML elements:

* **Use supported semantic HTML elements where possible**, such as `article` or `section`. Large numbers of `divs` in a row can cause parsing issues.
* **Limit the depth of `div` nesting**. Deeply nested elements increase the likelihood of conflicts between the Markdown and HTML parsing.
* **Use `<style></style>` and CSS classes** over inline `style` tags for custom CSS.

#### Limitations

* **PDFs in deliveries and downloads may render differently than what's visible in a browser,**, including:
  * **Directly referencing native HTML tags** - for example, `h3 { font-size: 18px; }` may not always work
  * **Some characters in CSS can't be parsed** causing those style declarations to be ignored, including:
    * The quotation marks needed for `content: "<value>";` will not work
    * `&.` and `&:` notation in your CSS will be ignored. Do not use this syntax if you nest your CSS.
* **Invalid HTML or CSS syntax may not render correctly in PNGs or PDFs** even if it correctly renders in a browser. For example, `@media`

### Dark mode styling

When your Omni instance is in dark mode, the Markdown visualization automatically receives a `prefers-dark` class. You can use this class to apply different styles based on the theme.

To target elements in dark mode, use the `&.prefers-dark` selector in your CSS:

```css theme={null}
<style>
  h1 {
    color: red;
  }

  .custom-element {
    background: green;
  }

  &.prefers-dark h1 {
    color: blue;
  }

  &.prefers-dark .custom-element {
    background: yellow;
  }
</style>
```

In this example, `h1` elements will be red in light mode and blue in dark mode. The `custom-element` class will have a green background in light mode and yellow in dark mode.

## Referencing query elements

Data and other elements from the query can be exposed using [Mustache syntax](https://mustache.github.io/). For example, `{{query_element}}`. The full list of query elements can be seen using [`{{ inspect }}`](/visualize-present/mustache-reference#query-and-user-attribute-inspection).

To reference query elements, you can do any of the following:

<Steps>
  <Step>
    Use the **Query details** dropdown menu inside the Markdown editor.
  </Step>

  <Step>
    Click any cell in the results table to copy the Markdown syntax:

    <img alt="Right-clicking a cell in the results table to copy the Markdown syntax" />
  </Step>

  <Step>
    Write the syntax directly, for example:

    ```handlebars theme={null}
    # Example field reference
    {{fields.blob_sales_view.total_sales_field.label}}

    # Example filter reference
    {{filters.blob_sales_view.total_sales_field.value}}
    ```
  </Step>
</Steps>

Refer to the [Markdown Mustache syntax reference](/visualize-present/mustache-reference) for more information and examples.

### Looping through the results set

To iteratively generate Markdown tiles based on the results set, use `{{#result}}` and `{{/result}}` to create a loop. For example:

```html wrap theme={null}
{{#result}} // start a loop
{{<view_name>.<field_name>.value}} // access contents of that loop  [...]
{{<view_name_n>.<field_name_n>.value}} // reference more fields  
(<br>) // // maybe add a newline to create sections
{{/result}} // end loop
```

For [pivoted queries](/analyze-explore/queries/pivots), you can iterate by pivot column or row using `result._pivots` or `row._pivots`. This allows templates to work dynamically when filters change which pivot values exist. See [pivot iteration](/visualize-present/mustache-reference#pivot-iteration) for full syntax and examples.

Check out these examples to see this pattern in action:

* [Repeating pie charts](/showcase/visualizations/repeating-pie-chart)
* [Repeating square fill charts](/showcase/visualizations/repeating-square-fill-chart)
* [Repeating waffle charts](/showcase/visualizations/repeating-waffle-chart)

## Adding visual components

Along with adding images and code to help highlight your data, you can also use the built-in components to create inline visualizations:

* [**Change arrow**](#change-arrow) - Adds an arrow icon indicating the type of change between two data points
* [**Sparkline**](#sparkline) - Adds a [sparkline](https://en.wikipedia.org/wiki/Sparkline). Useful for seeing the shape in variation in a condensed way.

More complex visualizations are possible - check out the [Markdown examples gallery](/showcase) for inspiration.

### Change arrow

Adds an arrow icon indicating the type of change between two data points. If the change is a positive number, the arrow will be green. If negative, it will be red.

To use this component, your results must include two data points that can be used to calculate a change.

<img alt="A ChangeArrow component displaying a green upward arrow between two data points" />

```html wrap theme={null}
<ChangeArrow current="{{result.0.users.count.value_static}}" comparison="{{result.1.users.count.value_static}}"></ChangeArrow>
```

#### Properties

| Name       | Value                                        | Notes                                                                                          |
| ---------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| current    | `result.0.view_name.field_name.value_static` | Use `value_static` instead of `value`, since the value and not the drillable element is needed |
| comparison | `result.1.view_name.field_name.value_static` |                                                                                                |

### Sparkline

Adds a [sparkline](https://en.wikipedia.org/wiki/Sparkline). Useful for seeing the shape in variation in a condensed way.

To use this component, your results must have more than one row of data and a field name.

<img alt="A Sparkline component displaying a small line chart inline with text" />

```html theme={null}
<Sparkline field="users.count" color="cornflowerblue"></Sparkline>
```

#### Properties

| Name    | Value                           | Notes                       |
| ------- | ------------------------------- | --------------------------- |
| color   | CSS color, ex: `cornflowerblue` |                             |
| field   | `view_name.field_name`          |                             |
| height  | Integer, ex: `4`                |                             |
| width   | Integer, ex: `4`                |                             |
| reverse | `true`                          | Remove property for `false` |
| type    | `line` (default) or `bar`       |                             |

## Adding iframes

Using iframes in a Markdown visualization is also supported. iframes can be parameterized with [query elements](#referencing-query-elements).

By default, Omni applies restrictions ([sandboxing](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#:~:text=to%20insecure%20origins.-,sandbox,-Controls%20the%20restrictions)) when rendering iframes. This means that some website features, such as popups, may be unavailable or incompatible.

Use the dropdowns to check out some examples.

<Accordion title="Google Docs">
  <Note>
    Before embedding in Omni, publish the doc and retrieve its embed link.
  </Note>

  **Code**:

  ```html wrap theme={null}
  <iframe width="650" height="450" src="https://docs.google.com/document/d/id"></iframe>
  ```

  **Result**:

  <img alt="A Google Doc embedded in a Markdown visualization using an iframe" />
</Accordion>

<Accordion title="Google News">
  **Code**:

  ```html theme={null}
  <iframe width="200" src="https://google.com/search?igu=1&q={{result._first.customers.name.value_static}}+company&tbm=nws&source=lnms&sa=X&ved=2ahUKEwjv1rPg7LmAAxXsFFkFHWTbCYcQ0pQJegQIPxAB&biw=1420&bih=840&dpr=2"></iframe>
  ```

  **Result**:

  <img alt="Google News search results embedded in a Markdown visualization using an iframe" />
</Accordion>

<Accordion title="Google Maps">
  **Code**:

  ```html theme={null}
  <iframe src="https://www.google.com/maps/embed/v1/search?q={{result.0.products.brand.value_static}}+in+{{result._first.users.city.value_static}},{{result._first.users.state.value_static}}&key=AIzaSyCXfF4zpXaYkgVaBzj3oZUtmcDAxpdoOGk&" width="100%" height="100%"></iframe>
  ```

  **Result**:

  <img alt="A Google Maps embed in a Markdown visualization using an iframe" />
</Accordion>

<Accordion title="Twitter/X">
  **Code**:

  ```html theme={null}
  <iframe height=250 width=550 src="https://twitframe.com/show?url=https%3A%2F%2Ftwitter.com%2Fjack%2Fstatus%2F20"></iframe>
  ```

  **Result**:

  <img alt="A tweet embedded in a Markdown visualization using an iframe" />
</Accordion>

<Accordion title="Windy">
  **Code**:

  ```html theme={null}
  <iframe width="650" height="450" src="https://embed.windy.com/embed2.html?lat=39.018&lon=-77.539&detailLat=39.018&detailLon=-77.539&width=650&height=450&zoom=5&level=surface&overlay=wind&product=ecmwf&menu=&message=&marker=&calendar=now&pressure=&type=map&location=coordinates&detail=&metricWind=default&metricTemp=default&radarRange=-1"></iframe>
  ```

  **Result**:

  <img alt="A Windy weather map embedded in a Markdown visualization using an iframe" />
</Accordion>

<Accordion title="YouTube">
  **Code**:

  ```html theme={null}
  <iframe width="560" height="315" src="https://www.youtube.com/embed/lNAzOJrV-Zk" title="YouTube video player"></iframe>
  ```

  **Result**:

  <img alt="A YouTube video embedded in a Markdown visualization using an iframe" />
</Accordion>

## Example gallery

Check out the [Markdown examples gallery](/showcase) to get inspired!


# Pie & Donut charts
Source: https://docs.omni.co/visualize-present/visualizations/types/pie

Pie:

<img alt="" />

**Donut:**

<img alt="" />

## Data Structure

Pie charts only use two series, the color and the size. If two series are needed in the color, it's recommended to concatenate columns together.

## Configuration Notes

Pie charts use the same color controls as all other charts (more [here](/visualize-present/visualizations/configuration/color)).

## Color configuration

Pie charts support gradient color scale value pins when coloring by continuous numeric fields. This allows you to pin specific minimum, midpoint, and maximum values for the color scale instead of using automatic data ranges.

Pinning these values is useful when you want to maintain consistent color mapping across multiple pie charts or ensure specific values always map to the same colors.

For full details on configuring gradient color scales, see [Gradient color scale values](/visualize-present/visualizations/configuration/color#gradient-color-scale-values).

### Inner Radius

Inner radius will transform the chart between a filled-in pie chart and donut charts of varying thickness:

<img alt="" />

### Pie Labels

Labels are the only other pie-specific configuration available, including inner/outer radius controls, the series mapped to labels, and layout controls for where the label appears. The controls appear under size configuration as shown:

<img alt="" />


# Sankey charts
Source: https://docs.omni.co/visualize-present/visualizations/types/sankey

Sankey charts visualize flows and relationships between stages, showing how values move through different phases of a process.

A Sankey chart shows the flow of values between two or more stages, with the width of each flow proportional to its magnitude.

<img alt="Sankey chart showing flow from various user acquisition sources" />

<Tip>
  Recreate this chart in Omni by downloading the [sample data](https://github.com/exploreomni/doc-sample-data/blob/main/visualizations/sankey.csv) and then [uploading the CSV as a source table](/analyze-explore/data-input-csvs)!
</Tip>

## Use cases

Sankey charts are particularly useful for visualizing:

* User flows through a website or application
* Conversion funnels showing drop-off at each stage
* Resource allocation across different categories
* Migration patterns or transitions between states
* Budget flows and spending breakdowns

## Limitations

**Cycles** are not currently supported. If your data contains a cycle - that is, a circular reference - a `Sankey does not support cycles or paths that loop back to previous nodes.` error will display. Refer to the [Troubleshooting section](#troubleshooting) for more information.

## Data structure

Sankey charts require **at least** two dimensions and a measure:

* **Source** - The starting node for each flow (dimension)
* **Target** - The destination node for each flow (dimension)
* **Link width** - The magnitude of each flow (measure)

The Sankey chart option becomes available once you have at least three fields in your query.

When setting up your query, keep the following in mind:

* Sankey charts work best with a manageable number of nodes. Too many nodes can make the visualization difficult to read.
* Ensure your data includes all relevant flows between stages for an accurate representation

### Multi-level sankeys

You can create multi-level sankey charts when nodes appear in both the source and target fields. For example, if your dataset has nodes `A → B → C`, where `B` serves as both a target (from `A`) and a source (to `C`), the chart will display multiple levels of flow.

For example, consider the dataset used for the chart at the top of this page:

<img alt="Example dataset used for sankey chart, showing source, target, and users columns" />

## Configuration

To view the configuration options for a sankey chart, open the **Chart options** panel in a workbook:

<img alt="" />

### Orientation

Located in the **Sankey** section of the **Chart options** panel, the **Orientation** setting controls how the flows are displayed:

* **Horizontal** - **Default**. Nodes arranged left to right with flows moving horizontally.
* **Vertical** - Nodes arranged top to bottom with flows moving vertically

### Nodes

The Nodes section controls the appearance of the bars at each stage of the flow.

#### Field mapping

* **Source** - The dimension representing the starting point of each flow
* **Target** - The dimension representing the destination of each flow

#### Color

Nodes support two coloring modes:

* **Discrete** - Assigns a distinct color from the palette to each node
* **Gradient** - Applies a continuous color scale based on node size, where larger nodes receive more saturated colors

Sankey charts inherit [modeled colors](/visualize-present/visualizations/configuration/color#dimension-colors) when defined. You can also apply color overrides to individual nodes. Use the reset option to return to default colors (modeled colors plus palette) or clear all assigned colors to ignore modeled colors and apply only the palette.

#### Labels

Toggle data labels to display node names on the chart. Label options include:

* **Position** - Top, bottom, left, right, or inside
* **Font size** - Adjust the label text size
* **Styling** - Bold and italic options

### Links

The Links section controls the appearance of the flows between nodes.

#### Field mapping

* **Link width** - The measure that determines the width of each flow

#### Color

Links support four coloring options:

* **Source-target gradient** - **Default**. A gradient from the source node color to the target node color.
* **Source** - Solid color matching the source node
* **Target** - Solid color matching the target node
* **Custom** - A single color of your choice for all links

#### Data labels

Toggle data labels to display values on the links. Link labels support:

* **Font size and styling** - Standard text formatting options
* **Format** - Number formatting options, such as currency or percentage

### Tooltips

Tooltips appear when hovering over links and nodes to display information about the flow.

#### Default tooltip content

* **Node tooltips** - Display the node name and value
* **Link tooltips** - Display the source node, target node, and flow value

Use the [tooltip configuration](/visualize-present/visualizations/configuration/tooltips) to add additional fields to link tooltips.

#### Show percentages

Enable the **Show percentages** toggle to display percentage calculations in tooltips:

* **Node tooltips** - Shows the node value as a percentage
* **Link tooltips** - Shows three percentage values:
  * **% of total** - The link value as a percentage
  * **% of source node** - The link value as a percentage of the source node's total value
  * **% of target node** - The link value as a percentage of the target node's total value

When percentages are enabled, you can configure:

* **% of total calculation** - Controls how the percentage denominator is calculated for node tooltips and the "% of total" row in link tooltips. Choose between:

  * **as a % of all activity** - **Default**. Best when each step is its own unit of work or cost — like API calls, tasks, or spend. Answers "how much of the total effort went here?"
  * **as a % of all entry points** - Best when things move through stages toward an outcome — like sessions, users, or orders flowing to success or failure. Answers "what fraction of the total ended up here?"

  <Note>
    The **% of source node** and **% of target node** rows are not affected by this setting and always show percentages relative to their respective nodes.
  </Note>

* **Decimal places** - The number of decimal places (0-9) to display for all percentage values

<Note>
  Percentage rows only appear in tooltips when a field is configured for the tooltip and the **Show percentages** toggle is enabled.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sankey option is not available">
    The Sankey chart type requires at least three fields in your query:

    * two dimensions (for source and target nodes)
    * one measure (for link width)

    If you don't see the sankey option in the **Chart selector**, add the required fields to your query.
  </Accordion>

  <Accordion title="'Sankey does not support cycles or paths that loop back to previous nodes.' error">
    Sankey charts require data that flows in one direction without loops. This error appears when your data contains circular references. For example, if `A → B` and `B → A` both exist in your dataset.

    To fix this, review your data for bidirectional flows or loops where a node eventually flows back to itself. You'll need to either remove the rows that create the cycle or restructure your data so flows only move forward through the stages.
  </Accordion>
</AccordionGroup>


# Scatterplots and bubble charts
Source: https://docs.omni.co/visualize-present/visualizations/types/scatterplot

Create scatterplot and bubble chart visualizations in Omni to explore correlations, distributions, and data point clusters.

## Examples

**Basic Scatter:**

<img alt="" />

**Color Scatter:**

<img alt="" />

**Bubble:**

<img alt="" />

**Bubble With Color:**

<img alt="" />

## Data Structures

Scatterplots can work with pivoted or unpivoted data. To layer in color or size, simply drag a series onto the optional facets. Note that color will behave differently for numerics (where color will be plotted as a continuous variable) or strings (where color is plotted as an ordinal). For numerics, the behavior can be toggled under color > type.

When using a continuous numeric color field, you can pin gradient color scale values (minimum, midpoint, and maximum) to control exactly which data values map to which colors. This is useful for maintaining consistent color mapping across multiple charts. See [Gradient color scale values](/visualize-present/visualizations/configuration/color#gradient-color-scale-values) for details.

## Scatter Configuration Notes

### Scatterplot Data Labels

Scatter plots offer limited point-specific configuration, but often desire labels on the points. Series labels are configured from the *Y-Axis menu* (see below), and can be mapped to other series in the results table (often the dimension). For more complex labels, formulas/calculations can build alternative label options.

Here we map the dimension (`Traffic Source`) into our series (`Sales Price Average`), note `Traffic Source` is also on color here, hence the legend, but that is not required:

<img alt="" />

### Scatterplot Tooltips

Tooltip control is another frequent need for scatterplots. To configure which dimensions or measures are in the tooltip, they can be dragged to the tooltip section, and are shown in the order listed.

<img alt="" />

## Overall Configuration Notes

The color section controls overall stacking and grouping behavior overall, which is rarely important for scatterplots. Additionally stack can be set independently on the different y-axis, under the y-axis series configuration (useful for overall grouping of two stacked grouplets):

* Automatic: we'll guess for you
* Stack: Series on same x-axis value, ontop of each other
* Group: Series offset from their baseline x-axis mark into grouplets
* Overlay: Series *ontop* of each other (usually very undesirable, but useful in rare cases)
* Stack %: Series rebased to 100% across each x-axis value

<img alt="" />

## Other Notes

* Time dimension axes are set to temporal with scatterplots (the same as line charts), meaning points will be displayed along a continuous time axis. For charts where ordinal behavior is desired, it's recommended to toggle the individual series from a bar chart accelerator.

* With time fields, order will be automatically set to ascending; other data types will obey the table ordering when graphing

* Tooltips have two styles (see below):

  * On scatterplots with multiple measures, hover will highlight all available series along the x-axis vertically, vs just the series being hovered.
  * On scatterplots with a dimension mapped to color (and a single measure), the hover will only show the nearest point

<img alt="" />

<img alt="" />


# Single record tables
Source: https://docs.omni.co/visualize-present/visualizations/types/single-record

Display a single data row as a pivoted column view in Omni using the single record visualization for compact data presentation.

Single record visualizations offer a compact way to show a single row of data, pivoted to display the full row in a single column. If more than one row is present, the visualization will only show the top row. Full table transpose is available in the table visualization options.

<img alt="" />

## Configuration

The only configuration for single record offers a bit of layout control:

* **Horizontal**: A slightly more compact version of the single-row table
* **Vertical**: Field names above their associated value
* **Compact**: The default view (see above)

## Text formatting

You can customize the appearance of field names and values independently using the text formatting controls:

* **Color**: Choose a custom color for your text
* **Font size**: Adjust the size of your text
* **Font weight**: Make text bold
* **Italic**: Apply italic styling to text

These formatting controls are available for both field names and values, and work across all three layout modes (horizontal, vertical, and compact). User-specified formatting takes precedence over theme defaults. To revert to theme styling, clear the formatting option.


# Table visualizations
Source: https://docs.omni.co/visualize-present/visualizations/types/table

Configure table visualizations in Omni with conditional formatting, in-line charts, layout controls, and data display options.

Table visualizations are useful for displaying detailed information in a clear, organized way. You can also use options like conditional formatting to add additional information to the visualization.

Omni offers many ways to configure tables for more visual sharing, including layout controls, in-line visualization, conditional formatting, and other controls.

<Note>
  Table visualizations are different than the results table. Think of a table visualization as the way you want to present the data in the results table.
</Note>

<img alt="" />

Similar to how a user would interact with the table in the **Results** tab, users can drag and drop columns and interact with the (**three dots**) menu to interact with the data.

## Managing columns

### Showing and hiding columns

To hide columns from the table, right click on any column in the result set from the table visualization configuration. Hidden columns can then be returned from the configuration. Columns may also be hidden from the table options menu.

### Re-sorting and reordering columns

Columns in the results table can be re-arranged using the drag target on each column header. Pivots can only be re-arranged via re-sort, not on an ad hoc basis. **Note:** Dimensions and measures can be interspersed if there is no pivot.

### Freezing columns

Freeze a column to keep it visible while you scroll the rest of the table horizontally. To freeze a column, right click its header or click the (**three dots**) menu on the header, then select **Freeze to the left**. Freezing applies to the column you select and every column to its left. To remove the freeze, open the same menu and select **Unfreeze**.

Freezing is only available in a workbook, so to freeze columns on a dashboard, set the freeze in the workbook and save. The freeze is saved with the visualization, so all viewers see the same frozen columns. Pivoted tables freeze the first visible dimension automatically.

### Working with pivots

Pivots can be sorted the same way that columns are sorted, by clicking on the field header in the results table.

Pivots can also be sorted based on values in the results table by clicking the row number, including by the total. Click the blank row number for totals.

## Table options

The **Table** tab in the **Options** panel allows you to configure column width, pivots, and add or remove columns from the visualization:

* **Column width** - Choose between a full width table (stretch) and a fixed table where column widths will remain fixed regardless of table size, any extra space in the table tile will be blank.

  In stretch mode, Omni measures column widths using the initially visible rows and locks them in place, which prevents columns and wrapped text from shifting as you scroll. Values in rows revealed by scrolling will wrap or truncate to fit the locked width instead of resizing the column. Column widths automatically recalculate when the table's data or columns change or the table is resized. To give a specific column more room, set an exact width using the [**Width** field option](#field-options).
* **Header text** - Controls if a column header will truncate or wrap to the next line if text doesn't fit.
* **View names** - If enabled, the view name will show in the results table.
* **Group dimensions** - If enabled and there's more than one dimension per row, dimensions will be grouped into one expandable section. This allows you to subtotal datasets and increase interactivity in the table:

  <img alt="" />

  You can also expand all groups in a column by right-clicking on its header and selecting **Expand groups**. To collapse all groups, click **Collapse groups**.

### Pivots

Drag and drop fields to pivot the table. Pivots can also be hidden, but must be hidden from the table itself and they will be indexed to the value of the pivoted series. This means if you hide the first pivot, say `status: Returned`, the hide is not indexed to the first pivot, but rather `status: Returned`.

### Fields

Drag and drop fields to add to the table and reorder them directly in this section. Use the drop down arrow to further customize the data in the table.

### Field options

* **Label** - Renames the column's display label, overriding the field's label as defined in the model. Select **Revert** or submit a blank label to remove the override and restore the modeled label.
* **Alignment**
* **Word wrap**
* **Width** - Set an exact pixel width for the column (50-800px). Works in both fixed and stretch layout modes. Clear the value to return to auto-sizing. Useful for aligning column widths across multiple tables on a dashboard.
* **Hide** - Can be used to hide or unhide columns

### Display tab

The **Display** tab allows you to customize how the field is displayed in the table. Fields can be displayed as the original value, images, links, or bars.

By default, Omni will display the current value of the field. See [Configuring table field display options](/visualize-present/visualizations/types/table-field-display) for more information.

## Style options

The **Style** tab allows you to adjust the look and feel of your table by making descriptions available, adding row numbers, banding rows, adjusting the font size, and text and background color of the various elements.

**Banding** will set the rows to alternate between the base background table value color (white) and the base banding background color (grey).

**Font Size** can be increased or decreased for Headers, Values, and Totals.

<img alt="" />

### Colors

In the **Colors** section, you can select a background color and apply text styling to:

* Table headers
* Values
* Banding
* Hover
* Totals

#### Resetting and copying table color palettes

Using the (**three dots**) menu in the **Colors** section allows you to reset the colors to their defaults or copy the hex codes of each defined color.

For example, copying the table palette would create something like the following, making it easily reusable:

```
{"header":{"fontColor":"#fefefe","backgroundColor":"#FF5788"},"banding":{"backgroundColor":"#ffeff3ff"}}
```

## Conditional formatting options

The **Conditional formatting** tab allows you to specify conditions that, if met, will apply the styling you specify to matching rows or a column.

<img alt="" />

<Check>
  To make a background transparent, click the (**bucket icon**) and then the **Custom** tab. Remove the hex code.
</Check>

### Applying gradients

The **Color scale** tab allows you to conditionally apply gradients to table visualizations. *Note*: If you do not set a `mapping` value, the color scale will apply across visible rows which may be confusing when row limits or pagination are active.

When applying a gradient, you can pin specific values for the minimum, midpoint, and maximum of the color scale. This controls which data values map to which colors in the gradient.

For more information about gradient color scale configuration, see [Gradient color scale values](/visualize-present/visualizations/configuration/color#gradient-color-scale-values).


# Configuring table field display options
Source: https://docs.omni.co/visualize-present/visualizations/types/table-field-display

Customize how individual fields appear in a table visualization, including as images, links, Markdown, or bars.

In a [table visualization](/visualize-present/visualizations/types/table), you can control how each field is displayed using the options in the field's **Display** tab. To open it, click the <Icon icon="caret-down" /> icon on a field in the visualization's **Options** panel, then open the **Display** tab.

<Frame>
  <img alt="Display tab for a Markdown field" />
</Frame>

By default, Omni shows the field's original value. From the **Display as** dropdown, you can instead render a field as an image, link, or bar, or—for fields with the `markdown` parameter—as formatted Markdown. The sections below cover each option.

## Displaying fields as images

To display a field as an image, select **Image** from the **Display as** dropdown. The tab will update to display image options, including **Height** and **Width**.

To create a linked image, check the **Link image** box and use the **Link URL** setting to finish configuring the link. This will create a hyperlink that, when clicked, will send the user to a link, a custom link, or an embed event.

<Note>
  The Link URL must be publicly accessible without authentication.
</Note>

## Displaying fields as links

Omni supports displaying field values as links, making it easy to link to relevant pages from the visualization. Dynamic links for each row can be created in just a few steps:

<Steps>
  <Step>
    In the query results table, create a [table calculation](/analyze-explore/calculations) that results in a valid URL. In this example, the `A` column contains a GitHub issue number like `10321`:

    ```text theme={null}
    =CONCAT("https://github.com/blobsrus/issues/",A1)
    ```

    This would result in a value like `https://github.com/blobsrus/issues/10321`.
  </Step>

  <Step>
    In the table visualization, hide the calculation column.
  </Step>

  <Step>
    Open the visualization's **Options** panel.
  </Step>

  <Step>
    In the **Fields** section, click the <Icon icon="caret-down" /> icon on the field to open the field options dialog.
  </Step>

  <Step>
    In the **Display** tab:

    * Set **Display as** to **Link**
    * Set **URL** to the hidden URL calculation field
  </Step>
</Steps>

## Displaying fields as Markdown

Fields with the `markdown` parameter render as formatted Markdown in table cells. This allows you to display rich text including bold and italic formatting, links, and images using [Mustache](/visualize-present/mustache-reference) templates.

To configure Markdown rendering for a field, add the `markdown` parameter to the [dimension](/modeling/dimensions/parameters/markdown)) or [measure](/modeling/measures/parameters/markdown) definition in your model.

See the [visualization showcase](/showcase) for ready-to-use recipes like [pills](/showcase/visualizations/pills), [star ratings](/showcase/visualizations/star-rating), [status indicators](/showcase/visualizations/status-indicator), and [user profiles](/showcase/visualizations/user-profile).

### Customizing Markdown templates in the workbook

When viewing a field with Markdown in a table visualization, you can customize the Markdown template and CSS in the visualization's **Display** tab without editing the model file.

After customizing the template or CSS, click **Promote** to save your changes to the workbook model. Use **Revert** to restore the original modeled definition.

## Displaying numeric fields as bars

Numeric columns can be displayed as bars in the table, allowing you show relative sizes. Select **Bar** from the **Display as** dropdown to view configuration options.

<img alt="" />

<Note>
  If a column contains negative values, bars will split directions. Column alignment settings will be ignored.
</Note>

### Setting a fixed range for bars

By default, bars scale automatically relative to the column's data extent—the largest value in the column fills the bar completely, and all other values are scaled proportionally.

You can instead set a fixed range using the **Range** setting in the **Display** tab. With a fixed range, bars render against an absolute scale regardless of the actual data values. For example, if you set a max of 100, a value of 50 will always fill half the bar, even if no row contains a value near 100.

To configure a fixed range:

1. In the field's **Display** tab, locate the **Range** setting
2. Enter a **Min** value, a **Max** value, or both
3. The bars will now scale against the specified range instead of the data extent

When you set a fixed range:

* **Values within the range** scale proportionally between the min and max
* **Values exceeding the max** truncate to a full bar, but the numeric label displays the true value
* **Values below the min** truncate to an empty bar, but the numeric label displays the true value
* To revert to automatic scaling, clear both the Min and Max inputs by deleting their values

<Note>
  The Min value must be strictly less than the Max value. If you enter an invalid range, the input will revert to the previously stored value.
</Note>