dbt-labs / dbt-labs/docs.getdbt.com
Quoting for database catalogs, schemas, tables, and columns
- 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.