Публичный API v1

Публичный API v1 — часть публичного API DataForge только для чтения: содержимое РПИ, модель данных и витрины. Аутентификация, общие соглашения и коды ошибок описаны на странице API.

1 Публичный DF API — содержимое РПИ (df-api/v1)

Базовый путь: /df-api/v1. Аутентификация: X-Api-Key. Все эндпоинты — read-only и контролируются лицензией компании (раздел 5 страницы API). Эта группа объединяет эндпоинты доступа к проектам, версиям и содержимому РПИ (показатели, измерения, факты); эндпоинты модели данных и витрин описаны в разделе 9.8. Эндпоинты содержимого РПИ монтируются прямо под версией — …/versions/{version_id}/measures, без промежуточного сегмента /rmd/.

Общее для всех эндпоинтов группы: видны только проекты, доступные владельцу ключа (раздел 2.2 страницы API); page и pageSize в этой группе не ограничиваются (раздел 3.2 страницы API); format=xlsx вместо тела JSON возвращает { "downloadUrl": "<подписанная ссылка, действует 15 минут>" } (раздел 3.5 страницы API).

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

Запрос

GET /df-api/v1/projects

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

Детали

Список фильтруется по проектам, доступным владельцу ключа; недоступные проекты исключаются из страницы и из total. Параметр language не принимается — в ответе нет локализуемых полей.

Ответ

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 (раздел 3.2 страницы API)

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

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

Запрос

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

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

Детали

Мягко удалённые версии не возвращаются. Проект, недоступный владельцу ключа, отвечает 404 — факт существования не раскрывается.

Ответ

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).

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/measures

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

Детали

Состав возвращаемых ключей соответствует колоночной раскладке таблицы показателей РПИ: каждая строка содержит все колонки, незаполненные — как null. Поля-справочники (measure_type, display_data_type, status, relevance, …) возвращаются как локализованные подписи (Base / Calculated, Number, …), а не как слаги. В формульных полях ссылки заменены с числовых ID на читаемые имена. original_source и original_object — свободный текст из РПИ.

Ответ

200 OK

{
  "measures": [
    {
      "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[].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).

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/dimensions

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

Детали

Каждая строка содержит все колонки таблицы измерений РПИ, незаполненные — как null; поля-справочники (dimension_type, display_data_type, status, …) возвращаются как локализованные подписи, ссылки в формулах — как читаемые имена. source_data_type вычисляется из connected_source: API разбирает объект источника (db, schema, table, column) и подставляет тип колонки из закешированной схемы соответствующего подключения. Возвращается null, если связанный источник не задан, не разрешается на колонку или для версии нет ни одной строки с connected_source. connected_source — объект источника из раздела 3.6 страницы API без поля connection (v1).

Ответ

200 OK

{
  "dimensions": [
    {
      "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": { "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[].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[].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).

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/facts

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

Детали

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

Ответ

200 OK

{
  "facts": [
    {
      "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": { "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[].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[].report_for_verification, comment, responsible_for_data	string | null	Текстовые колонки
facts[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
pagination	object	total, page, pageSize, totalPages

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

1.6 Получение полного РПИ (содержимое)

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/rmd

Параметр	Где	Тип	Обяз.	Описание
project_id	путь	integer	да	Идентификатор проекта
version_id	путь	integer	да	Идентификатор версии
language	query	ru | en	нет	Язык подписей полей-справочников
format	query	json | xlsx	нет	Формат вывода. По умолчанию json

Детали

В df-api/v1 этот путь — сводный экспорт РПИ: показатели, измерения и факты вместе с моделью данных (группы измерений, таблицы фактов, связи), без пагинации. Он возвращает полный снимок метаданных версии с отметкой времени exported_at и предназначен для внешних каталогов и полной синхронизации состояния.

Ответ

200 OK

{
  "project": {
    "id": "12",
    "name": "Sales Analytics",
    "description": "Production sales warehouse"
  },
  "version": {
    "id": "33",
    "name": "Q4 2025",
    "is_global": true
  },
  "measures": [
    {
      "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": [
    {
      "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": { "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": [
    {
      "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": { "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": {
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"],
      "created_at": null
    }
  ],
  "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": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "Многие-к-одному",
      "created_at": null
    }
  ],
  "exported_at": "2026-05-05T08:30:00Z"
}

Поле	Тип	Описание
project	object	id, name, description проекта (id — строкой)
version	object	id, name, is_global версии
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[].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[].comment, responsible_for_data	string | null	Текстовые колонки
dimensions[].value_options	string | null	Колонка допустимых значений
dimensions[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
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[].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	Объект источника { db, schema, table, column }
dimension_groups[].dimensions[]	array	Члены группы, упорядочены по уровню иерархии level; data_type — локализованный отображаемый тип, physical_column — колонка в исходной таблице
dimension_groups[].related_fact_tables[]	string	ID таблиц фактов, ссылающихся на группу; их конфигурация доступна через эндпоинты таблиц фактов
dimension_groups[].created_at	null	В v1 не заполняется
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[].id	string	Идентификатор связи
relationships[].source_fact_table	object	id, name таблицы фактов с внешним ключом
relationships[].target_dimension_group	object	id, name группы измерений с первичным ключом
relationships[].foreign_key, primary_key	object | null	Объекты источника соединения
relationships[].relationship_type	string	Локализованная подпись кратности
relationships[].created_at	null	В v1 не заполняется
exported_at	string	Момент снятия снимка, ISO 8601

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

2 Публичный DF API — модель данных и витрины (df-api/v1)

Базовый путь: /df-api/v1. Аутентификация: X-Api-Key. Все эндпоинты — read-only.

Эта группа сгруппирована в шесть логических областей: витрины, подключения, группы измерений, таблицы фактов, связи и сводный экспорт РПИ. Эндпоинты витрин и подключений возвращают только JSON; эндпоинты групп измерений, таблиц фактов, связей и сводного экспорта дополнительно поддерживают ?format=xlsx (см. раздел 3.5 страницы API). Эндпоинты содержимого РПИ (проекты, версии, показатели, измерения, факты) описаны в разделе 9.7.

Общее для всех эндпоинтов группы: {project_id} и {version_id} — обязательные целочисленные параметры пути; проект, недоступный владельцу ключа, отвечает 404; списочные эндпоинты отклоняют pageSize больше 100 с 400 DF_API.PAGE_SIZE_EXCEEDED и страничат с ключом total_pages (а не totalPages, раздел 3.2 страницы API). Объекты источника (primary_key, foreign_key) содержат db, schema, table, column и не содержат поля connection (раздел 3.6 страницы API).

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts

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

Детали

type возвращается как локализованная подпись (зависит от language / Accept-Language), например "С группировкой" для ru, тогда как фильтр принимает сырой слаг. merge_type — всегда сырой слаг (union / join), не локализуется. Если у витрины нет описания, ключ description отсутствует (v2 возвращает null). Только JSON — format не принимается.

Ответ

200 OK

{
  "data_marts": [
    {
      "id": "57",
      "name": "Monthly Sales Mart",
      "description": "Aggregated by month and region",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "type": "С группировкой",
      "merge_type": "union",
      "source_fact_table_count": 2,
      "has_physical_view": true
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 45, "total_pages": 3 }
}

Поле	Тип	Описание
data_marts[].id	string	Идентификатор витрины
data_marts[].name	string	Отображаемое имя
data_marts[].description	string	Описание; ключ опускается, если описание не задано
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, total_pages

Ошибки

Код	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

2.2 Получение деталей витрины

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts/{data_mart_id}

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

Детали

Возвращает полную конфигурацию витрины. Для транспонированных витрин (type = with_grouping_and_pivoting) ответ дополнительно содержит selected_measure_attributes, в котором неявный ключ транспонирования Measure name всегда добавлен в начало:

"selected_measure_attributes": [
  { "attribute_id": "3",  "attribute_name": "Measure name" },
  { "attribute_id": "27", "attribute_name": "Measure description" }
]

Ответ

200 OK

{
  "id": "57",
  "name": "Monthly Sales Mart",
  "description": "Aggregated by month and region",
  "owner": "Pavel Shalavin",
  "created_at": "2026-04-15T08:30:00Z",
  "type": "with_grouping",
  "merge_type": "union",
  "source_fact_tables": [
    { "id": "11", "name": "fact_sales", "description": "Primary sales facts" }
  ],
  "selected_measures": [
    {
      "instance_id": "204",
      "measure_id": "501",
      "measure_name": "Total revenue",
      "description": "Gross revenue",
      "formula": "SUM([Amount])",
      "data_type": "Numeric",
      "display_name": "Revenue",
      "aggregation_configuration": { "type": "default", "group_by_fields": [] },
      "source_fact_table_id": "11"
    }
  ],
  "selected_facts": [
    {
      "fact_id": "611",
      "fact_name": "Order line",
      "data_type": "Numeric",
      "display_name": "Order line",
      "include_in_result": true,
      "filter_condition": null,
      "source_fact_table_id": "11"
    }
  ],
  "selected_dimensions": [
    {
      "dimension_id": "722",
      "dimension_name": "Region",
      "description": "Geographic region",
      "data_type": "Text",
      "display_name": "Region",
      "include_in_result": true,
      "filter_condition": null,
      "source_fact_table_id": "11",
      "source_dimension_group_id": "9",
      "source_dimension_group_name": "Geography"
    }
  ],
  "physical_view": {
    "exists": false,
    "type": null, "database": null, "schema": null, "name": null, "created_at": null
  }
}

Поле	Тип	Описание
id	string	Идентификатор витрины
name	string	Отображаемое имя
description	string	Описание; ключ опускается, если описание не задано
owner	string	Имя владельца либо e-mail, если имя не заполнено
created_at	string	Дата создания, ISO 8601
type	string	Локализованная подпись типа витрины
merge_type	string | null	union / join; null для витрин на одной таблице фактов
source_fact_tables[]	array	Таблицы фактов-источники: id, name, description
selected_measures[].instance_id	string	Уникальный идентификатор экземпляра показателя в витрине (один показатель может входить несколько раз с разной настройкой агрегации)
selected_measures[].measure_id	string	Идентификатор показателя в РПИ
selected_measures[].formula	string | null	Формула расчётного показателя
selected_measures[].data_type	string	Локализованная подпись типа данных
selected_measures[].display_name	string	Имя колонки в витрине
selected_measures[].aggregation_configuration.type	string	default, none, custom или global
selected_measures[].aggregation_configuration.group_by_fields	array	Идентификаторы column-value полей группировки показателя
selected_facts[], selected_dimensions[]	array	Факты и измерения, используемые витриной
…include_in_result	boolean	false — элемент используется только для фильтрации и не попадает в проекцию
…filter_condition	string | null	Выражение фильтра с заменой column-value-ссылок на имена; null, если фильтра нет
selected_dimensions[].source_dimension_group_id / source_dimension_group_name	string | null	Разрешаются по модели данных, даже если группа измерений не указана явно в атрибутах витрины
physical_view	object	Метаданные материализованного объекта: exists, type (локализованная подпись вида объекта), database (сырой слаг), schema, name, created_at; поле connection здесь не возвращается

Ошибки

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

2.3 Получение метаданных физического представления

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts/{data_mart_id}/view

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

Детали

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

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

Ответ

200 OK

{
  "exists": true,
  "type": "materialized_view",
  "database": "postgresql",
  "schema": "marts",
  "name": "monthly_sales",
  "created_at": "2026-04-21T09:00:00Z",
  "connection": { "id": "3", "name": "Production PostgreSQL", "db_type": "postgres" }
}

Поле	Тип	Описание
exists	boolean	Материализован ли объект
type	string | null	Локализованная подпись вида физического объекта (зависит от language); сырые слаги: regular_view, materialized_view, table
database	string | null	Сырой слаг типа СУБД: postgresql, clickhouse, sqlserver (не локализуется)
schema	string | null	Схема объекта. В v1 для ClickHouse здесь возвращается имя базы данных; v2 возвращает null
name	string | null	Имя объекта в СУБД
created_at	string | null	Дата создания объекта, ISO 8601
connection	object | null	id, name, db_type подключения, в котором создан объект; без учётных данных

Ошибки

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

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

Запрос

POST /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts/{data_mart_id}/generate-sql

Параметр	Где	Тип	Обяз.	Описание
project_id	путь	integer	да	Идентификатор проекта
version_id	путь	integer	да	Идентификатор версии
data_mart_id	путь	integer	да	Идентификатор витрины
limit	тело	integer > 0	нет	Добавляет ограничение строк в синтаксисе диалекта: LIMIT n OFFSET m для PostgreSQL/ClickHouse, OFFSET m ROWS FETCH NEXT n ROWS ONLY для MS SQL
offset	тело	integer ≥ 0	нет	Смещение строк; действует только вместе с limit. offset без limit игнорируется

Тело запроса (необязательное):

{ "limit": 100, "offset": 0 }

Детали

Генерирует выражение SQL SELECT витрины. SQL только формируется и возвращается — он не выполняется, ничего не сохраняется. Для MS SQL, если в SQL отсутствует ORDER BY, сервис добавляет ORDER BY (SELECT NULL) для синтаксической валидности OFFSET … FETCH NEXT.

Эндпоинт отвечает 201 Created — стандартный статус POST в v1; тот же эндпоинт в v2 отвечает 200 и читает limit / offset из query-строки.

Если генерация SQL завершается ошибкой (повреждённые формулы или отсутствие привязок), ответ остаётся успешным (тот же статус 201), а сбой описывается в validation_errors. Это позволяет клиенту отличить «витрина не может сейчас сформировать SQL» от «витрины не существует» (404). В v1 поле message содержит сырой ключ причины (например, FORMULA.SOURCE_NOT_FOUND_FOR_METRIC); локализованный текст возвращает только v2.

Ответ

201 Created

{
  "sql_script": "SELECT ...\nFROM ...\nGROUP BY ...\nLIMIT 100 OFFSET 0",
  "target_db_type": "postgres",
  "validation_errors": []
}

При ошибке генерации:

{
  "sql_script": "",
  "target_db_type": null,
  "validation_errors": [
    { "code": "SQL_GENERATION_FAILED", "message": "FORMULA.SOURCE_NOT_FOUND_FOR_METRIC" }
  ]
}

Поле	Тип	Описание
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	Сырой ключ причины (v1)

Ошибки

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

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/connections

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

Детали

Учётные данные не возвращаются никогда (раздел 6 страницы API). schema возвращается только для PostgreSQL: для MS SQL Server схема включается в имя таблицы в других местах системы, для ClickHouse вместо схемы используется имя базы данных — в обоих случаях null. Подключения к СУБД, не поддерживаемым публичным API (например MySQL), исключаются из списка и из total.

status рассчитывается из внутреннего состояния: приоритет имеет never_verified — без отметки об успешном обновлении система не может утверждать состояние; failed соответствует внутреннему UPDATE_ERROR; inactive соответствует DISABLED; в остальных случаях статус — active.

Ответ

200 OK

{
  "connections": [
    {
      "id": "1",
      "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-04-15T08:30:00Z"
    },
    {
      "id": "2",
      "name": "Legacy SQL Server",
      "db_type": "sqlserver",
      "host": "sqlserver.legacy.company.com",
      "port": 1433,
      "database": "legacy_warehouse",
      "schema": null,
      "username": "etl_service",
      "status": "active",
      "last_updated_at": "2026-04-14T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 8, "total_pages": 1 }
}

Поле	Тип	Описание
connections[].id	string	Идентификатор подключения
connections[].name	string	Отображаемое имя (уникально в пределах версии)
connections[].db_type	string	Сырой слаг: postgresql, clickhouse, sqlserver
connections[].host, port, database	string / integer / string	Сетевые координаты
connections[].schema	string | null	Схема подключения; только для PostgreSQL
connections[].username	string	Имя пользователя СУБД (не секрет)
connections[].status	string	active, inactive, never_verified, failed
connections[].last_updated_at	string | null	Момент последнего успешного обновления снимка схемы
pagination	object	page, pageSize, total, total_pages

Ошибки

Код	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

2.6 Получение деталей подключения

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/connections/{connection_id}

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

Детали

db_tables[] содержит только name. db_schema.tables[] содержит table_name, schema (собственная схема таблицы; null для ClickHouse, где схем нет) и columns[] из column_name и data_type. Один и тот же объект структуры в этом эндпоинте называется db_schema, а в эндпоинте схемы (GET …/connections/{connection_id}/schema) — schema; состав таблиц в обоих случаях одинаков. В v1 объект структуры не содержит поля connection — его добавляет только v2. Схема — закешированный снимок, снятый при настройке подключения или ручном обновлении; момент снятия фиксирует last_updated_at.

Ответ

200 OK — include_db_schema=false:

{
  "id": "1",
  "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-04-15T08:30:00Z",
  "db_tables": [ { "name": "fact_sales" }, { "name": "dim_customer" } ]
}

200 OK — include_db_schema=true:

{
  "id": "1",
  "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-04-15T08:30:00Z",
  "db_schema": {
    "tables": [
      {
        "table_name": "fact_sales",
        "schema": "public",
        "columns": [
          { "column_name": "sale_id", "data_type": "int" },
          { "column_name": "sale_date", "data_type": "datetime" },
          { "column_name": "amount", "data_type": "decimal(18,2)" }
        ]
      }
    ]
  }
}

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

Ошибки

Код	HTTP	Условие
DF_API.CONNECTION_NOT_FOUND	404	Подключение не существует в указанной версии
Общие ошибки	—	Раздел 4 страницы API

2.7 Получение схемы подключения

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/connections/{connection_id}/schema

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

Детали

Возвращает только закешированную схему (таблицы и колонки) подключения, без сетевых координат. Ключ верхнего уровня здесь называется schema (в эндпоинте деталей подключения тот же объект называется db_schema); его состав идентичен: tables[] с table_name, schema таблицы (null для ClickHouse) и columns[] из column_name и data_type.

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

Ответ

200 OK

{
  "id": "1",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "last_updated_at": "2026-04-15T08:30:00Z",
  "schema": {
    "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	Момент снятия снимка
schema.tables[].table_name	string	Имя таблицы
schema.tables[].schema	string | null	Схема таблицы; null для ClickHouse
schema.tables[].columns[].column_name, data_type	string	Имя и тип колонки, как они получены из СУБД

Ошибки

Код	HTTP	Условие
DF_API.CONNECTION_NOT_FOUND	404	Подключение не существует в указанной версии
Общие ошибки	—	Раздел 4 страницы API

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/dimension-groups

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

Детали

Возвращает группы измерений (справочники) версии проекта с их первичным ключом, составом измерений и идентификаторами таблиц фактов, ссылающихся на группу. primary_key — объект источника из раздела 3.6 страницы API без connection либо null, если у группы не разрешён физический ключ; v1 отдаёт сохранённую схему как есть. created_at присутствует, но для групп измерений не заполняется и возвращается как null.

Ответ

200 OK

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

Поле	Тип	Описание
dimension_groups[].id, name, description	string / string / string | null	Идентификация
dimension_groups[].primary_key	object | null	Объект источника { db, schema, table, column }
dimension_groups[].dimensions[]	array	Члены группы, упорядочены по уровню иерархии level; data_type — локализованный отображаемый тип, physical_column — колонка в исходной таблице
dimension_groups[].related_fact_tables[]	string	ID таблиц фактов, ссылающихся на группу; их конфигурация доступна через эндпоинты таблиц фактов
dimension_groups[].created_at	null	В v1 не заполняется
pagination	object	page, pageSize, total, total_pages

Ошибки

Код	HTTP	Условие
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize больше 100
Общие ошибки	—	Раздел 4 страницы API

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/dimension-groups/{dimension_group_id}

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

Детали

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

Ответ

200 OK

{
  "id": "9",
  "name": "Geography",
  "description": "Geographic regions and countries",
  "primary_key": {
    "db": "analytics_db",
    "schema": "public",
    "table": "dim_geography",
    "column": "region_id"
  },
  "related_fact_tables": [
    { "fact_table_id": "11", "fact_table_name": "fact_sales", "foreign_key_column": "region_id" },
    { "fact_table_id": "14", "fact_table_name": "fact_inventory", "foreign_key_column": "region_id" }
  ],
  "created_at": null,
  "updated_at": null
}

Поле	Тип	Описание
id, name, description	string / string / string | null	Идентификация
primary_key	object | null	Объект источника { db, schema, table, column }
related_fact_tables[]	array	fact_table_id, fact_table_name, foreign_key_column каждой таблицы фактов, соединённой с группой
created_at, updated_at	null	В v1 не заполняются

Ошибки

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

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/fact-tables

Параметр	Где	Тип	Обяз.	Описание
project_id	путь	integer	да	Идентификатор проекта
version_id	путь	integer	да	Идентификатор версии
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, "total_pages": 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, total_pages

Ошибки

Код	HTTP	Условие
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize больше 100
Общие ошибки	—	Раздел 4 страницы API

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/fact-tables/{fact_table_id}

Параметр	Где	Тип	Обяз.	Описание
project_id	путь	integer	да	Идентификатор проекта
version_id	путь	integer	да	Идентификатор версии
fact_table_id	путь	integer	да	Идентификатор таблицы фактов
language	query	ru | en	нет	Язык подписей 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). В v1 поле типа данных элемента называется data_type (в v2 — display_data_type, раздел 1 страницы Публичный API v2).

Ответ

200 OK

{
  "id": "11",
  "name": "fact_sales",
  "description": "Primary sales facts",
  "owner": "Pavel Shalavin",
  "created_at": "2026-04-15T08:30:00Z",
  "updated_at": "2026-04-21T09:00:00Z",
  "measures": [
    {
      "id": "501",
      "name": "Total revenue",
      "description": "Gross revenue",
      "formula": "SUM([Amount])",
      "data_type": "Numeric",
      "measure_type": "base",
      "dependencies": null
    }
  ],
  "dimensions": [
    {
      "id": "801",
      "name": "Sale date",
      "description": "Calendar date of the sale",
      "data_type": "Date",
      "physical_column": "sale_date",
      "is_from_dimension_group": false,
      "dimension_group_id": null
    }
  ],
  "facts": [
    {
      "id": "611",
      "name": "Order line",
      "description": null,
      "data_type": "Numeric",
      "fact_type": "primary",
      "formula": null,
      "physical_column": "amount"
    }
  ],
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "foreign_key": { "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[].measure_type	string	base (источник напрямую) или calculated (производный по формуле)
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	Группа, из которой унаследовано измерение
facts[].fact_type	string	primary, derived или constant
…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.12 Список связей

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/relationships

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

Детали

Возвращает связи внешних ключей между таблицами фактов и группами измерений в версии проекта. relationship_type описывает кратность от источника (таблицы фактов) к цели (группе измерений); в v1 это локализованная подпись (Many-to-one / Многие-к-одному в зависимости от language) — слаг many_to_one возвращает только v2. created_at в v1 не заполняется (null). foreign_key и primary_key могут быть null, если соответствующий маппинг неполный; в этом случае связь видна, но не пригодна для построения SQL-join'а.

Ответ

200 OK

{
  "relationships": [
    {
      "id": "1101",
      "source_fact_table": { "id": "11", "name": "fact_sales" },
      "target_dimension_group": { "id": "9", "name": "Geography" },
      "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "Многие-к-одному",
      "created_at": null
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 4, "total_pages": 1 }
}

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

Ошибки

Код	HTTP	Условие
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize больше 100
Общие ошибки	—	Раздел 4 страницы API

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/relationships/{relationship_id}

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

Детали

Возвращает одну связь с описательными полями обеих сторон; целевая группа измерений дополнительно несёт свой primary_key.

Ответ

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": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" }
  },
  "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
  "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
  "relationship_type": "Многие-к-одному",
  "created_at": null,
  "updated_at": null
}

Поле	Тип	Описание
source_fact_table, target_dimension_group	object	Обе стороны с description; сторона группы повторяет свой primary_key
id	string	Идентификатор связи
foreign_key, primary_key	object | null	Объекты источника соединения
relationship_type	string	Локализованная подпись кратности
created_at, updated_at	null	В v1 не заполняются

Ошибки

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

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

Запрос

GET /df-api/v1/projects/{project_id}/versions/{version_id}/rmd

Параметр	Где	Тип	Обяз.	Описание
project_id	путь	integer	да	Идентификатор проекта
version_id	путь	integer	да	Идентификатор версии
language	query	ru | en	нет	Язык подписей полей-справочников
format	query	json | xlsx	нет	По умолчанию json. xlsx формирует шесть листов: Measures, Dimensions, Facts, Dimension Groups, Fact Tables, Relationships

Детали

Возвращает полный снимок метаданных версии проекта — содержимое РПИ (показатели, измерения, факты) и модель данных (группы измерений, таблицы фактов, связи) — в одном payload без пагинации, с отметкой времени exported_at. Предназначен для внешних каталогов и полной синхронизации состояния. Для отдельных постраничных секций РПИ используйте эндпоинты раздела 9.7.

Ответ

200 OK

{
  "project": {
    "id": "12",
    "name": "Sales Analytics",
    "description": "Production sales warehouse"
  },
  "version": {
    "id": "33",
    "name": "Q4 2025",
    "is_global": true
  },
  "measures": [
    {
      "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": [
    {
      "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": { "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": [
    {
      "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": { "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": {
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"],
      "created_at": null
    }
  ],
  "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": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "Многие-к-одному",
      "created_at": null
    }
  ],
  "exported_at": "2026-05-05T08:30:00Z"
}

Поле	Тип	Описание
project	object	id, name, description проекта (id — строкой)
version	object	id, name, is_global версии
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[].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[].comment, responsible_for_data	string | null	Текстовые колонки
dimensions[].value_options	string | null	Колонка допустимых значений
dimensions[].status, relevance, required, visibility	string | null	Локализованные подписи справочников
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[].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	Объект источника { db, schema, table, column }
dimension_groups[].dimensions[]	array	Члены группы, упорядочены по уровню иерархии level; data_type — локализованный отображаемый тип, physical_column — колонка в исходной таблице
dimension_groups[].related_fact_tables[]	string	ID таблиц фактов, ссылающихся на группу; их конфигурация доступна через эндпоинты таблиц фактов
dimension_groups[].created_at	null	В v1 не заполняется
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[].id	string	Идентификатор связи
relationships[].source_fact_table	object	id, name таблицы фактов с внешним ключом
relationships[].target_dimension_group	object	id, name группы измерений с первичным ключом
relationships[].foreign_key, primary_key	object | null	Объекты источника соединения
relationships[].relationship_type	string	Локализованная подпись кратности
relationships[].created_at	null	В v1 не заполняется
exported_at	string	Момент снятия снимка, ISO 8601

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