Context Layer
Renta Context Layer позволяет AI-ассистентам запрашивать данные из моделей Google BigQuery и ClickHouse через MCP-инструмент context_layer. Ассистент выбирает измерения, меры и фильтры. Renta составляет SQL и выполняет его через подключение модели к хранилищу.
Измерения задают группировку и фильтрацию, например по стране или дате заказа. Меры задают расчёты: сумму выручки, количество заказов и др угие агрегаты. Вы настраиваете их в модели данных.
Перед началом работы
Подключите Renta MCP Server к ассистенту и подготовьте модель данных.
- Откройте модель в Tools > Context layers. Если модели ещё нет, создайте её по инструкции для BigQuery или ClickHouse.
- Выберите scope AI agents only или AI agents & Reverse ETL. Модели со scope Reverse ETL only не появляются в
list_models. - На вкладке Access предоставьте доступ пользователям или группам воркспейса, которые будут запрашивать модель. У владельцев воркспейса доступ уже есть. Подробнее на странице Доступ к моделям.
- Настройте меры и метаданные, как описано ниже, и нажмите Save changes.
Запросы используют воркспейс и пользователя, указанных в токене. Renta проверяет членство в воркспейсе и доступ к модели при каждом запросе. Четыре действия context_layer читают данные и не изменяют записи в хранилище.
Настройка мер
На вкладке Measures включите для каждой колонки агрегации, доступные ассистенту. Например, SUM для revenue добавляет меру revenue_sum. Колонка остаётся доступной как измерение, даже если все её агрегации выключены.
Для числовых колонок доступны все восемь переключателей. Для остальных типов доступны COUNT и DISTINCT.
| Переключатель | Имя меры | Что возвращает |
|---|---|---|
| SUM | revenue_sum | Сумма по колонке. Только числовые колонки. |
| AVG | revenue_avg | Среднее по колонке. Только числовые колонки. |
| MIN | revenue_min | Минимальное значение. Только числовые колонки. |
| MAX | revenue_max | Максимальное значение. Только числовые колонки. |
| MEDIAN | revenue_median | Приблизительная медиана. Только числовые колонки. |
| P95 | revenue_p95 | Приблизительный 95-й процентиль. Только числовые колонки. |
| COUNT | order_id_count | Количество зна чений колонки, отличных от null. Любой тип колонки. |
| DISTINCT | order_id_distinct | Количество различных значений колонки. Любой тип колонки. |
Renta также добавляет count для подсчёта строк. Если у модели задан уникальный ключ, мера unique_count считает его различные значения.
Выбирайте агрегации с учётом того, что хранится в одной строке. Если строка соответствует заказу, revenue_sum может считать общую выручку. Если строки уже содержат средние или проценты, сначала определите, как учитывать их вес. Среднее дневных средних обычно не равно среднему по всем заказам.
Применение агрегаций к нескольким колонкам
Выберите колонки, чтобы изменить их агрегации за один раз.
- Отметьте нужные колонки. Флажок в заголовке таблицы выбирает строки, которые сейчас видны.
- Нажмите агрегацию на панели действий. Она включится для выбранных колонок, которые её поддерживают. Если она уже включена для всех подходящих колонок, нажатие выключит её.
- Нажмите Clear, чтобы убрать все агрегации у выбранных колонок, или Show Selected, чтобы скрыть остальные строки.
Описание модели
На вкладке Metadata задайте имя и описание модели. Оба поля доступны в list_models и describe_model. Ассистент использует их, чтобы выбрать модель и понять результаты запроса.
Укажите, что представляет одна строка, за какой период есть данные, когда они обновляются и в каких единицах или валюте хранятся. Добавьте исключения и правила, которые влияют на ответ. Например:
Одна строка соответствует завершённому заказу с идентификатором order_id.
Данные с 2024-01-01 обновляются ежедневно в 06:00 UTC по предыдущий день включительно.
Суммы в USD без НДС. Тестовые заказы исключены.
Используйте модель для выручки и количества заказов по странам, каналам и кампаниям.
Для возвратов используйте модель payments. Здесь возвращённые заказы сохраняют исходную сумму.Замените даты и правила в примере на те, которые действуют в вашей модели.
В разделе Column descriptions на вкладке Metadata опишите, что хранится в каждом поле. Context Layer передаёт эти описания AI-ассистенту вместе со схемой модели. Правила, общие для нескольких полей, укажите в Description модели.
Если для поля также задано описание через REST API, ассистент получит ве рсию из API.
Запрос данных
Вызовите list_models, чтобы найти модель, затем describe_model, чтобы получить имена её полей. Если перед запросом нужно проверить значения поля, вызовите sample_field.
| Действие | Параметры | Результат |
|---|---|---|
list_models | Необязательный source_id | Доступные модели: идентификаторы, имена, описания и типы хранилищ. |
describe_model | model_id | Определение модели, измерения, меры и семантические переопределения. |
sample_field | model_id, field_name | Значения или статистика одного поля и статистика запроса. |
run_query | model_id и выбранные поля | Строки результата, метаданные колонок и статистика запроса. |
Первые два действия читают сохранённые метаданные. Действия sample_field и run_query читают хранилище.
Проверка значений поля
Вызовите sample_field, чтобы проверить значения перед составлением фильтра. Например, колонка страны может содержать US, а не United States.
{
"action": "sample_field",
"model_id": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60",
"field_name": "country",
"values_limit": 10
}Для строковых измерений values_limit задаёт количество значений в ответе: по умолчанию 50, максимум 500. Необязательный параметр search ищет по префиксу без учёта регистра. Его длина ограничена 100 символами.
| Тип поля | Результат |
|---|---|
| Строка | Частые значения с количеством вхождений и приблизительное число различных значений. |
| Логическое значение | Количество строк со значениями true, false и null. |
| Число | Минимум, максимум и 10-й, 50-й, 90-й процентили. |
| Время | Самое раннее и позднее значение, количество различных дней с данными. |
| Числовая мера | Статистика числового поля и значение агрегата. |
| Мера COUNT | Общее количество строк, включая строки с null в выбранной колонке. В отличие от sample_field, run_query исключает null при расчёте COUNT по колонке. |
| Мера DISTINCT | Приблизительное число различных значений. |
| Вычисляемая мера | Проверка через sample_field недоступна. Используйте меру в run_query. |
Для моделей на основе таблицы ответ также может указывать, входит ли поле в ключ партиционирования, кластеризации или сортировки. Эти подсказки помогают выбрать фильтры, которые сокращают объём чтения.
Выполнение аналитического запроса
Пример возвращает до 20 групп «кампания и день» с наибольшим количеством лидов за последние семь дней. Замените идентификатор модели и поля значениями из list_models и describe_model. В примере date имеет тип DATE.
{
"action": "run_query",
"model_id": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60",
"dimensions": ["e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.campaign"],
"measures": ["e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.leads_sum"],
"time_dimensions": [
{
"dimension": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.date",
"granularity": "day",
"date_range": "last_7_days"
}
],
"order": [
{
"member": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.leads_sum",
"direction": "desc"
}
],
"limit": 20
}Выберите хотя бы одно измерение, меру или измерение времени. Измерения задают группировку. Запрос без мер возвращает различные сочетания выбранных измерений.
Справочник по запросу
Запрос работает с одной моделью. Если нужны данные из нескольких таблиц хранилища, задайте их соединение в SQL модели.
Ссылки на поля
В запросах, фильтрах и сортировке используйте формат model_id.field_name. Короткое field_name без идентификатора модели нужно только для sample_field.
Берите имена мер из describe_model, например leads_sum или count. Само имя колонки не задаёт агрегацию.
Фильтры
Фильтр содержит member, operator и, если нужны, values. Объединяйте условия во вложенные группы с operator: "and" или operator: "or" и массивом filters.
| Оператор | Значения |
|---|---|
equals, not_equals | Ровно одно |
gt, gte, lt, lte | Ровно одно |
contains, not_contains, starts_with, ends_with | Ровно одно |
in, not_in | Одно или больше |
between | Ровно два, обе границы включены |
is_null, is_not_null | Без значений |
Фильтры по измерениям применяются до агрегации. Фильтры по мерам применяются после неё, например для отбора кампаний со 100 и более лидами. Объединяйте эти два вида условий через and. Группа, которая смешивает их через or, отклоняется.
Даты и группировка по времени
Измерение времени выбирает поле с датой или временем. Необязательные параметры granularity и date_range задают группировку и период. Доступные значения гранулярности: hour, day, week, month, quarter и year. Без гранулярности запрос группирует по исходным значениям поля.
Задайте date_range парой дат ISO или относительным периодом:
| Группа | Токены |
|---|---|
| Дни | today, yesterday |
| Текущий период | this_week, this_month, this_quarter, this_year |
| Предыдущий период | last_week, last_month, last_quarter, last_year |
| Скользящие окна | last_7_days, last_14_days, last_30_days, last_60_days, last_90_days, last_365_days |
Относительные периоды отсчитываются от текущей даты UTC. Неделя начинается в понедельник. Скользящие периоды включают сегодня: last_7_days охватывает текущую дату и шесть предыдущих. Текущие календарные периоды заканчиваются сегодня.
Обе границы дат включены. Для поля timestamp верхняя граница соответствует началу указанной даты, а не её концу. Для отбора целых календарных дней используйте измерение типа DATE.
Сортировка и постраничная выдача
Каждый элемент order ссылается на выбранное поле и задаёт направление asc или desc. По умолчанию используется asc.
Параметр limit принимает от 1 до 10 000 строк, по умолчанию 1000. Чтобы пропустить строки, задайте offset. Для постраничной выдачи используйте одинаковую сортировку. В ответе нет признака, что доступны ещё строки.
Результат
В успешном ответе данные находятся внутри data. В таблицах показаны условные фрагменты ответа: MODEL_ID обозначает идентификатор модели.
| Поле | Описание | Пример |
|---|---|---|
data.rows | Строки результата. Имена колонок соединяют идентификатор модели и имя поля через __. У даты с группировкой по месяцам имя заканчивается на __date_month. | [{"MODEL_ID__date_month": "2026-09-01", "MODEL_ID__leads_sum": 120}] |
data.schema_meta | Метаданные колонок: имя и тип. Могут также содержать исходный тип хранилища и формат отображения меры. | [{"name": "MODEL_ID__leads_sum", "type": "int", "warehouse_type": "INTEGER"}] |
data.query_stats | Статистика выполнения запроса. Полный список полей приведён ниже. | {"source_type": "bigquery", "row_count": 1} |
Поля query_stats описывают выполненный запрос. Для ClickHouse показатели оплаты, стоимости, кеша и вычислительных слотов равны null.
| Поле query_stats | Описание | Пример BigQuery | Пример ClickHouse |
|---|---|---|---|
source_type | Тип хранилища. | "bigquery" | "clickhouse" |
bytes_processed | Объём данных в байтах: обработанных в BigQuery или прочитанных в ClickHouse. | 10485760 | 5242880 |
bytes_billed | Объём данных, учитываемый при оплате в BigQuery, в байтах. | 10485760 | null |
estimated_cost_usd | Оценка стоимости запроса в долларах США. | 0.00006 | null |
cache_hit | Признак получения результата из кеша BigQuery. | false | null |
slot_millis | Суммарное время использования вычислительных слотов BigQuery, в миллисекундах. | 250 | null |
duration_ms | Длительность выполнения, в миллисекундах. | 840 | 125 |
job_id | Идентификатор задания BigQuery или запроса ClickHouse. | "bq_job_example" | "ch_query_example" |
row_count | Количество строк результата с учётом limit и offset. | 1 | 1 |
Лимиты и стоимость запросов
Действия sample_field и run_query ис пользуют ресурсы вашего хранилища. Для каждого запроса действуют следующие ограничения:
| Действие | Лимит байтов | Таймаут запроса |
|---|---|---|
sample_field | 5 ГиБ | 30 секунд |
run_query | 10 ГиБ | 60 секунд |
В BigQuery ограничивается объём оплачиваемых байтов. В ClickHouse ограничивается объём чтения, и запрос прерывается при превышении лимита. Эти ограничения относятся к отдельному запросу и не задают общий бюджет расходов.
По возможности фильтруйте по колонкам партиционирования. В ClickHouse фильтр по первым колонкам ключа сортировки тоже может сократить чтение. Уменьшение limit сокращает ответ, но не обязательно объём сканирования.
По умолчанию действует квота 360 запросов в минуту и 6000 в час. Она общая с другими запросами Customer API в рамках лимита пользователя. Персональные настройки лимитов имеют приоритет.
Решение проблем
Проверьте сообщение об ошибке: оно указывает на поле, правило доступа или ограничение хранилища. Ошибка API в ответе MCP содержит status_code и может включать исходный ответ API.
| Проблема | Что проверить |
|---|---|
| Модели нет в list_models | Проверьте AI scope и доступ пользователя на вкладке Access. Владельцам воркспейса доступны все модели, включённые в список для AI. |
| Доступ запрещён | Проверьте членство в воркспейсе, доступ к модели и разрешение Context Layer Read у токена. |
| Неизвестное поле или неверный запрос | Повторите describe_model. Используйте полные ссылки на поля и сортируйте только по выбранным полям. |
| Вычисляемая мера недоступна в sample_field | Используйте меру в run_query или проверьте одно из полей, на которых она основана. |
| Превышен объём чтения или таймаут | Сократите период или добавьте фильтры, которые уменьшают объём чтения. |
| Превышена частота запросов | Снизьте частоту и повторите запрос после сброса лимита. |
Доступ через REST API
Те же операции доступны с токеном Renta API, у которого есть разрешение Read в категории Context Layer.
| Эндпоинт | Операция |
|---|---|
GET /v1/context_layer/models | Список моделей |
GET /v1/context_layer/models/{model_id} | Описание модели |
GET /v1/context_layer/models/{model_id}/fields/{field_name}/values | Получение значений поля |
POST /v1/context_layer/query | Выполнение запроса |
curl -X GET "https://api.eu.renta.im/v1/context_layer/models" \
-H "Authorization: Bearer YOUR_API_TOKEN"Для получения значений поля через REST используйте limit вместо параметра MCP values_limit. REST также поддерживает match=contains для поиска внутри строковых значений. По умолчанию используется match=prefix.
Семантические переопределения добавляют или заменяют определения полей, включая описания и вычисляемые меры. Получите их через GET /v1/context_layer/models/{model_id}/semantics, замените через PUT или удалите через DELETE. Для замены нужно разрешение Update, для удаления Delete.
Что дальше
В этих разделах описаны настройка моделей и подключение клиентов.
Ready to get started?
Build your data pipeline today or get a personalized demo. Start free!
Need help?
Get expert support to ensure your project succeeds. We're here to help!
Feature requests?
Help shape our product! Share your ideas for new features and integrations.