Quick Start

Setting up Aggregate Awareness is simple and requires just two steps:

1. Define the pre-aggregate mapping in your dataset
2. Connect to your pre-aggregated table (either existing tables from your warehouse or tables created by Holistics)

Step 1: Define the pre-aggregate mapping

In your dataset file, add a pre_aggregates config that maps your model's dimensions and measures to the columns in your pre-aggregated table.

Dataset ecommerce {
  models: [transactions]

  pre_aggregates: {
    agg_transactions: PreAggregate {

      // Map each column in your pre-aggregated table to the corresponding model field
      dimension created_at_day {
        for: r(transactions.created_at),  // Maps to transactions.created_at
        time_granularity: "day"           // Aggregated at day level
      }
      dimension status {
        for: r(transactions.status)        // Maps to transactions.status
      }
      dimension country {
        for: r(transactions.country)       // Maps to transactions.country
      }
      dimension city {
        for: r(transactions.city)          // Maps to transactions.city
      }
      measure count_transactions {
        for: r(transactions.id)            // Count of transaction IDs
        aggregation_type: 'count'
      }
    }
  }
}

Step 2: Connect to a pre-aggregated table

Now you need to tell Holistics where to find the actual pre-aggregated table. You have two options:

Option A: Use your existing pre-aggregated table

If you already have pre-aggregated tables in your data warehouse (created by dbt, Airflow, or other tools), simply point to them using ExternalPersistence:

Dataset ecommerce {
  pre_aggregates: {
    agg_transactions: PreAggregate {
      // ... mapping of dimensions and measures
      
      // Point to your existing table
      persistence: ExternalPersistence {
        table_name: 'your_schema.your_aggregated_table'  // Replace with your actual table name
      }
    }
  }
}

Key requirement

The dimension and measure names in your pre-aggregate must exactly match the column names in your external table.

Option B: Let Holistics create the table

If you don't have a pre-aggregated table yet, Holistics can create and manage it for you:

Dataset ecommerce {
  pre_aggregates: {
    agg_transactions: PreAggregate {
      // ... mapping of dimensions and measures
      
      // Let Holistics create the table
      persistence: FullPersistence {
        schema: 'persisted'  // Schema where Holistics will create the table
      }
    }
  }
}

After adding this configuration, you'll need to trigger the table creation. See Built-in Pre-aggregate Persistence for detailed instructions.

Quick tip

• Have existing tables? Use ExternalPersistence (Option A)
• Need Holistics to create tables? Use FullPersistence (Option B)

That's it!

Once configured, Holistics will automatically use your pre-aggregated tables when users query the data, resulting in faster performance without any changes to their reports or explorations.

Next steps

• Using Holistics persistence? Learn how to create and refresh tables
• Multiple time granularities: Build multiple pre-aggregates using AML Extend