Skip to content

docs: dbt INDEX projections #6546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
29antonioac wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: dbt INDEX projections #6546

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 49 additions & 2 deletions docs/integrations/data-ingestion/etl-tools/dbt/materializations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,13 @@

### Projections {#projections}

You can add [projections](/data-modeling/projections) to `table` and `distributed_table` materializations using the `projections` configuration:
You can add [projections](/data-modeling/projections) to `table` and `distributed_table` materializations using the `projections` configuration. Each projection entry requires either a `query` or an `index` key (not both).

**Note**: For distributed tables, the projection is applied to the `_local` tables, not to the distributed proxy table.

Check warning on line 185 in docs/integrations/data-ingestion/etl-tools/dbt/materializations.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.Colons 

': F' should be in lowercase.

#### Query projections {#query-projections}

Use `query` to define a full projection query:

```sql
{{ config(
Expand All @@ -193,7 +199,48 @@
]
) }}
```
**Note**: For distributed tables, the projection is applied to the `_local` tables, not to the distributed proxy table.

#### Index projections {#index-projections}

:::note
Requires ClickHouse 25.6 or later.
:::

Use `index` as syntax sugar for lightweight [index projections](https://clickhouse.com/blog/clickhouse-release-25-06#index-projections) that use the `_part_offset` virtual column. Pass a single column name or a list of columns to order by:

```sql
{{ config(
materialized='table',
projections=[
{
'name': 'proj_by_age',
'index': 'age'
}
]
) }}
```

```sql
{{ config(
materialized='table',
projections=[
{
'name': 'proj_by_dept_age',
'index': ['department', 'age']
}
]
) }}
```

dbt-clickhouse generates version-appropriate DDL automatically:

| ClickHouse version | Generated SQL |
|--------------------|---------------|
| 26.1+ | `ADD PROJECTION proj_by_age INDEX age TYPE basic` |
| 25.6 – 26.0 | `ADD PROJECTION proj_by_age (SELECT _part_offset ORDER BY age)` |
| < 25.6 | Compile-time error |

Specifying both `query` and `index` on the same projection entry raises a compile-time error.

## Materialization: incremental {#materialization-incremental}

Expand Down
Loading