dbt-labs / dbt-labs/docs.getdbt.com

Quoting for database catalogs, schemas, tables, and columns

Open
#3,518 0 comments 1 reaction 0 assignees View on GitHub
content improvement
Dominant language
JavaScript
Stars
215
Forks
1.2k
Avg merge
1d 15h
Merged PRs (30d)
130

Description

### Contributions

- [X] I have read the contribution docs, and understand what's expected of me.

### TLDR

- **Models:** It is possible to configure quoting for `database`, `schema`, and `identifier` names on a dbt project-wide basis via [`quoting`](https://docs.getdbt.com/reference/project-configs/quoting), but **not** a per-model (or per-seed) basis. However, `column` names can be configured on a per-model basis via [`quote`](https://docs.getdbt.com/reference/resource-properties/quote), but not project-wide.
- **Sources:** `database`, `schema`, and `identifier`, and `column` names can be configured on a per-source and per-table basis (via [`quoting`](https://docs.getdbt.com/reference/resource-properties/quoting) and [`quote`](https://docs.getdbt.com/reference/resource-properties/quote)), but not project-wide.

There are many related pieces in the product documentation, but they aren't linked together (which is the aim of this documentation proposal).

The feature proposal in https://github.com/dbt-labs/dbt-core/issues/2986 aims to unify these 4 levels of quoting into a `quote` config that can be applied [hierarchically](https://docs.getdbt.com/reference/configs-and-properties#config-inheritance) from project-wide down to the individual resource-level.

### Link to the page on docs.getdbt.com requiring updates

There are a couple things that are mostly frequently quoted within SQL:
1. database identifier _names_
2. column _names_ and _values_

For example, all of the following can be quoted within SQL:
- `database` / catalog names (`project` in BigQuery)
- `schema` names (`dataset` in BigQuery)
- `identifier` names (table / view / etc. names)
- `column` _names_
- `column` _values_
- other database object names (`user`s, `role`s, `index`es, etc.)

We have all of the following documentation, but it rarely refers to each other:

#### For `database`, `schema`, and `identifier` names

- [`quoting`](https://docs.getdbt.com/reference/project-configs/quoting) - Configuring quoting in **projects** (for `database`, `schema`, and `identifier`)
- [`quoting`](https://docs.getdbt.com/reference/resource-properties/quoting) - Configuring quoting in **sources** (for `database`, `schema`, and `identifier`)
- [`quoted`](https://github.com/dbt-labs/dbt-adapters/blob/154ca610f67906b0affea9a1e85d29126721cafd/dbt/adapters/base/relation.py#L217) method in the Relation class - Applying quoting to **relations** (for `database`, `schema`, and `identifier`) ([source](https://github.com/dbt-labs/dbt-adapters/blob/d831caa33bc1a31d1162f1d1b3ccd6caaec08fd5/dbt/adapters/base/column.py#L37))
- [`as_case_sensitive`](https://github.com/dbt-labs/dbt-snowflake/pull/1107) in the SnowflakeRelation class (see also: [dbt-snowflake dbt-labs/dbt-adapters#714](https://github.com/dbt-labs/dbt-adapters/issues/714))

#### For `column` names

- [`quote`](https://docs.getdbt.com/reference/resource-properties/quote) - Configuring quoting in **models** for `column` names
- also **sources**, **seeds**, **snapshots**, and **analyses** if you click the tabs
- [`quote_columns`](https://docs.getdbt.com/reference/resource-configs/quote_columns) - Configuring quoting in **seed** files for `column` names
- [`quote_seed_column`](https://github.com/dbt-labs/dbt-adapters/blob/d831caa33bc1a31d1162f1d1b3ccd6caaec08fd5/dbt/adapters/base/impl.py#L928) - Quote or do not quote the column name of a seed according to the [`quote_columns`](https://docs.getdbt.com/reference/resource-configs/quote_columns) configuration
- [`quoted`](https://github.com/dbt-labs/dbt-adapters/blob/154ca610f67906b0affea9a1e85d29126721cafd/dbt/adapters/base/column.py#L37) method in the Column class via [Column API](https://docs.getdbt.com/reference/dbt-classes#column-api) - Applying quoting to relation **columns** for `column` names
- [`quote_identifiers`](https://github.com/dbt-labs/dbt-utils) in macros within `dbt_utils` (like [`star`](https://github.com/dbt-labs/dbt-utils?tab=readme-ov-file#star-source) and [`pivot`](https://github.com/dbt-labs/dbt-utils?tab=readme-ov-file#pivot-source))

#### For `column` values

- [`quote` within `accepted_values`](https://docs.getdbt.com/reference/resource-properties/data-tests#accepted_values) - Configuring quoting in **data tests** for accepted `column` values
- [`dbt.string_literal`](https://github.com/dbt-labs/dbt-adapters/blob/c310bc5fbd36e510353cfcd9a451f69bfdb9c9c3/dbt/include/global_project/macros/utils/literal.sql#L5-L7) - Applying quoting to `column` values in Jinja
- [`dbt.escape_single_quotes`](https://github.com/dbt-labs/dbt-adapters/blob/c310bc5fbd36e510353cfcd9a451f69bfdb9c9c3/dbt/include/global_project/macros/utils/escape_single_quotes.sql#L6-L8) - Escaping single quotes within `column` values in Jinja

#### For multiple purposes

- [`adapter.quote`](https://docs.getdbt.com/reference/dbt-jinja-functions/adapter#quote) - Applying quoting via the **adapter**-specific macro to a `column` name or individual components of a (`database`, `schema`, `identifier`) combo (or even other database objects like `users` or `roles`) ([source](https://github.com/dbt-labs/dbt-adapters/blob/d831caa33bc1a31d1162f1d1b3ccd6caaec08fd5/dbt/adapters/sql/impl.py#L209)).
- [`quote_as_configured`](https://github.com/dbt-labs/dbt-adapters/blob/d831caa33bc1a31d1162f1d1b3ccd6caaec08fd5/dbt/adapters/base/impl.py#L909) - Quote or do not quote the given database, schema, or identifier according to the [`quoting`](https://docs.getdbt.com/reference/project-configs/quoting) project configuration.

### For users / groups / roles in grants

As hinted at in https://github.com/dbt-labs/dbt-postgres/issues/55, we don't have any mechanism to specify that a grant should be quoted. i.e., we don't have a `quote_grants` config.

### What part(s) of the page would you like to see updated?

It would be an improvement to merely cross-link these different pages so that the first result in a Google search is likely to eventually lead where you want to get.

### Additional information

Instigating scenario: https://github.com/dbt-labs/dbt-core/issues/7832

https://github.com/dbt-labs/dbt-core/issues/2986 aims to unify all of these under a single `quote` config/property, but the earliest that might happen is v1.9+, and we'd want to clarify things for users earlier than that as well.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.