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

SQL Комментарии

SQL комментарии... двоякая вещь: мы говорим о комментариях встроенных в SQL? Или о комментариях к таблице или представлению в базе данных?

Почему бы не оба варианта!?

На этой странице мы разберем, как создавать как встроенные, так и комментарии на уровне объектов базы данных, общие лучшие практики по SQL комментариям и как dbt может помочь вам улучшить (и контролировать версии) ваших комментариев.

Как создавать SQL комментарии​

Встроенные SQL комментарии начинаются с двух дефисов (--) перед ними в запросе или модели dbt; любой текст, следующий за этими дефисами, считается "закомментированным". Для более длинных, многострочных комментариев обычно используется синтаксис /* ваш многострочный комментарий здесь */.

Пример SQL комментария​

/* эти строки образуют многострочный SQL комментарий; если его раскомментировать,
это вызовет ошибку в этом запросе */
select
	customer_id,
	-- order_id, эта строка закомментирована
	order_date
from {{ ref ('orders') }}

На практике вы, вероятно, увидите SQL комментарии в начале сложной логики кода, чтобы помочь будущим разработчикам или даже опытным бизнес-пользователям понять, что делают конкретные блоки кода. В других случаях вы увидите комментарии, как в приведенном выше коде, которые комментируют строки, больше не нужные (или не существующие) для этого запроса или модели. Мы более подробно рассмотрим лучшие практики по встроенным комментариям позже на этой странице.

Для комментариев к объектам базы данных, таким как представления и таблицы, используется другой синтаксис для добавления этих явных комментариев:

comment on [тип объекта базы данных] <имя объекта базы данных> is 'текст комментария здесь';

Эти комментарии на уровне объектов базы данных более полезны для добавления дополнительного контекста или метаданных к этим объектам, в то время как встроенные комментарии полезны для объяснения функциональности кода. В качестве альтернативы, эти комментарии на уровне таблиц и представлений могут быть легко абстрагированы и контролироваться по версиям с использованием описаний моделей в dbt и сохраняться в объектах с использованием конфигурации persist_docs в dbt.

SQL комментарии в Snowflake, Databricks, BigQuery и Redshift​

Google BigQuery, Amazon Redshift, Snowflake и Databricks поддерживают возможность добавления встроенных SQL комментариев. За исключением BigQuery, эти хранилища данных также поддерживают нативные комментарии на уровне объектов базы данных; однако BigQuery поддерживает нативные описания на уровне полей.

Лучшие практики по SQL комментариям​

В общем, встроенные SQL комментарии следует использовать обдуманно; другой аналитический инженер должен иметь возможность сопоставить ваши комментарии с вашим кодом, чтобы четко понять функциональность модели.

Мы рекомендуем использовать встроенные комментарии в следующих ситуациях:

  • Объяснение сложной логики кода, над которой, если вам пришлось задуматься, кому-то другому тоже придется задуматься
  • Объяснение специфичной, уникальной для вашего бизнеса логики
  • Разделение типов полей (например, идентификаторы, булевы значения, строки, даты, числовые значения и временные метки) в моделях подготовки данных для создания более читаемых, организованных и формульных моделей
  • Ясная маркировка технического долга (-- [TODO]: TECH DEBT) в запросах или моделях

Если вы обнаружите, что ваши встроенные SQL комментарии выходят из-под контроля, становятся менее сканируемыми и читаемыми, это знак, что стоит больше полагаться на dbt Docs и markdown файлы в вашем проекте dbt. dbt поддерживает описания, которые позволяют добавлять подробные описания моделей (или макросов, источников, снимков, семян и источников) и колонок, которые будут отображаться в размещенных dbt Docs. Для моделей или колонок, которые требуют более тщательной или настраиваемой документации, используйте блоки документации в markdown и YAML файлах для создания более детальных объяснений и комментариев.

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