CelestaDoc

Аналогично тому, как в языке Java можно документировать объекты кода при помощи JavaDoc, или в языке Python использовать документирующую константу, доступную затем во время выполнения, объекты базы данных, определённые в CelestaSQL, могут быть задокументированы при помощи комментариев в специальном формате: /** … */ (две звёздочки после первого слэша, в отличие от одной звёздочки в простом комментарии). Эти комментарии называются CelestaDoc-комментариями (по аналогии с JavaDoc), и могут находиться в коде CelestaSQL-скрипта непосредственно перед определениями соответствующих объектов, как в примере:

/**описание гранулы*/
CREATE SCHEMA test1 VERSION '1.0';

/**описание последовательности*/
CREATE SEQUENCE test_entryno;

/**описание таблицы*/
CREATE TABLE table2(
    /**описание первой колонки*/
    column1 INT NOT NULL DEFAULT NEXTVAL(test_entryno) PRIMARY KEY,
    /**описание второй колонки*/
    column2 INT
);

/**описание индекса idx1*/
CREATE INDEX idx1 ON  table2 (column2);

/**описание представления v1*/
CREATE VIEW v1 AS
  SELECT DISTINCT column2 FROM table2;

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

Синтаксический анализатор прочитывает CelestaDoc, и эта информация доступна в объектах метаданных в процессе выполнения при помощи метода getCelestaDoc() (см. раздел Метаданные Celesta).

Цель комментариев CelestaDoc — снабжение объектов Celesta документацией и дополнительной метаинформацией во время выполнения — например, human readable названиями полей, информацией о том, как представлять поля в пользовательском интерфейсе и т. п.

Общепринятой практикой является запись в комментарии CelestaDoc мета-информации в формате JSON-объекта. При этом CelestaDoc может содержать как обычный текст, так и JSON-объект. С помощью утилитного метода getCelestaDocJSON класса CelestaDocUtils можно извлечь первый валидный JSON-объект из CelestaDoc-строки.