From 27d3aa69213e1de0fa4a9ebc465b8cf728064cc8 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 4 Sep 2023 12:39:56 +0100 Subject: [PATCH 01/14] add relation examples for {{this}} jinja function --- .../reference/dbt-jinja-functions/this.md | 68 ++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 9065c660cb0..f41b46109ea 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -3,13 +3,14 @@ title: "about this" sidebar_label: "this" id: "this" description: "Represents the current model in the database." +keywords: relation, relation object, this function, this jinja, --- `this` is the database representation of the current model. It is useful when: - Defining a `where` statement within [incremental models](/docs/build/incremental-models) - Using [pre or post hooks](/reference/resource-configs/pre-hook-post-hook) -`this` is a [Relation](/reference/dbt-classes#relation), and as such, properties such as `{{ this.database }}` and `{{ this.schema }}` compile as expected. +`this` is a [Relation](/reference/dbt-classes#relation), and as such, properties such as `{{ this.database }}` and `{{ this.schema }}` compile as expected. Refer to [using relation objects](#using-relation-objects) for more examples. `this` can be thought of as equivalent to `ref('')`, and is a neat way to avoid circular dependencies. @@ -54,3 +55,68 @@ from raw_app_data.events ``` + + +### Using relation objects + +`{{this}}` is a [relation object](/reference/dbt-classes#relation_) in dbt that simplifies the handling of database schema and table names while ensuring appropriate quoting in SQL code. You can use `{{this}}` for various tasks, such as accessing attributes or validating relation types. For example: + +1. Open a new file and [create](/reference/dbt-classes#using-relations) a relation by calling the `create` class method on the `Relation` class. + +2. In a separate file, set the `{{this}}` relation object with specific database, schema, and identifier values: + + + + ```sql + {% set this = api.Relation.create(database='mydb', schema='public', identifier='my_table') %} + ``` + + + This code creates a `{{this}}` object representing a table named "my_table" in the "public" schema of the "mydb" database. + +2. Once you create a `{{this}}` relation object, you can access its attributes using the double curly brackets `{{ }}` or validate the type of relation. + + The following example commands prints out the database, schema, identifier, and validates the relation type using the **Compile** button: + + + + + + ```sql + -- Accessing attributes + + {{ this.database }} # Fetches the database name + {{ this.schema }} # Fetches the schema + {{ this.identifier }} # Fetches the identifier (table name in this case) + + -- Validating relation type + + Is Table: {{ this.is_table }} # Validate if it's a table + Is View: {{ this.is_view }} # Validate if it's a view + Is CTE: {{ this.is_cte }} # Validate if it's a CTE + ``` + + + + + + + + + ```sql + -- Accessing attributes + + {{ this.database }} # Fetches the database name + {{ this.schema }} # Fetches the schema + {{ this.identifier }} # Returns the request + + -- Validating relation type + + Is Table: {{ this.is_table }} # Validate if it's a table + Is View: {{ this.is_view }} # Validate if it's a view + Is CTE: {{ this.is_cte }} # Validate if it's a CTE + ``` + + + + From e3effaa5673058cb86a901098f8811cd4e11896c Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 4 Sep 2023 12:45:43 +0100 Subject: [PATCH 02/14] fix keywords --- website/docs/reference/dbt-jinja-functions/this.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index f41b46109ea..35319655b66 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -3,7 +3,8 @@ title: "about this" sidebar_label: "this" id: "this" description: "Represents the current model in the database." -keywords: relation, relation object, this function, this jinja, +keywords: + relation, relation object, this function, this jinja, this --- `this` is the database representation of the current model. It is useful when: From 7fc7cad9cac0a4b6c0b8fef1c32313195e9ffc3b Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 4 Sep 2023 14:55:17 +0100 Subject: [PATCH 03/14] fix keyword error --- website/docs/reference/dbt-jinja-functions/this.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 35319655b66..96e95703952 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -4,7 +4,7 @@ sidebar_label: "this" id: "this" description: "Represents the current model in the database." keywords: - relation, relation object, this function, this jinja, this + - relation, relation object, this function, this jinja, this --- `this` is the database representation of the current model. It is useful when: From a438f7e95f0ac219869fff6da9adf3b04f8f2037 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 4 Sep 2023 14:56:12 +0100 Subject: [PATCH 04/14] more keywords --- website/docs/reference/dbt-jinja-functions/this.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 96e95703952..4d55405ef97 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -4,7 +4,7 @@ sidebar_label: "this" id: "this" description: "Represents the current model in the database." keywords: - - relation, relation object, this function, this jinja, this + - relation, relation object, this function, this jinja, this.database, this.schema, this.identifier --- `this` is the database representation of the current model. It is useful when: From d392f4f1b05fabf93565129f437532bba6d7e5a4 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 6 Sep 2023 13:00:55 +0100 Subject: [PATCH 05/14] add link to this on relation page --- website/docs/reference/dbt-classes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docs/reference/dbt-classes.md b/website/docs/reference/dbt-classes.md index 5984826a2a2..3bb4dd39f01 100644 --- a/website/docs/reference/dbt-classes.md +++ b/website/docs/reference/dbt-classes.md @@ -32,6 +32,8 @@ class Relation: ### Using relations +Use relations in your SQL code by wrapping them in double curly brackets `{{ }}` (such as the [Jinja function {{ this }}](/reference/dbt-jinja-functions/this)). For example: + ```jinja2 From 1379c87a3eb58979a3df15d3526439724968ac6d Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Thu, 7 Sep 2023 10:52:59 +0100 Subject: [PATCH 06/14] remove duplication --- .../reference/dbt-jinja-functions/this.md | 21 +++---------------- 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 4d55405ef97..26df6507708 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -60,24 +60,9 @@ from raw_app_data.events ### Using relation objects -`{{this}}` is a [relation object](/reference/dbt-classes#relation_) in dbt that simplifies the handling of database schema and table names while ensuring appropriate quoting in SQL code. You can use `{{this}}` for various tasks, such as accessing attributes or validating relation types. For example: +`{{ this }}` is a [relation object](/reference/dbt-classes#relation_) built in dbt that simplifies the handling of database schema and table names while ensuring appropriate quoting in SQL code. You can use `{{ this }}` for various tasks, such as accessing attributes or validating relation types. -1. Open a new file and [create](/reference/dbt-classes#using-relations) a relation by calling the `create` class method on the `Relation` class. - -2. In a separate file, set the `{{this}}` relation object with specific database, schema, and identifier values: - - - - ```sql - {% set this = api.Relation.create(database='mydb', schema='public', identifier='my_table') %} - ``` - - - This code creates a `{{this}}` object representing a table named "my_table" in the "public" schema of the "mydb" database. - -2. Once you create a `{{this}}` relation object, you can access its attributes using the double curly brackets `{{ }}` or validate the type of relation. - - The following example commands prints out the database, schema, identifier, and validates the relation type using the **Compile** button: +The following command examples print out the database, schema, and identifier and also validate the relation type using the **Compile** button. @@ -88,7 +73,7 @@ from raw_app_data.events {{ this.database }} # Fetches the database name {{ this.schema }} # Fetches the schema - {{ this.identifier }} # Fetches the identifier (table name in this case) + {{ this.identifier }} # Fetches the identifier (For example, table name) -- Validating relation type From 3772d66d8c595d14117c42620bc21cf9cd7da935 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Thu, 7 Sep 2023 10:58:15 +0100 Subject: [PATCH 07/14] simplify example paragraph --- website/docs/reference/dbt-jinja-functions/this.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 26df6507708..187edaf7134 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -60,7 +60,7 @@ from raw_app_data.events ### Using relation objects -`{{ this }}` is a [relation object](/reference/dbt-classes#relation_) built in dbt that simplifies the handling of database schema and table names while ensuring appropriate quoting in SQL code. You can use `{{ this }}` for various tasks, such as accessing attributes or validating relation types. +Since `{{ this }}` is a [relation object](/reference/dbt-classes#relation_) included in dbt, you can use it to simplify the handling of database schema and table names. This also helps you ensure appropriate quoting in SQL code. You can use `{{ this }}` for various tasks, such as accessing attributes or validating relation types. The following command examples print out the database, schema, and identifier and also validate the relation type using the **Compile** button. From 5415e2078f95b193d8512f061e11aa0eb347d1f8 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Fri, 15 Sep 2023 14:10:25 +0100 Subject: [PATCH 08/14] clarify this per convo w joel --- website/docs/reference/dbt-classes.md | 2 + .../docs/reference/dbt-jinja-functions/ref.md | 1 + .../reference/dbt-jinja-functions/source.md | 2 + .../reference/dbt-jinja-functions/this.md | 53 +++---------------- 4 files changed, 11 insertions(+), 47 deletions(-) diff --git a/website/docs/reference/dbt-classes.md b/website/docs/reference/dbt-classes.md index 3bb4dd39f01..630ff92d338 100644 --- a/website/docs/reference/dbt-classes.md +++ b/website/docs/reference/dbt-classes.md @@ -10,6 +10,8 @@ These classes are often useful when building advanced dbt models and macros. The `Relation` object is used to interpolate schema and names into SQL code with appropriate quoting. This object should _always_ be used instead of interpolating values with `{{ schema }}.{{ table }}` directly. Quoting of the Relation object can be configured using the [`quoting` config](/reference/project-configs/quoting). +dbt provides built-in relations, such as [`this`](/reference/dbt-jinja-functions/this), [`source`](/reference/dbt-jinja-functions/source), [`ref`](/reference/dbt-jinja-functions/ref). + ### Creating relations A `Relation` can be created by calling the `create` class method on the `Relation` class. diff --git a/website/docs/reference/dbt-jinja-functions/ref.md b/website/docs/reference/dbt-jinja-functions/ref.md index 6df06a2f415..e1e97a2eb2f 100644 --- a/website/docs/reference/dbt-jinja-functions/ref.md +++ b/website/docs/reference/dbt-jinja-functions/ref.md @@ -30,6 +30,7 @@ from {{ref('model_a')}} `ref()` is, under the hood, actually doing two important things. First, it is interpolating the schema into your model file to allow you to change your deployment schema via configuration. Second, it is using these references between models to automatically build the dependency graph. This will enable dbt to deploy models in the correct order when using `dbt run`. The `{{ ref }}` function returns a `Relation` object that has the same `table`, `schema`, and `name` attributes as the [{{ this }} variable](/reference/dbt-jinja-functions/this). + - Note — Starting from dbt v1.6 or higher, `{{ {ref.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. ## Advanced ref usage diff --git a/website/docs/reference/dbt-jinja-functions/source.md b/website/docs/reference/dbt-jinja-functions/source.md index 2d73e79f09c..d36c4319bf6 100644 --- a/website/docs/reference/dbt-jinja-functions/source.md +++ b/website/docs/reference/dbt-jinja-functions/source.md @@ -13,9 +13,11 @@ select * from {{ source(source_name, table_name) }} This function: - Returns a [Relation](/reference/dbt-classes#relation) for a [source](/docs/build/sources) + - Note — Starting from dbt v1.6 or higher, `{{ {source.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. - Creates dependencies between a source and the current model, which is useful for documentation and model selection - Compiles to the full object name in the database + ## Related guides - [Using sources](/docs/build/sources) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 187edaf7134..68756148ebf 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -5,6 +5,8 @@ id: "this" description: "Represents the current model in the database." keywords: - relation, relation object, this function, this jinja, this.database, this.schema, this.identifier +meta: + label: 'this' --- `this` is the database representation of the current model. It is useful when: @@ -12,9 +14,12 @@ keywords: - Using [pre or post hooks](/reference/resource-configs/pre-hook-post-hook) `this` is a [Relation](/reference/dbt-classes#relation), and as such, properties such as `{{ this.database }}` and `{{ this.schema }}` compile as expected. Refer to [using relation objects](#using-relation-objects) for more examples. + - Note — Starting from dbt v1.6 or higher, `{{ {this.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. `this` can be thought of as equivalent to `ref('')`, and is a neat way to avoid circular dependencies. + + ## Examples @@ -58,51 +63,5 @@ from raw_app_data.events -### Using relation objects - -Since `{{ this }}` is a [relation object](/reference/dbt-classes#relation_) included in dbt, you can use it to simplify the handling of database schema and table names. This also helps you ensure appropriate quoting in SQL code. You can use `{{ this }}` for various tasks, such as accessing attributes or validating relation types. - -The following command examples print out the database, schema, and identifier and also validate the relation type using the **Compile** button. - - - - - - ```sql - -- Accessing attributes - - {{ this.database }} # Fetches the database name - {{ this.schema }} # Fetches the schema - {{ this.identifier }} # Fetches the identifier (For example, table name) - - -- Validating relation type - - Is Table: {{ this.is_table }} # Validate if it's a table - Is View: {{ this.is_view }} # Validate if it's a view - Is CTE: {{ this.is_cte }} # Validate if it's a CTE - ``` - - - - - - - - - ```sql - -- Accessing attributes - - {{ this.database }} # Fetches the database name - {{ this.schema }} # Fetches the schema - {{ this.identifier }} # Returns the request - - -- Validating relation type - - Is Table: {{ this.is_table }} # Validate if it's a table - Is View: {{ this.is_view }} # Validate if it's a view - Is CTE: {{ this.is_cte }} # Validate if it's a CTE - ``` - - - + \ No newline at end of file From cd5d6bc4c17b07e7e3bbc15ffa8ae548c318b777 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Fri, 15 Sep 2023 14:16:10 +0100 Subject: [PATCH 09/14] remove --- website/docs/reference/dbt-jinja-functions/this.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 68756148ebf..87e4dfd2a76 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -13,13 +13,11 @@ meta: - Defining a `where` statement within [incremental models](/docs/build/incremental-models) - Using [pre or post hooks](/reference/resource-configs/pre-hook-post-hook) -`this` is a [Relation](/reference/dbt-classes#relation), and as such, properties such as `{{ this.database }}` and `{{ this.schema }}` compile as expected. Refer to [using relation objects](#using-relation-objects) for more examples. +`this` is a [Relation](/reference/dbt-classes#relation), and as such, properties such as `{{ this.database }}` and `{{ this.schema }}` compile as expected. - Note — Starting from dbt v1.6 or higher, `{{ {this.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. `this` can be thought of as equivalent to `ref('')`, and is a neat way to avoid circular dependencies. - - ## Examples From 9d3684cef6f231d1b73ba3181afac028a76d3ace Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 18 Sep 2023 10:45:00 +0100 Subject: [PATCH 10/14] Update website/docs/reference/dbt-classes.md Co-authored-by: Joel Labes --- website/docs/reference/dbt-classes.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/reference/dbt-classes.md b/website/docs/reference/dbt-classes.md index 630ff92d338..ef0a94e7422 100644 --- a/website/docs/reference/dbt-classes.md +++ b/website/docs/reference/dbt-classes.md @@ -10,7 +10,6 @@ These classes are often useful when building advanced dbt models and macros. The `Relation` object is used to interpolate schema and names into SQL code with appropriate quoting. This object should _always_ be used instead of interpolating values with `{{ schema }}.{{ table }}` directly. Quoting of the Relation object can be configured using the [`quoting` config](/reference/project-configs/quoting). -dbt provides built-in relations, such as [`this`](/reference/dbt-jinja-functions/this), [`source`](/reference/dbt-jinja-functions/source), [`ref`](/reference/dbt-jinja-functions/ref). ### Creating relations From 3bb218556898d51b43e76018713b090f19ef9879 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 18 Sep 2023 10:45:11 +0100 Subject: [PATCH 11/14] Update website/docs/reference/dbt-jinja-functions/source.md Co-authored-by: Joel Labes --- website/docs/reference/dbt-jinja-functions/source.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/source.md b/website/docs/reference/dbt-jinja-functions/source.md index d36c4319bf6..59317a79e3d 100644 --- a/website/docs/reference/dbt-jinja-functions/source.md +++ b/website/docs/reference/dbt-jinja-functions/source.md @@ -13,7 +13,6 @@ select * from {{ source(source_name, table_name) }} This function: - Returns a [Relation](/reference/dbt-classes#relation) for a [source](/docs/build/sources) - - Note — Starting from dbt v1.6 or higher, `{{ {source.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. - Creates dependencies between a source and the current model, which is useful for documentation and model selection - Compiles to the full object name in the database From 9bbdb224ddf88696e4f86a7452e2d1221d563970 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 18 Sep 2023 10:45:43 +0100 Subject: [PATCH 12/14] Update website/docs/reference/dbt-jinja-functions/ref.md Co-authored-by: Joel Labes --- website/docs/reference/dbt-jinja-functions/ref.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/ref.md b/website/docs/reference/dbt-jinja-functions/ref.md index e1e97a2eb2f..fda5992e234 100644 --- a/website/docs/reference/dbt-jinja-functions/ref.md +++ b/website/docs/reference/dbt-jinja-functions/ref.md @@ -30,7 +30,7 @@ from {{ref('model_a')}} `ref()` is, under the hood, actually doing two important things. First, it is interpolating the schema into your model file to allow you to change your deployment schema via configuration. Second, it is using these references between models to automatically build the dependency graph. This will enable dbt to deploy models in the correct order when using `dbt run`. The `{{ ref }}` function returns a `Relation` object that has the same `table`, `schema`, and `name` attributes as the [{{ this }} variable](/reference/dbt-jinja-functions/this). - - Note — Starting from dbt v1.6 or higher, `{{ {ref.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. + - Note — Prior to dbt v1.6, the dbt Cloud IDE returns `request` as the result of `{{ ref.identifier }}`. ## Advanced ref usage From 56848ee48c1782dd6b99c7c8040bd4a501a085e9 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 18 Sep 2023 10:56:35 +0100 Subject: [PATCH 13/14] Update website/docs/reference/dbt-jinja-functions/this.md Co-authored-by: Joel Labes --- website/docs/reference/dbt-jinja-functions/this.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/dbt-jinja-functions/this.md b/website/docs/reference/dbt-jinja-functions/this.md index 87e4dfd2a76..c75a639042c 100644 --- a/website/docs/reference/dbt-jinja-functions/this.md +++ b/website/docs/reference/dbt-jinja-functions/this.md @@ -14,7 +14,7 @@ meta: - Using [pre or post hooks](/reference/resource-configs/pre-hook-post-hook) `this` is a [Relation](/reference/dbt-classes#relation), and as such, properties such as `{{ this.database }}` and `{{ this.schema }}` compile as expected. - - Note — Starting from dbt v1.6 or higher, `{{ {this.identifier }}` will fetch the identifier (such as table name). Previously it would only return the request. + - Note — Prior to dbt v1.6, the dbt Cloud IDE returns `request` as the result of `{{ ref.identifier }}`. `this` can be thought of as equivalent to `ref('')`, and is a neat way to avoid circular dependencies. From a64c1dd9e9d8b0f76e38d534a86034b6925082c1 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 18 Sep 2023 11:07:57 +0100 Subject: [PATCH 14/14] Update website/docs/reference/dbt-classes.md Co-authored-by: Joel Labes --- website/docs/reference/dbt-classes.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/reference/dbt-classes.md b/website/docs/reference/dbt-classes.md index ef0a94e7422..5bd8a4f5ef0 100644 --- a/website/docs/reference/dbt-classes.md +++ b/website/docs/reference/dbt-classes.md @@ -33,8 +33,7 @@ class Relation: ### Using relations -Use relations in your SQL code by wrapping them in double curly brackets `{{ }}` (such as the [Jinja function {{ this }}](/reference/dbt-jinja-functions/this)). For example: - +In addition to `api.Relation.create`, dbt returns a Relation when you use [`ref`](/reference/dbt-jinja-functions/ref), [`source`](/reference/dbt-jinja-functions/source) or [`this`](/reference/dbt-jinja-functions/this). ```jinja2