Перейти к основному содержимому

query-comment

dbt_project.yml
query-comment: string

Конфигурация query-comment также принимает словарь, как показано ниже:

dbt_project.yml
models:
  my_dbt_project:
    +materialized: table

query-comment:
  comment: string
  append: true | false
  job-label: true | false  # Только для BigQuery

Определение​

Строка, которая вставляется в качестве комментария в каждый запрос, который dbt выполняет в вашей базе данных. Этот комментарий может связывать SQL-выражения с конкретными ресурсами dbt, такими как модели и тесты.

Конфигурация query-comment также может вызывать макрос, который возвращает строку.

По умолчанию​

По умолчанию dbt вставляет комментарий в формате в начало вашего запроса, содержащий информацию, включая версию dbt, имена профиля и цели, а также идентификаторы узлов для ресурсов, которые он выполняет. Например:

/* {"app": "dbt", "dbt_version": "0.15.0rc2", "profile_name": "debug",
    "target_name": "dev", "node_id": "model.dbt2.my_model"} */

create view analytics.analytics.orders as (
    select ...
  );

Использование синтаксиса словаря​

Синтаксис словаря включает два ключа:

  • comment (необязательно, для получения дополнительной информации см. раздел по умолчанию): Строка, которая будет вставлена в запрос в качестве комментария.
  • append (необязательно, по умолчанию=false): Должен ли комментарий быть добавлен в конец запроса (добавлен внизу) или нет (т.е. добавлен в начало запроса). По умолчанию комментарии добавляются в начало запросов (т.е. append: false).

Этот синтаксис полезен для баз данных, таких как Snowflake, которые удаляют начальные SQL-комментарии.

Примеры​

Добавление статического комментария в начало​

Следующий пример вставляет комментарий /* executed by dbt */ в заголовок SQL-запросов, которые выполняет dbt.

dbt_project.yml
query-comment: "executed by dbt"

Пример вывода:

/* executed by dbt */

select ...

Отключение комментариев в запросах​

dbt_project.yml
query-comment:

Или:

dbt_project.yml
query-comment: null

Добавление динамического комментария в начало​

Следующий пример вставляет комментарий, который изменяется в зависимости от настроенного user, указанного в активной цели dbt.

dbt_project.yml
query-comment: "run by {{ target.user }} in dbt"

Пример вывода:

/* run by drew in dbt */

select ...

Добавление комментария по умолчанию в конец​

Следующий пример использует синтаксис словаря для добавления (вместо добавления в начало) комментария по умолчанию.

Обратите внимание, что поле comment: опущено, чтобы позволить добавление комментария по умолчанию.

dbt_project.yml

query-comment:
  append: True

Пример вывода:

select ...
/* {"app": "dbt", "dbt_version": "0.16.`0rc2`", "profile_name": "debug", "target_name": "dev", "node_id": "model.dbt2.my_model"} */
;

BigQuery: включение элементов комментария запроса как меток задания​

Если query-comment.job-label установлено в true, dbt будет включать элементы комментария запроса, если это словарь, или строку комментария, как метки задания в запросе, который он выполняет. Они будут включены в дополнение к меткам, указанным в конфигурации, специфичной для BigQuery.

dbt_project.yml

query-comment:
  job-label: True

Добавление пользовательского комментария в конец​

Следующий пример использует синтаксис словаря для добавления (вместо добавления в начало) комментария, который изменяется в зависимости от настроенного user, указанного в активной цели dbt.

dbt_project.yml

query-comment:
  comment: "run by {{ target.user }} in dbt"
  append: True

Пример вывода:

select ...
/* run by drew in dbt */
;

Промежуточный уровень: Использование макроса для генерации комментария​

Конфигурация query-comment может ссылаться на макросы в вашем проекте dbt. Просто создайте макрос с любым именем (например, query_comment) в вашем каталоге macros, как показано ниже:

macros/query_comment.sql

{% macro query_comment() %}

  dbt {{ dbt_version }}: running {{ node.unique_id }} for target {{ target.name }}

{% endmacro %}

Затем вызовите макрос в вашем файле dbt_project.yml. Убедитесь, что вы заключили макрос в кавычки, чтобы избежать попыток парсера YAML интерпретировать { как начало словаря.

dbt_project.yml
query-comment: "{{ query_comment() }}"

Продвинутый уровень: Использование макроса для генерации комментария​

Следующий пример показывает JSON-комментарий к запросу, который может быть проанализирован для понимания характеристик производительности вашего проекта dbt.

macros/query_comment.sql
{% macro query_comment(node) %}
    {%- set comment_dict = {} -%}
    {%- do comment_dict.update(
        app='dbt',
        dbt_version=dbt_version,
        profile_name=target.get('profile_name'),
        target_name=target.get('target_name'),
    ) -%}
    {%- if node is not none -%}
      {%- do comment_dict.update(
        file=node.original_file_path,
        node_id=node.unique_id,
        node_name=node.name,
        resource_type=node.resource_type,
        package_name=node.package_name,
        relation={
            "database": node.database,
            "schema": node.schema,
            "identifier": node.identifier
        }
      ) -%}
    {% else %}
      {%- do comment_dict.update(node_id='internal') -%}
    {%- endif -%}
    {% do return(tojson(comment_dict)) %}
{% endmacro %}

Как и выше, вызовите этот макрос следующим образом:

dbt_project.yml
query-comment: "{{ query_comment(node) }}"

Контекст компиляции​

Следующие переменные контекста доступны при генерации комментария к запросу:

Переменная контекстаОписание
dbt_versionВерсия dbt, которая используется. Для получения подробной информации о версионировании релизов см. Версионирование.
env_varСм. env_var
modulesСм. modules
run_started_atКогда начался вызов dbt
invocation_idУникальный идентификатор для вызова dbt
fromjsonСм. fromjson
tojsonСм. tojson
logСм. log
varСм. var
targetСм. target
connection_nameСтрока, представляющая внутреннее имя для соединения. Эта строка генерируется dbt.
nodeПредставление узла в виде словаря. Используйте node.unique_id, node.database, node.schema и так далее.

Примечание: Функция var() в макросах query-comment имеет доступ только к переменным, переданным через аргумент --vars в CLI. Переменные, определенные в блоке vars вашего dbt_project.yml, недоступны при генерации комментариев к запросам.

0
Отредактировать эту страницу