Когда вызывать: ПЕРЕД seaf_jsonata_query, когда не уверены в форме результата запроса. Возвращает тип (array/object/scalar/missing), count по всему результату, поля с покрытием present_in k/n по первым 100 элементам и до 3 примеров (≤1500 символов каждый); схема строится по выборке — это разведка, а не полная схема. Терминальные агрегаты ($count, $sum) — скаляр в value. Дальше: seaf_jsonata_query с уточнённым запросом.

Когда вызывать: нужна структура ОДНОГО раздела без образцов — атрибуты с частотой, исходящие/входящие поля-связи, примеры ID. Для образцов данных и нескольких разделов сразу используйте inspect_sections. Дальше: list_entities (выборка по фильтрам) или describe_query_result (разведка перед JSONata).

Когда вызывать: известно только примерное название объекта (система, сервис, человек) — поиск по подстроке в ID/title/description всех разделов (или одного). Возвращает total и items {section, id, title}. Когда раздел и условия по полям известны точно, эффективнее list_entities. Дальше: get_entity или get_relations по найденному id.

Когда вызывать: перед написанием JSONata — взять проверенный пример похожего запроса (keyword-поиск по вопросу, группе, разделам и тексту выражения; русские словоформы совпадают по префиксу). Возвращает до limit (по умолчанию 5) примеров {id, question, sections, expression, explanation}; записи с template=true требуют подстановки реального ID. При настроенном SEAF_METAMODEL_PATH после проверенных примеров идут фрагменты YAML метамодели с пометкой файла. Дальше: seaf_jsonata_query с адаптированным выражением.

Когда вызывать: нужно понять, через какие поля и разделы связаны два раздела (например, people и products), прежде чем писать JOIN. Возвращает до 10 кратчайших маршрутов (до 5 шагов): каждый шаг — from_section, field, to_section, direction (out/in); данные сущностей не возвращаются, JOIN не выполняется. via_sections ограничивает промежуточные разделы. Дальше: find_jsonata_examples (группа relations) или seaf_jsonata_query.

Когда вызывать: нужен именованный датасет представлений ЦЕЛИКОМ (только seaf.company.ds., например seaf.company.ds.people: записи людей с полями title/ФИО, role, department и техническими id/link_to_card). Возвращает объект объектов (ключ — ID записи). Для выборок по датасету и служебных seaf.ds. — query_dataset. Дальше: query_dataset с фильтром.

Когда вызывать: известен точный ID объекта (например example.app_system.hotel_booking). Возвращает раздел и все атрибуты объекта. ID неизвестен — сначала find_entities. Дальше: get_relations для связей объекта.

Когда вызывать: проверить доступность портала (health-check). Возвращает {"message": "app is alive"}. Дальше: list_sections.

Endpoint: GET /health

Когда вызывать: нужны связи объекта — outgoing (на что он ссылается) и incoming (кто ссылается на него: подсистемы — incoming is_part_of, компоненты — incoming realizes_system, таблицы — incoming system). Возвращает группы по полю с count, до limit элементов и title. У крупных объектов сужайте direction/field. Дальше: get_entity на связанном id.

Когда вызывать: увидеть ошибки валидации, найденные при загрузке манифеста. Дальше: зависит от найденных проблем.

Endpoint: GET /seaf-core/api/core/storage/problems/

Когда вызывать: узнать версию ядра портала и хэш манифеста. Дальше: list_sections.

Endpoint: GET /seaf-core/api/core/storage/versions

Когда вызывать: нужны структура И образцы сразу 1-5 разделов, например перед запросом со связями между типами. Возвращает по каждому разделу count, атрибуты, поля-связи и до sample_limit (1-3, по умолчанию 2) ограниченных образцов; раздел целиком не выгружается. Для одного раздела без образцов достаточно describe_section. Дальше: seaf_jsonata_query со связывающим запросом. При включённом API_MIN_INTERVAL_SECONDS время ответа растёт пропорционально числу разделов.

Когда вызывать: нужны объекты раздела с точными фильтрами по полям (eq/ne/contains/missing/exists) и пагинацией — выполняется на портале. Пример: системы без стейкхолдеров — where=[{field:'stakeholders',op:'missing'}]. Поля через точку (stakeholders.name); для массивов eq/contains срабатывает на любой элемент; булевы — 'true'/'false'. Не знаете раздел — list_sections; ищете по примерному названию — find_entities. Возвращает {section,total,offset,items}. Дальше: get_entity по id из items.

Когда вызывать: в начале работы или когда неизвестно, в каком разделе искать данные. Возвращает разделы seaf.company.* с числом объектов и описанием. Дальше: inspect_sections (структура и образцы нескольких разделов) или describe_section (один раздел без образцов).

Когда вызывать: нужны понятия метамодели SEAF, смысл отношений и проверенные приёмы JSONata (чек-лист, паттерны, ловушки). Возвращает текст справочника. Дальше: list_sections.

Когда вызывать: нужна выборка JSONata поверх именованного датасета (корневой $ — данные датасета; для манифеста модели — seaf_jsonata_query). origin — ID датасета или {алиас: dataset_id} (тогда $ — мапа, датасет как $."алиас"); source оборачивается в (...) автоматически. Возвращает результат выражения; доступны любые датасеты, включая seaf.ds.* — сужайте выборку: ответ считается на портале целиком. Дальше: seaf_jsonata_query, если данных нет в датасете.

Когда вызывать: нужен произвольный JSONata по манифесту модели (корневой $ — манифест); для датасетов — query_dataset, для разведки формы результата — describe_query_result. Возвращает результат выражения; ошибки JSONata (S0xxx/T0xxx) приходят с подсказкой по исправлению. Дальше: get_entity/list_entities для типовых выборок без JSONata.

Endpoint: POST /seaf-core/api/core/storage/jsonata