← Все курсы · Курс SQL · Все руководства

COMMENT ON TABLE

Как хранить описание в базе данных, где его сможет найти следующий аналитик · Часть Analyst Prep Kit

К Майкл Носито, аналитик данных · Опубликовано 11 августа 2026 г.

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

Большинство людей имеют в виду --, что останавливает выполнение строки вашего запроса. Если вы пришли именно за этим, это описано в Как комментировать в SQL.

Эта страница о другом. COMMENT ON TABLE — это оператор, который вы запускаете, и он записывает описание в базу данных, прикрепленное к таблице. В следующем году он все еще будет там для коллеги, который никогда не видел ваш файл запроса.

Почему это вообще стоит делать

Каждый аналитик открывал таблицу, которая называлась примерно так: cust_txn_f со столбцом под названием flag_3 и не у кого было спросить.

Знания существовали когда-то. Это было в сообщении Слабый, или в электронной таблице, или в чьей-то голове. Его не было в базе данных, поэтому он не сохранился.

Комментарий к таблице сохраняется, поскольку он перемещается вместе с описываемым объектом. Сделайте резервную копию базы данных, и комментарий тоже появится. Наведите каталог данных или инструмент BI на базу данных, и большинство из них автоматически прочитают эти описания и покажут их людям, которые никогда не будут писать запросы.

На одну таблицу уходит около двадцати секунд. Это самая дешевая документация в работе.

PostgreSQL и Оракул

Оба используют стандартный оператор, и форма у них одинакова.

COMMENT ON TABLE orders IS 'One row per order line, not per order.';

COMMENT ON COLUMN orders.status IS 'Values: new, paid, shipped, refunded. Set by the billing job, not the web app.';

Три вещи о его поведении, все из документации PostgreSQL:

• Для каждого объекта сохраняется только один комментарий. Повторный запуск заменяет текст, а не добавляет второй.
• Чтобы удалить комментарий, установите для него значение NULL: COMMENT ON TABLE orders IS NULL;
• Комментарии удаляются автоматически при удалении объекта, поэтому вы никогда не оставите без внимания.

Вы должны владеть объектом, чтобы комментировать его, и это стоит знать, прежде чем вы напишете тридцать таких писем и обнаружите, что половина из них отклонена.

MySQL

MySQL не имеет COMMENT ON заявление. Комментарий — это предложение, прикрепленное к таблице или столбцу, и оно находится внутри CREATE TABLE или ALTER TABLE.

CREATE TABLE orders (
  id      INT PRIMARY KEY COMMENT 'Order line ID, not order ID',
  status  VARCHAR(20)     COMMENT 'new, paid, shipped, refunded'
) COMMENT = 'One row per order line, not per order.';

В уже существующей таблице используйте ALTER TABLE:

ALTER TABLE orders COMMENT = 'One row per order line, not per order.';

Ограничения документированы, и их стоит знать, прежде чем писать эссе: комментарий к таблице может содержать 2048 символов, комментарий к столбцу — 1024.

SQL Server

SQL Server не имеет COMMENT заявление любого рода. Он хранит подобные вещи как расширенное свойство, которое представляет собой имя и значение, прикрепленные к объекту. Соглашение заключается в том, чтобы назвать свойство MS_Description, потому что это то, что ищет SSMS и большинство инструментов.

EXEC sp_addextendedproperty
  @name = N'MS_Description',
  @value = N'One row per order line, not per order.',
  @level0type = N'SCHEMA', @level0name = N'dbo',
  @level1type = N'TABLE',  @level1name = N'orders';

Для получения того же результата требуется гораздо больше ввода, чем в других базах данных. Использовать sp_updateextendedproperty изменить одно и sp_dropextendedproperty удалить его, так как sp_addextendedproperty ошибки, если свойство уже существует.

SQLite, который не может этого сделать

SQLite не имеет возможности хранить описание таблицы или столбца. Нет COMMENT ON и никаких расширенных свойств.

Вместо этого люди ставят -- комментарий в CREATE TABLE само заявление. SQLite сохраняет исходный текст оператора в sqlite_master.sql, комментарии и все такое, чтобы заметку можно было восстановить:

SELECT sql FROM sqlite_master WHERE name = 'orders';

Это обходной путь, а не функция. Ни один инструмент не будет читать это как описание. Если документация важна для проекта SQLite, храните ее в репозитории рядом с файлом схемы.

Читаю комментарии назад

Написать их – это полдела. Возможность вытащить их все делает их полезными.

Маршруты MySQL и PostgreSQL полезны, поскольку это обычные запросы. Это означает, что вы можете объединить их со списком столбцов и создать словарь данных для всей схемы за один раз, что очень полезно иметь в портфолио проекта.

Что собственно написать в одном

Синтаксис требует минуты, чтобы изучить. Решение о том, что будет в строке, является важной частью, и это такое же решение, как и любой другой комментарий.

Описание заслуживает своего места только в том случае, если оно говорит что-то, о чем еще не говорит название. COMMENT ON TABLE orders IS 'The orders table' это хуже, чем ничего, потому что оно похоже на документацию и не содержит ее.

То, что имя действительно не может сказать вам, стоит двадцати секунд:

• Что такое один ряд. Самое полезное предложение о любом столе. Одна строка на заказ, на строку заказа или на заказ в день.
• Откуда берутся данные и как часто. Загружается каждую ночь из биллинговой системы или записывается приложением в реальном времени.
• Что означают значения. Для любого столбца, содержащего коды или флаги, перечислите их.
• Что в этом плохого. Строки до 2023 года не имеют региона. Это предложение экономит кому-то целый день.

Последний пункт люди упускают из виду, и он наиболее ценен. Тот же принцип, подробно описанный в полном формате, находится в Как комментировать SQL, чтобы он обучал.

Шпаргалка

Тот, кто напишет первым

Если вы сделаете это сегодня ровно для одной таблицы, напишите предложение, в котором будет указано, что представляет собой одна строка. Это вопрос, который задает каждый новичок, на него имя таблицы почти никогда не дает ответа, и неправильное решение приводит к двойному подсчету итогов.

Выберите таблицу, которую вы чаще всего объясняли вслух в этом году. Это объяснение является комментарием.

Хотите более широкий навык, а не одну привычку? SQL для аналитиков читает запросы построчно простыми словами, и это та же привычка, по которой написаны эти комментарии. SQL для аналитиков, 19 $ →