Skip to main content

Push Omni topics to Databricks as metric views

If you’ve built a topic in Omni that you want to formalize as a governed metric view in Databricks Unity Catalog, you can use the 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 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
  • 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

1

Install the Omni Python SDK

  1. In the terminal, clone the SDK repository and install its dependencies: 
    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 and base URL: 
    OMNI_API_KEY=your_api_key
OMNI_BASE_URL=https://your-org.omni.co
2

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: 
    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.
3

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.
python -m examples.databricks_metric_view <model_id> <topic_name> <default_catalog> <default_schema>
Run the script from the SDK directory, for example:
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.
4

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:
Example generated DDL for Omni topic
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, the metric view will also sync back into Omni on the next schema refresh.