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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Объясняйте сложную логику кода: если вам самим пришлось «поломать голову», чтобы в ней разобраться, кому‑то ещё тоже придётся это делать
  • Объясняйте нишевую логику, уникальную именно для вашего бизнеса
  • Разделяйте типы полей (например, Ids, booleans, strings, dates, numerics и timestamps) в staging models, чтобы модели были более читаемыми, организованными и формульными
  • Явно помечайте технический долг (-- [TODO]: TECH DEBT) в запросах или моделях

Если вы замечаете, что inline‑комментарии в SQL становятся слишком громоздкими, их сложно быстро просмотреть и понять, — это сигнал, что стоит активнее использовать dbt Docs и markdown‑файлы в вашем dbt‑проекте. dbt поддерживает descriptions, которые позволяют добавлять развернутые описания моделей (а также макросов, sources, snapshots, seeds и колонок). Эти описания будут отображаться в размещённых dbt Docs. Для моделей или колонок, которым требуется более подробная или настраиваемая документация, используйте doc blocks в markdown и YAML файлах, чтобы создавать более детальные пояснения и комментарии.

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

Нашли ошибку?

0
Loading