Публичный API v2

Базовый путь: /df-api/v2. Аутентификация: X-Api-Key. Эндпоинты контролируются лицензией компании (раздел 5 страницы API). v2 — это полноценный CRUD API на чтение и запись: наряду с эндпоинтами чтения он предоставляет эндпоинты создания/обновления/удаления для проектов, версий, содержимого РПИ (показатели, измерения, факты), групп измерений, таблиц фактов (включая состав и фильтры верификации на уровне таблицы фактов), фильтров верификации на уровне версии и связей. Витрины и подключения доступны в v2 только на чтение (разделы 5–6); дополнительно v2 управляет экспортом/импортом версий (раздел 4 страницы Операции записи в публичном API v2) и Git-подключениями (раздел 5 страницы Операции записи в публичном API v2).

По сравнению с v1 в v2 используются унифицированный формат пагинации (totalPages во всех списках вместо смеси totalPages/total_pages), расширенный формат ошибок (раздел 4), идемпотентная запись (раздел 1 страницы Операции записи в публичном API v2) и генерация SQL для показателей (раздел 3); троттлинг одинаков во всех группах (раздел 2.4 страницы API). Эндпоинты чтения описаны в разделе 2, эндпоинты записи — в разделе 2 страницы Операции записи в публичном API v2, управление доступом к проектам — в разделе 9.9.7.

Далее в этом разделе {v} сокращает /df-api/v2/projects/{project_id}/versions/{version_id}; project_id и version_id — обязательные целочисленные параметры пути, в таблицах параметров они не повторяются. Каждая ошибка v2 приходит в конверте из раздела 4; общие ошибки раздела 4 страницы API действуют для каждого эндпоинта.

1 Отличия v2 от v1

Аспект	v1	v2
Пути показателей, измерений, фактов	{v}/measures, {v}/dimensions, {v}/facts	те же
Пагинация	totalPages в РПИ/проектах/версиях, total_pages в остальных списках	totalPages везде
Поле id сущности (показатели/измерения/факты)	отсутствует	присутствует (первое поле)
Троттлинг	100 запросов / 60 с на ключ	то же
SQL для показателей	нет	?include_sql=true
Тип данных показателей (таблицы фактов)	data_type	display_data_type
Тип данных измерений (таблицы фактов)	data_type	display_data_type + dimension_type + formula
Тип данных фактов (таблицы фактов)	data_type	поле отсутствует
Тип данных измерения в группе измерений	data_type	display_data_type; в деталях группы v2 дополнительно возвращает массив dimensions (с description), которого в деталях v1 нет
created_at / updated_at групп измерений, связей и деталей таблицы фактов	присутствуют (для групп и связей — null)	отсутствуют
relationship_type	локализованная подпись (Many-to-one)	слаг many_to_one
description витрины без описания	ключ отсутствует	null
pageSize выше 100	400 для витрин, подключений, групп измерений, таблиц фактов, связей; без ограничения для проектов, версий и содержимого РПИ	400 для витрин, подключений, Git-подключений; для остальных списков молча ограничивается до 100
Витрины и подключения	только чтение	только чтение (перенесены в v2)
physical_view витрины	exists, type, database, schema, name, created_at	+ status, is_stale, last_refresh_at (раздел 5.2)
Экспорт/импорт версий, Git-подключения	нет	разделы 4–5 страницы Операции записи в публичном API v2
format для витрин и подключений	json | xlsx	только json
Статус generate-sql	201	200
Объекты источника (connected_source, primary_key, foreign_key)	db, schema, table, column	+ connection (раздел 3.6 страницы API)
Правила по диалектам для schema объекта источника (раздел 3.6 страницы API)	только эндпоинты РПИ	все эндпоинты
Формат ошибок	4 поля	+ code и details (раздел 4)
Идемпотентность (Idempotency-Key)	нет	для POST записи; generate-sql, export/file, import/validate, import/preview и test Git-подключения исключены
Частичный успех массовой операции	—	207 Multi-Status (раздел 1 страницы Операции записи в публичном API v2)

2 Эндпоинты чтения

Маршруты чтения (GET) для v2. Чтение витрин и подключений описано вместе с их группами в разделах 5 и 9.9.9.

Метод	Путь	Раздел
GET	/projects	2.1
GET	/projects/{id}/versions	2.2
GET	{v}/measures	2.3
GET	{v}/dimensions	2.4
GET	{v}/facts	2.5
GET	{v}/rmd	2.6
GET	{v}/dimension-groups	2.7
GET	{v}/dimension-groups/{dimension_group_id}	2.8
GET	{v}/fact-tables	2.9
GET	{v}/fact-tables/{fact_table_id}	2.10
GET	{v}/relationships	2.11
GET	{v}/relationships/{relationship_id}	2.12
GET	{v}/data-marts, …/{data_mart_id}, …/{data_mart_id}/view; POST …/generate-sql	5.1–5.4
GET	{v}/connections, …/{connection_id}, …/{connection_id}/schema	6.1–6.3
GET	/projects/{projectId}/access	3.1 страницы Операции записи в публичном API v2
GET	/git-connections, …/{connection_id}	5.1–5.3 страницы Операции записи в публичном API v2

Тела ответов чтения соответствуют аналогам в v1 (разделы 1 страницы Публичный API v1 и 2.8–2.14 страницы Публичный API v1) и отличаются соглашением о пагинации из раздела 1, а также двумя дополнениями.

Первое: каждый объект показателя, измерения и факта — как в постраничных эндпоинтах ({v}/measures, {v}/dimensions, {v}/facts), так и в сводном экспорте РПИ ({v}/rmd) — начинается с поля id. Это стабильный идентификатор сущности в рамках версии проекта (то же значение, которое эндпоинты записи из раздела 2 страницы Операции записи в публичном API v2 принимают как {id} в пути и возвращают в ответах), что позволяет передать результат чтения сразу в последующий вызов PUT / PATCH / DELETE или назначения без дополнительного запроса. id — строка, присутствует независимо от ?include_sql и ?language; row_number сохраняется для отображения/сортировки. Добавление обратно совместимо — клиенты, игнорирующие неизвестные поля, не затрагиваются.

Второе: каждый объект источника содержит поле connection с названием подключения, которому он принадлежит, — форма и правила по диалектам описаны в разделе 9.3.6. Это касается connected_source измерений и фактов, primary_key групп измерений, primary_key и foreign_key в деталях таблицы фактов и связях, а также всего перечисленного внутри сводного экспорта. Если подключение было удалено, connection равен null — и db в этом случае тоже null.

Общее для всех списочных эндпоинтов ниже: page (по умолчанию 1) и pageSize (по умолчанию 20, молча ограничивается до 100); format=xlsx возвращает { "downloadUrl": "<подписанная ссылка, действует 15 минут>" }; недопустимый format отвечает 400 DF_API.INVALID_FORMAT.

2.1 Список проектов

Запрос

GET /df-api/v2/projects

Параметр	Где	Тип	Обяз.	Описание
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100
format	query	json | xlsx	нет	По умолчанию json; xlsx формирует книгу с одним листом Projects
language	query	ru | en	нет	Принимается для единообразия; локализуемых полей нет

Детали

Возвращаются только проекты, доступные владельцу ключа (раздел 2.2 страницы API); недоступные исключаются из страницы и из total.

Ответ

200 OK

{
  "projects": [
    { "id": 12, "name": "Sales Analytics", "description": "Production sales warehouse" }
  ],
  "pagination": { "total": 1, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Поле	Тип	Описание
projects[].id	integer	Идентификатор проекта
projects[].name	string	Имя проекта
projects[].description	string | null	Описание проекта
pagination	object	total, page, pageSize, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.2 Список версий

Запрос

GET /df-api/v2/projects/{id}/versions

Параметр	Где	Тип	Обяз.	Описание
id	путь	integer	да	Идентификатор проекта
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100
format	query	json | xlsx	нет	По умолчанию json; xlsx формирует книгу с одним листом Versions
language	query	ru | en	нет	Принимается для единообразия; локализуемых полей нет

Ответ

200 OK

{
  "versions": [ { "id": 33, "name": "Q4 2025", "is_global": true } ],
  "pagination": { "total": 1, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Поле	Тип	Описание
versions[].id	integer	Идентификатор версии
versions[].name	string	Имя версии
versions[].is_global	boolean	true для опубликованной (глобальной) версии проекта
pagination	object	total, page, pageSize, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.3 Получение показателей

Запрос

GET {v}/measures

Параметр	Где	Тип	Обяз.	Описание
language	query	ru | en	нет	Язык подписей полей-справочников
format	query	json | xlsx	нет	По умолчанию json
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100
include_sql	query	boolean	нет	true или 1: дополнить каждый показатель объектом sql_code (раздел 3)

Детали

Каждая строка начинается с id — стабильного идентификатора показателя в рамках версии — и содержит все колонки таблицы показателей РПИ, незаполненные — как null. Поля-справочники — локализованные подписи; ссылки в формулах отображаются как [Имя].

Ответ

200 OK

{
  "measures": [
    {
      "id": "1000",
      "row_number": 1,
      "group": "Revenue",
      "block": "Sales",
      "measure_name": "Total revenue",
      "measure_description": "Gross revenue across all channels",
      "original_source_type": "Database",
      "original_source": "ERP",
      "original_object": "sales.amount",
      "display_data_type": "Number",
      "measure_type": "Base",
      "restrictions": null,
      "formula": null,
      "report_for_verification": null,
      "comment": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null,
      "variation": null
    }
  ],
  "pagination": { "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 }
}

Поле	Тип	Описание
measures[].id	string	Стабильный идентификатор показателя в рамках версии; {measure_id} эндпоинтов записи
measures[].sql_code	object	Присутствует только при include_sql=true и только если SQL удалось сгенерировать (раздел 3)
measures[].row_number	integer	Позиция строки в таблице РПИ
measures[].group, block	string | null	Группирующие колонки РПИ
measures[].measure_name	string	Имя показателя
measures[].measure_description	string | null	Описание
measures[].original_source_type, original_source, original_object	string | null	Колонки происхождения; свободный текст
measures[].display_data_type	string | null	Локализованная подпись типа данных (Number, Text, Date, …)
measures[].measure_type	string	Локализованная подпись: Base или Calculated
measures[].restrictions	string | null	Колонка ограничений
measures[].formula	string | null	Формула расчётного показателя со ссылками вида [Имя]
measures[].report_for_verification, comment, responsible_for_data, variation	string | null	Текстовые колонки
measures[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
pagination	object	total, page, pageSize, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.4 Получение измерений

Запрос

GET {v}/dimensions

Параметр	Где	Тип	Обяз.	Описание
language	query	ru | en	нет	Язык подписей полей-справочников
format	query	json | xlsx	нет	По умолчанию json
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100

Детали

Каждая строка начинается с id — стабильного идентификатора измерения в рамках версии — и содержит все колонки таблицы измерений РПИ, незаполненные — как null; поля-справочники — локализованные подписи. source_data_type вычисляется из connected_source по закешированной схеме подключения (null, если разрешить не удалось). connected_source содержит connection (раздел 3.6 страницы API): { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_customer", "column": "customer_name" }. Действуют правила по диалектам: schema равна "" для MS SQL Server и ClickHouse.

Ответ

200 OK

{
  "dimensions": [
    {
      "id": "2000",
      "row_number": 1,
      "group": "Customer",
      "block": "Profile",
      "dimension_name": "Customer name",
      "dimension_description": "Full customer name",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "dimension_group": "Customers",
      "display_data_type": "Text",
      "source_data_type": "VARCHAR(255)",
      "dimension_type": "Primary",
      "formula": null,
      "connected_source": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_customer", "column": "customer_name" },
      "comment": null,
      "value_options": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "pagination": { "total": 18, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Поле	Тип	Описание
dimensions[].id	string	Стабильный идентификатор; {dimension_id} эндпоинтов записи
dimensions[].row_number	integer	Позиция строки в таблице РПИ
dimensions[].group, block	string | null	Группирующие колонки РПИ
dimensions[].dimension_name, dimension_description	string / string | null	Имя и описание
dimensions[].original_source_type, original_source, original_object	string | null	Колонки происхождения; свободный текст
dimensions[].dimension_group	string | null	Имя группы измерений, в которую входит измерение
dimensions[].display_data_type	string | null	Локализованная подпись типа данных
dimensions[].source_data_type	string | null	Физический тип колонки, полученный из закешированной схемы подключения
dimensions[].dimension_type	string	Локализованная подпись: Primary или Derived
dimensions[].formula	string | null	Формула производного измерения
dimensions[].connected_source	object | null	Объект источника { db, schema, table, column } (раздел 3.6 страницы API)
dimensions[].connected_source.connection	string | null	Название подключения; null (вместе с db), если подключение удалено
dimensions[].comment, responsible_for_data	string | null	Текстовые колонки
dimensions[].value_options	string | null	Колонка допустимых значений
dimensions[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
pagination	object	total, page, pageSize, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.5 Получение фактов

Запрос

GET {v}/facts

Параметр	Где	Тип	Обяз.	Описание
language	query	ru | en	нет	Язык подписей полей-справочников
format	query	json | xlsx	нет	По умолчанию json
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100

Детали

Каждая строка начинается с id — стабильного идентификатора факта в рамках версии — и содержит все колонки таблицы фактов РПИ, незаполненные — как null; поля-справочники — локализованные подписи. connected_source содержит connection (раздел 3.6 страницы API), а source_data_type вычисляется из него по закешированной схеме подключения (null, если разрешить не удалось).

Ответ

200 OK

{
  "facts": [
    {
      "id": "3000",
      "row_number": 1,
      "group": "Sales",
      "block": "Orders",
      "fact_name": "Order line",
      "fact_description": "An individual line item on a sales order",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "source_data_type": "DECIMAL(18,2)",
      "fact_type": "Primary",
      "formula": null,
      "connected_source": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_order_line", "column": "amount" },
      "report_for_verification": null,
      "comment": null,
      "status": null,
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "pagination": { "total": 6, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Поле	Тип	Описание
facts[].id	string	Стабильный идентификатор; {fact_id} эндпоинтов записи
facts[].row_number	integer	Позиция строки в таблице РПИ
facts[].group, block	string | null	Группирующие колонки РПИ
facts[].fact_name, fact_description	string / string | null	Имя и описание
facts[].original_source_type, original_source, original_object	string | null	Колонки происхождения; свободный текст
facts[].source_data_type	string | null	Физический тип колонки, полученный из закешированной схемы подключения
facts[].fact_type	string	Локализованная подпись: Primary или Derived
facts[].formula	string | null	Формула производного факта
facts[].connected_source	object | null	Объект источника { db, schema, table, column } (раздел 3.6 страницы API)
facts[].connected_source.connection	string | null	Название подключения; null (вместе с db), если подключение удалено
facts[].report_for_verification, comment, responsible_for_data	string | null	Текстовые колонки
facts[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
pagination	object	total, page, pageSize, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.6 Сводный экспорт РПИ

Запрос

GET {v}/rmd

Параметр	Где	Тип	Обяз.	Описание
language	query	ru | en	нет	Язык подписей полей-справочников
format	query	json | xlsx	нет	По умолчанию json; xlsx формирует шесть листов: Measures, Dimensions, Facts, Dimension Groups, Fact Tables, Relationships
include_sql	query	boolean	нет	Дополнить каждый показатель объектом sql_code (раздел 3)

Детали

Сводный экспорт: проект, версия, все строки РПИ и модель данных в одном payload без пагинации. Каждая строка РПИ начинается с id; каждый объект источника содержит connection; dimension_groups[], fact_tables[] и relationships[] содержат те же объекты, что соответствующие списочные эндпоинты v2 (с display_data_type, слагом relationship_type, без created_at).

Ответ

200 OK

{
  "project":  { "id": "12", "name": "Sales Analytics", "description": "Production sales warehouse" },
  "version":  { "id": "33", "name": "Q4 2025", "is_global": true },
  "measures": [
    {
      "id": "1000",
      "row_number": 1,
      "group": "Revenue",
      "block": "Sales",
      "measure_name": "Total revenue",
      "measure_description": "Gross revenue across all channels",
      "original_source_type": "Database",
      "original_source": "ERP",
      "original_object": "sales.amount",
      "display_data_type": "Number",
      "measure_type": "Base",
      "restrictions": null,
      "formula": null,
      "report_for_verification": null,
      "comment": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null,
      "variation": null
    }
  ],
  "dimensions": [
    {
      "id": "2000",
      "row_number": 1,
      "group": "Customer",
      "block": "Profile",
      "dimension_name": "Customer name",
      "dimension_description": "Full customer name",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "dimension_group": "Customers",
      "display_data_type": "Text",
      "source_data_type": "VARCHAR(255)",
      "dimension_type": "Primary",
      "formula": null,
      "connected_source": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_customer", "column": "customer_name" },
      "comment": null,
      "value_options": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "facts": [
    {
      "id": "3000",
      "row_number": 1,
      "group": "Sales",
      "block": "Orders",
      "fact_name": "Order line",
      "fact_description": "An individual line item on a sales order",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "source_data_type": "DECIMAL(18,2)",
      "fact_type": "Primary",
      "formula": null,
      "connected_source": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_order_line", "column": "amount" },
      "report_for_verification": null,
      "comment": null,
      "status": null,
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": {
        "connection": "Production PostgreSQL",
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "display_data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "display_data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"]
    }
  ],
  "fact_tables": [
    {
      "id": "11",
      "name": "fact_sales",
      "description": "Primary sales facts",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "measures_count": 5,
      "dimensions_count": 3,
      "facts_count": 2,
      "verification_filters_count": 2,
      "related_dimension_groups_count": 1
    }
  ],
  "relationships": [
    {
      "id": "1101",
      "source_fact_table": { "id": "11", "name": "fact_sales" },
      "target_dimension_group": { "id": "9", "name": "Geography" },
      "foreign_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "many_to_one"
    }
  ],
  "exported_at": "2026-05-05T08:30:00Z"
}

Поле	Тип	Описание
project, version	object	Идентификация экспортированной версии (id — строками; version.name может быть null)
measures[].id	string	Стабильный идентификатор показателя в рамках версии; {measure_id} эндпоинтов записи
measures[].sql_code	object	Присутствует только при include_sql=true и только если SQL удалось сгенерировать (раздел 3)
measures[].row_number	integer	Позиция строки в таблице РПИ
measures[].group, block	string | null	Группирующие колонки РПИ
measures[].measure_name	string	Имя показателя
measures[].measure_description	string | null	Описание
measures[].original_source_type, original_source, original_object	string | null	Колонки происхождения; свободный текст
measures[].display_data_type	string | null	Локализованная подпись типа данных (Number, Text, Date, …)
measures[].measure_type	string	Локализованная подпись: Base или Calculated
measures[].restrictions	string | null	Колонка ограничений
measures[].formula	string | null	Формула расчётного показателя со ссылками вида [Имя]
measures[].report_for_verification, comment, responsible_for_data, variation	string | null	Текстовые колонки
measures[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
dimensions[].id	string	Стабильный идентификатор; {dimension_id} эндпоинтов записи
dimensions[].row_number	integer	Позиция строки в таблице РПИ
dimensions[].group, block	string | null	Группирующие колонки РПИ
dimensions[].dimension_name, dimension_description	string / string | null	Имя и описание
dimensions[].original_source_type, original_source, original_object	string | null	Колонки происхождения; свободный текст
dimensions[].dimension_group	string | null	Имя группы измерений, в которую входит измерение
dimensions[].display_data_type	string | null	Локализованная подпись типа данных
dimensions[].source_data_type	string | null	Физический тип колонки, полученный из закешированной схемы подключения
dimensions[].dimension_type	string	Локализованная подпись: Primary или Derived
dimensions[].formula	string | null	Формула производного измерения
dimensions[].connected_source	object | null	Объект источника { db, schema, table, column } (раздел 3.6 страницы API)
dimensions[].connected_source.connection	string | null	Название подключения; null (вместе с db), если подключение удалено
dimensions[].comment, responsible_for_data	string | null	Текстовые колонки
dimensions[].value_options	string | null	Колонка допустимых значений
dimensions[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
facts[].id	string	Стабильный идентификатор; {fact_id} эндпоинтов записи
facts[].row_number	integer	Позиция строки в таблице РПИ
facts[].group, block	string | null	Группирующие колонки РПИ
facts[].fact_name, fact_description	string / string | null	Имя и описание
facts[].original_source_type, original_source, original_object	string | null	Колонки происхождения; свободный текст
facts[].source_data_type	string | null	Физический тип колонки, полученный из закешированной схемы подключения
facts[].fact_type	string	Локализованная подпись: Primary или Derived
facts[].formula	string | null	Формула производного факта
facts[].connected_source	object | null	Объект источника { db, schema, table, column } (раздел 3.6 страницы API)
facts[].connected_source.connection	string | null	Название подключения; null (вместе с db), если подключение удалено
facts[].report_for_verification, comment, responsible_for_data	string | null	Текстовые колонки
facts[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
dimension_groups[].id, name, description	string / string / string | null	Идентификация
dimension_groups[].primary_key	object | null	Объект источника с connection (раздел 3.6 страницы API); null, если у группы ещё нет ключа
dimension_groups[].dimensions[]	array	id, name, level (уровень иерархии), display_data_type (локализованный), physical_column
dimension_groups[].related_fact_tables[]	string	ID таблиц фактов, которым назначена группа
fact_tables[].id, name, description, owner, created_at	—	Идентификация; owner — имя создателя
fact_tables[].measures_count, dimensions_count, facts_count	integer	Элементы, назначенные таблице фактов напрямую
fact_tables[].verification_filters_count	integer	Фильтры верификации уровня таблицы фактов
fact_tables[].related_dimension_groups_count	integer	Группы измерений, назначенные таблице фактов
relationships[].relationship_type	string	Слаг many_to_one (единственная кратность, поддерживаемая моделью)
relationships[].foreign_key, primary_key	object | null	Объекты источника с connection; null, если маппинг неполный
relationships[].id	string	Идентификатор связи
relationships[].source_fact_table	object	id, name таблицы фактов с внешним ключом
relationships[].target_dimension_group	object	id, name группы измерений с первичным ключом
exported_at	string	Момент снятия снимка, ISO 8601

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.7 Список групп измерений

Запрос

GET {v}/dimension-groups

Параметр	Где	Тип	Обяз.	Описание
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100
language	query	ru | en	нет	Язык подписей display_data_type
format	query	json | xlsx	нет	По умолчанию json; xlsx формирует книгу с одним листом Dimension Groups

Детали

Возвращает группы измерений (справочники) версии проекта с их первичным ключом, составом измерений и идентификаторами таблиц фактов, ссылающихся на группу. primary_key содержит connection, schema равна "" для MS SQL Server и ClickHouse, а db равен null, только если подключение было удалено; измерения-члены отдают display_data_type вместо data_type; поля created_at нет.

Ответ

200 OK

{
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": {
        "connection": "Production PostgreSQL",
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "display_data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "display_data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"]
    }
  ],
  "pagination": { "total": 12, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Поле	Тип	Описание
dimension_groups[].id, name, description	string / string / string | null	Идентификация
dimension_groups[].primary_key	object | null	Объект источника с connection (раздел 3.6 страницы API); null, если у группы ещё нет ключа
dimension_groups[].dimensions[]	array	id, name, level (уровень иерархии), display_data_type (локализованный), physical_column
dimension_groups[].related_fact_tables[]	string	ID таблиц фактов, которым назначена группа
pagination	object	total, page, pageSize, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.8 Получение деталей группы измерений

Запрос

GET {v}/dimension-groups/{dimension_group_id}

Параметр	Где	Тип	Обяз.	Описание
dimension_group_id	путь	integer	да	Идентификатор группы измерений
language	query	ru | en	нет	Локализация
format	query	json | xlsx	нет	По умолчанию json

Детали

Возвращает полную конфигурацию одной группы измерений: массив dimensions (каждый член — с description) наряду со связанными таблицами фактов и колонками их внешних ключей. Полей created_at / updated_at нет.

Ответ

200 OK

{
  "id": "9",
  "name": "Geography",
  "description": "Geographic regions and countries",
  "primary_key": {
    "connection": "Production PostgreSQL",
    "db": "analytics_db",
    "schema": "public",
    "table": "dim_geography",
    "column": "region_id"
  },
  "dimensions": [
    { "id": "722", "name": "Region", "description": "Sales region", "level": 1, "display_data_type": "Text", "physical_column": "region_name" }
  ],
  "related_fact_tables": [
    { "fact_table_id": "11", "fact_table_name": "fact_sales", "foreign_key_column": "region_id" }
  ]
}

Поле	Тип	Описание
dimensions[]	array	Члены группы с id, name, description, level, display_data_type, physical_column
related_fact_tables[]	array	fact_table_id, fact_table_name, foreign_key_column
id, name, description	string / string / string | null	Идентификация
primary_key	object | null	Объект источника с connection (раздел 3.6 страницы API); null, если у группы ещё нет ключа

Ошибки

Код	HTTP	Условие
DF_API.DIMENSION_GROUP_NOT_FOUND	404	Группа измерений не существует в версии
Общие ошибки	—	Раздел 4 страницы API

2.9 Список таблиц фактов

Запрос

GET {v}/fact-tables

Параметр	Где	Тип	Обяз.	Описание
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100
language	query	ru | en	нет	Принимается; в списке нет локализуемых полей
format	query	json | xlsx	нет	По умолчанию json; xlsx формирует книгу с одним листом Fact Tables

Детали

dimensions_count учитывает только измерения, добавленные непосредственно в таблицу фактов (не входящие ни в одну группу измерений). Измерения, унаследованные через группы, доступны через related_dimension_groups_count и через эндпоинт деталей.

Ответ

200 OK

{
  "fact_tables": [
    {
      "id": "11",
      "name": "fact_sales",
      "description": "Primary sales facts",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "measures_count": 5,
      "dimensions_count": 3,
      "facts_count": 2,
      "verification_filters_count": 2,
      "related_dimension_groups_count": 1
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 6, "totalPages": 1 }
}

Поле	Тип	Описание
fact_tables[].id, name, description, owner, created_at	—	Идентификация; owner — имя создателя
fact_tables[].measures_count, dimensions_count, facts_count	integer	Элементы, назначенные таблице фактов напрямую
fact_tables[].verification_filters_count	integer	Фильтры верификации уровня таблицы фактов
fact_tables[].related_dimension_groups_count	integer	Группы измерений, назначенные таблице фактов
pagination	object	page, pageSize, total, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.10 Получение деталей таблицы фактов

Запрос

GET {v}/fact-tables/{fact_table_id}

Параметр	Где	Тип	Обяз.	Описание
fact_table_id	путь	integer	да	Идентификатор таблицы фактов
language	query	ru | en	нет	Язык подписей display_data_type и invalid_reason
include_dependencies	query	boolean	нет	По умолчанию false; true добавляет каждому показателю рекурсивное дерево dependencies
format	query	json | xlsx	нет	По умолчанию json; xlsx формирует пять листов: Measures, Dimensions, Facts, Dimension Groups, Verification Filters

Детали

Возвращает полную конфигурацию таблицы фактов — её показатели, измерения, факты, группы измерений (с первичными и внешними ключами) и фильтры верификации. measure_type и fact_type — сырые слаги (base / calculated, primary / derived / constant); показатели несут display_data_type (не data_type); измерения — display_data_type, dimension_type и formula; у фактов поля типа данных нет; dimension_groups[].primary_key / foreign_key содержат connection; поля updated_at нет.

Ответ

200 OK

{
  "id": "11",
  "name": "fact_sales",
  "description": "Primary sales facts",
  "owner": "Pavel Shalavin",
  "created_at": "2026-04-15T08:30:00Z",
  "measures": [
    { "id": "501", "name": "Total revenue", "description": "Gross revenue", "formula": "SUM([Amount])", "display_data_type": "Number", "measure_type": "base", "dependencies": null }
  ],
  "dimensions": [
    { "id": "801", "name": "Sale date", "description": "Calendar date of the sale", "display_data_type": "Date", "dimension_type": "primary", "formula": null, "physical_column": "sale_date", "is_from_dimension_group": false, "dimension_group_id": null }
  ],
  "facts": [
    { "id": "611", "name": "Order line", "description": null, "fact_type": "primary", "formula": null, "physical_column": "amount" }
  ],
  "dimension_groups": [
    {
      "id": "9", "name": "Geography", "description": "Geographic regions and countries",
      "primary_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "foreign_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" }
    }
  ],
  "verification_filters": [
    { "id": "301", "name": "Valid sales only", "description": "Excludes test and cancelled orders", "conditions": "[Status] != 'cancelled'", "is_valid": true, "invalid_reason": null }
  ]
}

Поле	Тип	Описание
measures[].display_data_type	string | null	Локализованная подпись типа данных
measures[].measure_type	string | null	base или calculated
dimensions[].dimension_type	string | null	primary или derived
dimensions[].formula	string | null	Формула производного измерения
facts[].fact_type	string | null	primary, derived или constant
measures[].dependencies	array | null	Присутствует и заполняется только при include_dependencies=true; узел содержит id, name, type, formula и рекурсивный массив dependencies
dimensions[].is_from_dimension_group	boolean	true — измерение унаследовано из связанной группы; false — задано прямо в таблице фактов
dimensions[].dimension_group_id	string | null	Группа, из которой унаследовано измерение
…physical_column	string | null	Колонка исходной таблицы, привязанная к элементу
dimension_groups[].primary_key, foreign_key	object | null	Объекты источника соединения (раздел 3.6 страницы API)
verification_filters[].is_valid	boolean	false, если выражение фильтра не разрешается (отсутствующая ссылка, ошибка синтаксиса); invalid_reason несёт локализованное объяснение

Ошибки

Код	HTTP	Условие
DF_API.FACT_TABLE_NOT_FOUND	404	Таблица фактов не существует в версии
Общие ошибки	—	Раздел 4 страницы API

2.11 Список связей

Запрос

GET {v}/relationships

Параметр	Где	Тип	Обяз.	Описание
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, ограничивается до 100
language	query	ru | en	нет	Принимается; relationship_type в v2 — слаг и не локализуется
fact_table_id	query	integer	нет	Только связи с указанной таблицей фактов в качестве источника
dimension_group_id	query	integer	нет	Только связи с указанной группой измерений в качестве цели
format	query	json | xlsx	нет	По умолчанию json

Ответ

200 OK

{
  "relationships": [
    {
      "id": "1101",
      "source_fact_table": { "id": "11", "name": "fact_sales" },
      "target_dimension_group": { "id": "9", "name": "Geography" },
      "foreign_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "many_to_one"
    }
  ],
  "pagination": { "total": 4, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Поле	Тип	Описание
relationships[].relationship_type	string	Слаг many_to_one (единственная кратность, поддерживаемая моделью)
relationships[].foreign_key, primary_key	object | null	Объекты источника с connection; null, если маппинг неполный
relationships[].id	string	Идентификатор связи
relationships[].source_fact_table	object	id, name таблицы фактов с внешним ключом
relationships[].target_dimension_group	object	id, name группы измерений с первичным ключом
pagination	object	page, pageSize, total, totalPages

Ошибки. Только общие ошибки (раздел 4 страницы API).

2.12 Получение деталей связи

Запрос

GET {v}/relationships/{relationship_id}

Параметр	Где	Тип	Обяз.	Описание
relationship_id	путь	integer	да	Идентификатор связи
language	query	ru | en	нет	Принимается; ничего не локализуется
format	query	json | xlsx	нет	По умолчанию json

Детали

Возвращает одну связь с описательными полями обеих сторон; целевая группа измерений дополнительно несёт свой primary_key. ключи содержат connection, relationship_type — слаг many_to_one, полей created_at / updated_at нет.

Ответ

200 OK

{
  "id": "1101",
  "source_fact_table": { "id": "11", "name": "fact_sales", "description": "Primary sales facts" },
  "target_dimension_group": {
    "id": "9", "name": "Geography", "description": "Geographic regions and countries",
    "primary_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" }
  },
  "foreign_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
  "primary_key": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
  "relationship_type": "many_to_one"
}

Поле	Тип	Описание
id	string	Идентификатор связи
source_fact_table, target_dimension_group	object	Обе стороны с description; сторона группы повторяет свой primary_key
foreign_key, primary_key	object | null	Объекты источника с connection; null, если маппинг неполный
relationship_type	string	Слаг many_to_one (единственная кратность, поддерживаемая моделью)

Ошибки

Код	HTTP	Условие
DF_API.RELATIONSHIP_NOT_FOUND	404	Связь не существует в версии
Общие ошибки	—	Раздел 4 страницы API

3 Генерация SQL для показателей (include_sql)

Эндпоинты GET {v}/measures (2.3) и GET {v}/rmd (2.6) принимают опциональный параметр ?include_sql=true. При его передаче каждый элемент массива measures дополняется полем sql_code:

{
  "id": "1000",
  "row_number": 1,
  "measure_name": "Total revenue",
  "sql_code": {
    "generated_at": "2026-05-29T08:00:00.000Z",
    "sql_scripts": [
      {
        "fact_table_id": "11",
        "fact_table_name": "fact_sales",
        "sql": "SELECT SUM(amount) FROM fact_sales WHERE ..."
      }
    ]
  }
}

Поле	Тип	Описание
sql_code.generated_at	string	Момент генерации SQL, ISO 8601
sql_code.sql_scripts[]	array	По одной записи на каждую таблицу фактов, к которой привязан показатель; для показателя без привязок — одна запись с fact_table_id и fact_table_name, равными null
sql_code.sql_scripts[].sql	string	Сгенерированный SQL. Он формируется, но не выполняется

Если для показателя не удалось построить SQL, поле sql_code не включается в ответ для этого элемента; сам запрос при этом успешен.

4 Формат ошибок v2

v2 расширяет базовый конверт из раздела 4 страницы API двумя машиночитаемыми полями. Ответ одинаков для всех эндпоинтов v2:

{
  "message": "Некорректное значение фильтра merge_type",
  "originalMessage": "DF_API.INVALID_MERGE_TYPE",
  "statusCode": 400,
  "error": "BadRequestException",
  "code": "invalid_merge_type",
  "details": [{ "field": "merge_type", "code": "invalid_value" }]
}

Поле	Описание
code	Машиночитаемый код ошибки. Соответствует ключу из раздела 8 страницы API без префикса DF_API. в нижнем регистре: DF_API.DATA_MART_NOT_FOUND → data_mart_not_found. Один код всегда соответствует одному HTTP-статусу
details	Какие поля вызвали ошибку. Пустой массив, если ошибка не привязана к полю (например, invalid_api_key)
details[].field	Имя поля или параметра. Для вложенных и bulk-элементов — путь через точку: measures.1.measure_type
details[].code	Причина по полю из закрытого списка: missing_field, unknown_field, invalid_value. Для ошибок «не найдено» дублирует основной code

Особенности, которые стоит учитывать клиенту:

• originalMessage всегда содержит ключ вида DF_API.*. Ключи, поднятые внутренними сервисами приложения, приводятся к DF_API.* до отдачи наружу — в публичный контракт чужие пространства имён не попадают.
• Ключи, не входящие в каталог, деградируют до обобщённого кода по HTTP-статусу (например, любая неизвестная ошибка 409 станет constraint_violation).
• Неожидаемые внутренние сбои отдаются как 500 / internal_error без внутреннего текста.
• HTTP-статус определяется каталогом кодов, а не классом брошенного исключения.

5 Витрины в v2 (df-api/v2)

Четыре эндпоинта витрин, все — только для чтения: v2, как и v1, не предоставляет операций создания, изменения или удаления витрин, а POST generate-sql ничего не сохраняет и лишь возвращает сгенерированный текст запроса.

Общие свойства всех эндпоинтов группы:

• аутентификация — заголовок X-Api-Key (раздел 2.1 страницы API), доступ к проекту — по правилам раздела 2.2 страницы API: проект, к которому у владельца ключа нет доступа, отдаётся как 404, а не 403;
• вывод только JSON. Параметр format можно не передавать или передать json; любое другое значение, включая xlsx, отклоняется как DF_API.INVALID_FORMAT;
• language (ru / en) влияет только на описательные подписи. Значения-слаги (merge_type, db_type) не переводятся никогда, так как используются как значения фильтров;
• ограничения безопасности раздела 6 страницы API действуют в полном объёме.

5.1 Список витрин

Запрос

GET {v}/data-marts

Параметр	Где	Тип	Обяз.	Описание
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, максимум 100
language	query	ru | en	нет	По умолчанию en; влияет только на type
format	query	json	нет	Допустимо только json
type	query	string	нет	Фильтр по типу витрины: with_grouping, without_grouping, with_grouping_and_pivoting
merge_type	query	string	нет	Фильтр по типу слияния: union, join
search	query	string	нет	Поиск без учёта регистра по подстроке в name и description

Детали

Страница за пределами диапазона ошибкой не является: возвращается пустой data_marts при корректном total.

Ответ

200 OK

{
  "data_marts": [
    {
      "id": "9666",
      "name": "DF Fashion retail sales only",
      "description": "Витрина с продажами без планов",
      "owner": "Алёна Зубакова",
      "created_at": "2026-05-21T13:23:10.621Z",
      "type": "С группировкой",
      "merge_type": null,
      "source_fact_table_count": 1,
      "has_physical_view": false
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 2, "totalPages": 1 }
}

Поле	Тип	Описание
data_marts[].id	string	Идентификатор витрины. Строка, а не число
data_marts[].name	string	Отображаемое имя
data_marts[].description	string | null	Ключ присутствует всегда; null, если описание не заполнено (пустая строка в хранилище тоже отдаётся как null); v1 в этом случае опускает ключ
data_marts[].owner	string	Имя владельца («Имя Фамилия»), либо e-mail, если имя не заполнено
data_marts[].created_at	string	Дата создания, ISO 8601
data_marts[].type	string	Локализованная подпись типа: «С группировкой», «Без группировки», «С группировкой и сверткой»
data_marts[].merge_type	string | null	Сырой слаг union / join, не переводится. null для витрин, не объединяющих несколько таблиц фактов
data_marts[].source_fact_table_count	integer	Количество уникальных таблиц фактов, используемых как источники
data_marts[].has_physical_view	boolean	Материализовано ли для витрины физическое представление
pagination	object	page, pageSize, total, totalPages

Ошибки

Код	HTTP	Условие
DF_API.INVALID_TYPE	400	Значение type не входит в допустимый набор
DF_API.INVALID_MERGE_TYPE	400	Значение merge_type не входит в допустимый набор
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize больше 100
Общие ошибки	—	Раздел 4 страницы API

5.2 Детали витрины

Запрос

GET {v}/data-marts/{data_mart_id}

Параметр	Где	Тип	Обяз.	Описание
data_mart_id	путь	integer	да	Идентификатор витрины
language	query	ru | en	нет	Язык подписей type и data_type
format	query	json	нет	Допустимо только json

Детали

Полная конфигурация витрины: таблицы-источники, выбранные показатели, факты и измерения, метаданные физического представления. Для витрин со свёрткой (type соответствует слагу with_grouping_and_pivoting) ответ дополнительно содержит selected_measure_attributes — он размещается перед physical_view:

"selected_measure_attributes": [
  { "attribute_id": "18", "attribute_name": "Measure name" },
  { "attribute_id": "24", "attribute_name": "Measure description" }
]

Ответ

200 OK

{
  "id": "9667",
  "name": "DF Fashion retail sales and plans",
  "description": "Объединенная витрина с продажами и планами",
  "owner": "Алёна Зубакова",
  "created_at": "2026-05-21T13:23:10.621Z",
  "type": "С группировкой",
  "merge_type": "join",
  "source_fact_tables": [
    { "id": "6784", "name": "Sales and refunds", "description": "Таблица фактов с возвратами и продажами" }
  ],
  "selected_measures": [
    {
      "instance_id": "155341",
      "measure_id": "33540",
      "measure_name": "Items Gross, count",
      "description": "Количество уникальных проданных позиций",
      "formula": "COUNTDISTINCT({[operation_id]=1} [Receipt position])",
      "data_type": "Number",
      "display_name": "Items Gross, count",
      "aggregation_configuration": { "type": "default", "group_by_fields": [] },
      "source_fact_table_id": "6784"
    }
  ],
  "selected_facts": [
    {
      "fact_id": "611",
      "fact_name": "Order line",
      "description": null,
      "data_type": "Number",
      "display_name": "Order line",
      "include_in_result": true,
      "filter_condition": null,
      "source_fact_table_id": "6784"
    }
  ],
  "selected_dimensions": [
    {
      "dimension_id": "33929",
      "dimension_name": "Year",
      "description": "Год периода в диапазоне фильтра",
      "data_type": "Number",
      "display_name": "Year",
      "include_in_result": true,
      "filter_condition": "[Year] >= 2020",
      "source_fact_table_id": "6785",
      "source_dimension_group_id": "1204",
      "source_dimension_group_name": "Calendar"
    }
  ],
  "physical_view": {
    "exists": false,
    "type": null,
    "database": null,
    "schema": null,
    "name": null,
    "created_at": null,
    "status": null,
    "is_stale": null,
    "last_refresh_at": null
  }
}

Поле	Тип	Описание
description (витрина, source_fact_tables[], selected_measures[], selected_facts[], selected_dimensions[])	string | null	Ключ присутствует всегда; null, если описание не заполнено
source_fact_tables[]	array	Таблицы фактов, используемые витриной как источники
selected_measures[].instance_id	string	Идентификатор экземпляра показателя в витрине. Один и тот же показатель может входить в витрину несколько раз с разной настройкой агрегации
selected_measures[].measure_id	string	Идентификатор самого показателя в РПИ
selected_measures[].formula	string	Формула расчётного показателя; для базовых — пусто
selected_measures[].aggregation_configuration.type	string	default, none, custom или global
selected_measures[].aggregation_configuration.group_by_fields	array	Идентификаторы полей, по которым группируется показатель
…include_in_result	boolean	false означает, что элемент участвует только в фильтрации и не попадает в результат
…filter_condition	string | null	Выражение фильтра, в котором ссылки на элементы заменены их именами; null, если фильтра нет
selected_dimensions[].source_dimension_group_id / source_dimension_group_name	string | null	Группа измерений, определённая по модели данных, — даже если она не указана в атрибутах витрины явно
physical_view	object	Метаданные материализованного объекта — exists, type (локализованная подпись вида объекта), database (сырой слаг), schema, name, created_at, status, is_stale, last_refresh_at — но без поля connection: его возвращает только отдельный эндпоинт представления

Ошибки

Код	HTTP	Условие
DF_API.DATA_MART_NOT_FOUND	404	Витрина не существует в указанной версии. details адресует поле data_mart_id
Общие ошибки	—	Раздел 4 страницы API

5.3 Метаданные физического представления

Запрос

GET {v}/data-marts/{data_mart_id}/view

Параметр	Где	Тип	Обяз.	Описание
data_mart_id	путь	integer	да	Идентификатор витрины
language	query	ru | en	нет	Язык подписи type
format	query	json	нет	Допустимо только json

Детали

Метаданные объекта, который DataForge материализовал для витрины. Подключение к целевой СУБД не выполняется — возвращается только то, что известно платформе. Если представления нет, exists равен false, а все остальные поля — null:

{
  "exists": false, "type": null, "database": null, "schema": null, "name": null, "created_at": null,
  "status": null, "is_stale": null, "last_refresh_at": null, "connection": null
}

Ответ

200 OK

{
  "exists": true,
  "type": "Материализованное представление",
  "database": "clickhouse",
  "schema": "dataforge_test",
  "name": "materialized_view_6839_datamart_DF Fashion retail sales only",
  "created_at": "2026-03-17T12:44:45.000Z",
  "status": "active",
  "is_stale": false,
  "last_refresh_at": "2026-08-30T03:00:12.000Z",
  "connection": { "id": "3160", "name": "Click", "db_type": "clickhouse" }
}

Поле	Тип	Описание
exists	boolean	Материализован ли объект. Если false, все остальные поля равны null
type	string | null	Локализованная подпись вида объекта. Сырые слаги: regular_view, materialized_view, table
database	string | null	Сырой слаг типа СУБД: postgresql, clickhouse, sqlserver. Не переводится
schema	string | null	Схема, в которой создан объект. Только для PostgreSQL; null для MS SQL Server и ClickHouse, где «схема» подключения и есть его база
name	string | null	Имя объекта в СУБД
created_at	string | null	Дата создания объекта, ISO 8601
status	string | null	Сырой слаг состояния жизненного цикла объекта: deploying, active, updating, deleting, error. Не переводится
is_stale	boolean | null	true, если конфигурация витрины изменилась после развёртывания и объект расходится с ней (требуется пересоздание); false, если объект соответствует текущей конфигурации; null, если объекта нет
last_refresh_at	string | null	Момент последнего успешного обновления данных объекта, ISO 8601; null, если обновление ещё не выполнялось
connection	object | null	Подключение, в котором создан объект. null, если представления нет либо подключение не удалось определить. Учётных данных не содержит — только id, name и db_type

Ошибки

Код	HTTP	Условие
DF_API.DATA_MART_NOT_FOUND	404	Витрина не существует в указанной версии. details адресует поле data_mart_id
Общие ошибки	—	Раздел 4 страницы API

5.4 Генерация SQL-скрипта

Запрос

POST {v}/data-marts/{data_mart_id}/generate-sql

Параметр	Где	Тип	Обяз.	Описание
data_mart_id	путь	integer	да	Идентификатор витрины
limit	query	integer > 0	нет	Добавляет ограничение числа строк в синтаксисе целевой СУБД: LIMIT n OFFSET m для PostgreSQL и ClickHouse, OFFSET m ROWS FETCH NEXT n ROWS ONLY для MS SQL
offset	query	integer ≥ 0	нет	Смещение; действует только совместно с limit. Передан без limit — игнорируется
language	query	ru | en	нет	Язык validation_errors[].message

POST {v}/data-marts/{data_mart_id}/generate-sql?limit=100&offset=0

Детали

Тело запроса не передаётся. Возвращает текст SQL-запроса витрины. Запрос не выполняется, данные из целевой СУБД не читаются, ничего не сохраняется.

В отличие от v1, где { "limit": …, "offset": … } передаются в теле запроса, v2 читает эти значения из query-строки. Тело JSON с числовым limit отклоняется межсетевым экраном на границе до того, как запрос дойдёт до API.

Эндпоинт игнорирует Idempotency-Key — он ничего не создаёт, и повторный вызов всегда генерирует SQL заново, а не отдаёт закэшированный ответ. Отвечает 200, а не 201, и не 4xx при неудаче генерации: именно validation_errors отличает «витрина сейчас не может дать SQL» от «витрины не существует» (404). Для MS SQL, если в запросе нет ORDER BY, добавляется ORDER BY (SELECT NULL) — иначе конструкция OFFSET … FETCH NEXT синтаксически недопустима.

Ответ

200 OK, успех:

{
  "sql_script": "SELECT ... FROM ... GROUP BY ... LIMIT 100 OFFSET 0",
  "target_db_type": "clickhouse",
  "validation_errors": []
}

200 OK, сгенерировать SQL не удалось:

{
  "sql_script": "",
  "target_db_type": null,
  "validation_errors": [
    { "code": "SQL_GENERATION_FAILED", "message": "Внешний ключ не настроен для группы измерений \"География\"" }
  ]
}

Поле	Тип	Описание
sql_script	string	Сгенерированный SELECT. Пустая строка при неудаче
target_db_type	string | null	Тип целевой СУБД: postgres, clickhouse, sqlserver. null при неудаче
validation_errors	array	Пустой массив при успехе
validation_errors[].code	string	Всегда SQL_GENERATION_FAILED
validation_errors[].message	string	Человекочитаемая причина, локализуется по language / Accept-Language. Для неожидаемых внутренних сбоев — обобщённый текст без внутренних деталей

Ошибки

Код	HTTP	Условие
DF_API.VALIDATION_FAILED	400	Query-параметр не прошёл проверку схемы: limit не целое положительное (0, -3, 2.7, abc), offset отрицательный. details адресует конкретный параметр
DF_API.DATA_MART_NOT_FOUND	404	Витрина не существует в указанной версии
Общие ошибки	—	Раздел 4 страницы API

6 Подключения в v2 (df-api/v2)

Три эндпоинта подключений к внешним СУБД. Все только для чтения — создание, изменение и удаление подключений через публичный API недоступны ни в v1, ни в v2; они выполняются только в интерфейсе платформы.

Два свойства, важных для интеграций:

• учётные данные не возвращаются никогда. Пароль, сертификаты, закрытые ключи и строка подключения отсутствуют в ответах (полный перечень — раздел 6 страницы API). Возвращаются только сетевые координаты и имя пользователя СУБД, необходимые для построения SQL;
• схема — это кэшированный снимок, снятый при настройке подключения или при последнем обновлении, а не результат обращения к СУБД в момент запроса. Момент снятия снимка указан в last_updated_at.

Подключения СУБД, не поддерживаемых публичным API (например MySQL), из выдачи исключаются полностью — они не попадают ни в список, ни в total, а обращение к такому подключению по идентификатору отдаёт 404.

6.1 Список подключений

Запрос

GET {v}/connections

Параметр	Где	Тип	Обяз.	Описание
page	query	integer	нет	Номер страницы, нумерация с 1. По умолчанию 1
pageSize	query	integer	нет	Размер страницы. По умолчанию 20, максимум 100
language	query	ru | en	нет	Принимается для единообразия; на ответ не влияет — все поля подключения являются сырыми слагами
format	query	json	нет	Допустимо только json
db_type	query	string	нет	Фильтр по типу СУБД: postgresql, clickhouse, sqlserver
status	query	string	нет	Фильтр по статусу: active, inactive, never_verified, failed

Детали

Соответствие внутреннего состояния публичному status:

Внутреннее состояние	Публичный status
Обновление схемы ни разу не завершалось успешно	never_verified
UPDATE_ERROR	failed
DISABLED	inactive
Остальные случаи	active

never_verified имеет приоритет: без успешного обновления платформа не может утверждать ничего о состоянии подключения, поэтому этот статус возвращается независимо от внутреннего значения.

Ответ

200 OK

{
  "connections": [
    {
      "id": "3821",
      "name": "Production PostgreSQL",
      "db_type": "postgresql",
      "host": "db.production.company.com",
      "port": 5432,
      "database": "analytics_db",
      "schema": "public",
      "username": "analytics_user",
      "status": "active",
      "last_updated_at": "2026-05-21T13:23:07.188Z"
    },
    {
      "id": "3822",
      "name": "Legacy SQL Server",
      "db_type": "sqlserver",
      "host": "sqlserver.legacy.company.com",
      "port": 1433,
      "database": "legacy_warehouse",
      "schema": null,
      "username": "etl_service",
      "status": "failed",
      "last_updated_at": "2026-05-14T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 2, "totalPages": 1 }
}

Поле	Тип	Описание
connections[].id	string	Идентификатор подключения
connections[].name	string	Отображаемое имя
connections[].db_type	string	Сырой слаг: postgresql, clickhouse, sqlserver. Не переводится
connections[].host	string	Хост или IP-адрес сервера СУБД
connections[].port	integer	Порт
connections[].database	string	Имя базы данных
connections[].schema	string | null	Схема. Возвращается только для PostgreSQL; для MS SQL схема входит в имя таблицы, для ClickHouse её роль играет имя базы — в обоих случаях null
connections[].username	string	Имя пользователя СУБД. Не является секретом и нужно для построения SQL (раздел 6 страницы API)
connections[].status	string	active, inactive, never_verified или failed
connections[].last_updated_at	string | null	Момент последнего успешного обновления схемы, ISO 8601
pagination	object	page, pageSize, total, totalPages

Ошибки

Код	HTTP	Условие
DF_API.INVALID_DB_TYPE	400	Значение db_type не входит в допустимый набор
DF_API.INVALID_STATUS	400	Значение status не входит в допустимый набор
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize больше 100
Общие ошибки	—	Раздел 4 страницы API

6.2 Детали подключения

Запрос

GET {v}/connections/{connection_id}

Параметр	Где	Тип	Обяз.	Описание
connection_id	путь	integer	да	Идентификатор подключения
include_db_schema	query	boolean	нет	По умолчанию false. true или 1 заменяет краткий массив db_tables полным объектом db_schema; любое другое значение трактуется как false
language	query	ru | en	нет	Принимается для единообразия; на ответ не влияет
format	query	json	нет	Допустимо только json

Детали

Если кэш схемы пуст или недоступен, возвращается пустой массив таблиц, а не ошибка: db_tables: [] либо db_schema.tables: [].

Ответ

200 OK, include_db_schema не задан:

{
  "id": "3821",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "host": "db.production.company.com",
  "port": 5432,
  "database": "analytics_db",
  "schema": "public",
  "username": "analytics_user",
  "status": "active",
  "last_updated_at": "2026-05-21T13:23:07.188Z",
  "db_tables": [{ "name": "fact_sales" }, { "name": "dim_customer" }]
}

200 OK, include_db_schema=true:

{
  "id": "3821",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "host": "db.production.company.com",
  "port": 5432,
  "database": "analytics_db",
  "schema": "public",
  "username": "analytics_user",
  "status": "active",
  "last_updated_at": "2026-05-21T13:23:07.188Z",
  "db_schema": {
    "connection": "Production PostgreSQL",
    "tables": [
      {
        "table_name": "fact_sales",
        "schema": "public",
        "columns": [
          { "column_name": "sale_id", "data_type": "int" },
          { "column_name": "amount", "data_type": "decimal(18,2)" }
        ]
      }
    ]
  }
}

Поле	Тип	Описание
id	string	Идентификатор подключения
name	string	Отображаемое имя
db_type	string	Сырой слаг: postgresql, clickhouse, sqlserver. Не переводится
host	string	Хост или IP-адрес сервера СУБД
port	integer	Порт
database	string	Имя базы данных
schema	string | null	Схема. Возвращается только для PostgreSQL; для MS SQL схема входит в имя таблицы, для ClickHouse её роль играет имя базы — в обоих случаях null
username	string	Имя пользователя СУБД. Не является секретом и нужно для построения SQL (раздел 6 страницы API)
status	string	active, inactive, never_verified или failed
last_updated_at	string | null	Момент последнего успешного обновления схемы, ISO 8601
db_tables	array	Краткий перечень таблиц: только имена. Присутствует, когда include_db_schema не задан
db_schema	object	Полная структура. Присутствует вместо db_tables, когда include_db_schema=true
db_schema.connection	string | null	Название подключения, которому принадлежит схема; повторяет name верхнего уровня, чтобы объект оставался самоидентифицируемым при обработке отдельно от этой обёртки
db_schema.tables[].table_name	string	Имя таблицы
db_schema.tables[].schema	string | null	Схема таблицы. null для ClickHouse, где схем нет: в его снапшоте на этом месте лежит имя базы, и наружу оно намеренно не выдаётся
db_schema.tables[].columns[].column_name	string	Имя колонки
db_schema.tables[].columns[].data_type	string	Тип колонки в строковом представлении, как он получен из СУБД

Ошибки

Код	HTTP	Условие
DF_API.CONNECTION_NOT_FOUND	404	Подключение не существует в указанной версии либо его СУБД не поддерживается публичным API. details адресует поле connection_id
Общие ошибки	—	Раздел 4 страницы API

6.3 Схема подключения

Запрос

GET {v}/connections/{connection_id}/schema

Параметр	Где	Тип	Обяз.	Описание
connection_id	путь	integer	да	Идентификатор подключения
format	query	json	нет	Допустимо только json

Детали

Возвращает только идентификацию подключения и кэшированную схему, без сетевых координат. Схема — кэшированный снимок, снятый при настройке подключения или при последнем обновлении, а не результат обращения к СУБД; момент снятия указан в last_updated_at. Обратите внимание: ключ контейнера называется schema, а не db_schema, как в эндпоинте деталей подключения; содержимое одинаково.

Ответ

200 OK

{
  "id": "3821",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "last_updated_at": "2026-05-21T13:23:07.188Z",
  "schema": {
    "connection": "Production PostgreSQL",
    "tables": [
      {
        "table_name": "fact_sales",
        "schema": "public",
        "columns": [
          { "column_name": "sale_id", "data_type": "int" },
          { "column_name": "sale_date", "data_type": "datetime" }
        ]
      }
    ]
  }
}

Поле	Тип	Описание
id, name, db_type	string	Идентификация подключения
last_updated_at	string | null	Момент снятия снимка схемы, ISO 8601
schema	object	Кэшированная структура
schema.connection	string | null	Название подключения, которому принадлежит схема, — повторяет name верхнего уровня. Тот же объект с тем же полем в эндпоинте деталей подключения называется db_schema; в v1 поля connection нет
schema.tables[]	array	Таблицы со списком колонок; состав полей и правила для schema у таблицы table_name, schema таблицы (null для ClickHouse, где схем нет), columns[] из column_name и data_type

Ошибки

Код	HTTP	Условие
DF_API.CONNECTION_NOT_FOUND	404	Подключение не существует в указанной версии либо его СУБД не поддерживается публичным API. details адресует поле connection_id
Общие ошибки	—	Раздел 4 страницы API