Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omni.co/llms.txt

Use this file to discover all available pages before exploring further.

This parameter should be used on the aggregated view, which will allow Omni to match the aggregated table to the underlying views it aggregates.
Check out the Aggregate awareness guide for a comprehensive look at implementing aggregate awareness.

​
Syntax

The fields parameter accepts two formats: an object (recommended) or an array.

​
Properties

​
fields
object | array
required
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.
    When using the array format, field order matters! Make sure the fields listed match the column order in the view’s sql statement.
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.
​
base_view
string
required
The name of the base view that this aggregated view summarizes.

​
Examples

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 fieldsAggregated user_facts fields
users.idbecomesuser_id
order_items.created_at[month]becomesmonth
order_items.count becomescount
order_items.total_sale_pricebecomestotal_sale_price
To create this view in Omni, the user_facts.view file would look like this: 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:
Query without aggregate awareness
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:
Query with aggregate awareness
SELECT user_id, month, count, total_sale_price
FROM user_facts