Context Layer

Context Layer это компонент Renta MCP Server, предназначенный для взаимодействия с данными. Он предоставляет модели данных Google BigQuery в виде структурированных измерений (dimensions) и мер (measures), позволяя AI-ассистентам программно выбирать поля вместо генерации сырых SQL-запросов.

Renta компилирует этот выбор в SQL-запросы для BigQuery, выполняет их в вашем проекте с использованием сервисного аккаунта подключения и возвращает результирующие строки вместе с подробными метаданными об объеме сканирования и стоимости.

Архитектура энтерпрайз-уровня

Context Layer спроектирован с упором на безопасность, контроль затрат и производительность, выступая в роли защищенного шлюза между вашим хранилищем данных и AI-ассистентами.

1. Безопасность (Security by Design) и дата-контракты.
   Архитектура опирается на строгие дата-контракты (data contracts). AI получает доступ исключительно к тем данным, которые вы явно разрешили. Интерфейс строго ограничен операциями чтения: генерируются только оптимизированные SELECT-запросы, что полностью исключает возможность удаления, модификации или несанкционированного доступа к конфиденциальным данным.
2. Контроль затрат и оптимизация.
   В случае с BigQuery Context Layer жестко ограничивает количество и объем запросов, не позволяя AI инициировать неконтролируемые расходы. Запросы максимально оптимизированы, обеспечивая высокую эффективность работы даже с миллиардами строк.
3. Оптимизация контекста AI.
   Изолируя обработку сырых данных на стороне хранилища и возвращая только агрегированные результаты, Renta предотвращает засорение контекстного окна AI. Это значительно повышает эффективность и качество работы AI с данными.
4. Синергия с дата-инженерами.
   Renta не заменяет проектировщиков данных. Наоборот, дата-инженеры продолжают создавать эффективные, заранее рассчитанные витрины данных (datamarts), а Renta берет на себя роль шлюза, который обеспечивает безопасность, производительность и контролируемый доступ AI к этим данным.

Как это работает

Агенты функционируют без предварительных знаний о топологии вашего хранилища, последовательно формируя контекст за четыре шага.

1. Список моделей.
   Агент запрашивает доступные в рабочей области (workspace) модели и выбирает необходимую по ее идентификатору.
2. Описание модели.
   Renta возвращает все измерения и меры, связанные с указанной моделью, включая их типы и описания. Агент ограничен использованием только тех полей, которые присутствуют в этом ответе.
3. Сэмплирование поля.
   Renta извлекает фактические значения, диапазоны или статистические распределения для указанного поля, гарантируя, что агенты строят фильтры на основе эмпирических данных, а не предположений.
4. Выполнение запроса.
   Renta компилирует выбранные поля, фильтры и временные границы в SQL-запрос, выполняет его и возвращает результирующие строки, метаданные колонок и статистику выполнения.

Все запросы строго ограничены рабочей областью, для которой был выпущен токен. Renta валидирует членство при каждом вызове. Следовательно, отозванный доступ вступает в силу немедленно.

Что нужно заранее

Context Layer взаимодействует с предварительно настроенными моделями. Перед началом использования убедитесь в выполнении следующих предварительных требований.

1. Модель данных с областью видимости для AI.
   Управление моделями осуществляется в разделе Tools > Data models. Инструкции по их созданию приведены в документации Google BigQuery reverse ETL.
2. Подключённый MCP-сервер.
   Процесс авторизации, выполняемый при добавлении сервера, по умолчанию включает доступ к Context Layer. Запрос дополнительных прав не требуется.

Что агент видит в модели

Агенты используют нативную конфигурацию модели. Поддерживать отдельные описания, специфичные для AI, не требуется.

Колонки модели транслируются в измерения, типизированные как string, number, boolean или time. Структурированные колонки, такие как массивы (arrays) и записи (records), преобразуются в строковый тип (string). Имя и описание модели обеспечивают базовый контекст, используемый агентами для интерпретации семантики строк.

Меры формируются на основе конфигураций столбцов на вкладке Measures. Активация переключателя создает соответствующую меру, имя которой состоит из названия колонки и примененной агрегации.

Числовые колонки поддерживают все восемь функций агрегации. Для нечисловых типов доступны только COUNT и DISTINCT, поскольку арифметические операции (сумма, среднее) неприменимы к строковым или временным данным.

Две меры доступны по умолчанию: count, возвращающая общее количество строк, и unique_count, возвращающая количество различных значений уникального ключа (если он задан в модели).

Назначение агрегаций сразу нескольким колонкам

Индивидуальное переключение подходит для узких схем. В моделях с большим количеством столбцов целесообразно использовать массовые операции: выберите целевые колонки для глобального применения агрегаций одним действием.

1. Выберите колонки.
   Отметьте чекбокс в крайней левой колонке нужных строк. Чекбокс в строке заголовка берёт всё, что сейчас показано в таблице, поэтому сначала сузьте список поиском или фильтрами Dimensions и Metrics.
2. Примените агрегации.
   Заголовок страницы сменится панелью, которая показывает размер выбора и восемь агрегаций в виде чипов. Нажатие на чип включает агрегацию всем выбранным колонкам, повторное нажатие выключает.
3. Читайте состояние по чипу.
   Залитый чип означает, что агрегация включена у всех выбранных колонок, пунктирный что у части, контурный что нигде. Чип, который не поддерживает ни одна выбранная колонка, гаснет, поэтому SUM не попадёт на текстовую колонку даже случайно.
4. Начните заново, если нужно.
   Clear снимает у выбранных колонок все агрегации. Show Selected прячет остальную таблицу, пока вы работаете с выбором.

Список мер это контракт

Агент считает только то, что модель ему отдала. Своего SQL у него нет, и агрегация, которую вы не включили, для него не существует, поэтому список мер работает контрактом между вашими данными и агентом.

Ради этого и стоит потратить минуту на выбор по каждой колонке. Тип колонки говорит, что арифметически возможно, а вы говорите, что осмысленно.

На кадре выше правило уже применено: у discount_rate открыты AVG и MEDIAN, а SUM выключен, поэтому суммированную ставку скидки агент не покажет никогда.

Метаданные, которые читает агент

Вашу таблицу агент не видит. Он видит имя модели, её описание и список имён полей с типами, и все его решения строятся на этом. Метаданные заполняются на вкладке Metadata модели.

1. Model name.
   Как модель называют агент и ваши коллеги. Нижний регистр с подчёркиваниями.
2. Description.
   Что лежит в модели и как её использовать. Это поле делает основную работу, и что в нём писать, разобрано в следующем разделе.
3. Column descriptions.
   Хранятся вместе с моделью и показываются в интерфейсе. Кнопка Auto-generate with AI заполняет их по запросу и данным примера.

Панель справа считает, сколько токенов модель займёт в контексте агента. Этот контекст делится со всем остальным в диалоге, поэтому описание оправдывает свою длину тем, что оно решает.

Описание как инструкция для агента

Описание это свободный текст, и агент получает его дважды: в списке моделей, где выбирать больше не по чему, и затем в полной модели. Всё, что вы там напишете, попадёт в контекст агента, поэтому пишите инструкцию, а не подпись.

Что стоит указать в описании:

1. Что такое одна строка.
   От гранулярности зависит, будет число итогом или задвоением.
2. Покрытый период и время обновления.
   Это то, что удержит агента от вывода «сегодня всё упало», когда сегодняшний день ещё не загружен.
3. Единицы измерения и валюта.
   Сумма без валюты всё равно сложится, просто неправильно.
4. На какие вопросы отвечает модель.
   Формулируйте так, как их задают люди, чтобы агент сопоставил запрос с моделью.
5. Когда нужна другая модель.
   Назовите её. Именно это не даёт агенту ответить про возвраты по таблице выручки.
6. Что отфильтровано.
   Тестовые заказы, отменённые строки, внутренние аккаунты.

Действия

Четыре действия инструмента context_layer рассчитаны на использование по порядку. Первые два не читают данные, и именно они не дают итоговому запросу сослаться на несуществующее поле.

Список моделей

Точка входа в любую сессию. Параметров у действия нет, а необязательный source_id сужает выдачу до моделей одного подключения BigQuery.

Ответ короткий: идентификатор, имя и описание каждой модели. Это всё, что есть у агента при выборе модели, поэтому инструкции для него живут в описании модели.

Описание модели

Действие принимает model_id и возвращает модель целиком: таблицу или запрос, который она читает, измерения с типами и описаниями, меры с типами и подсказками по форматированию.

Дальше имена полей используются буквально, а поле, которого не было в этом ответе, использовать нельзя. Здесь же агент узнаёт, какие меры вычисляемые, потому что на следующем шаге они ведут себя иначе.

Сэмплирование поля

Действие принимает model_id и field_name и читает хранилище по одному полю. Так фильтры остаются привязаны к данным, и агент не фильтрует по United States, когда в колонке лежит US.

Что придёт в ответе, зависит от типа поля.

Два необязательных параметра относятся к строковым измерениям. values_limit ограничивает число значений в ответе, максимум 500, по умолчанию 50. search фильтрует по префиксу без учёта регистра, до 100 символов, и это рабочий способ найти значение в колонке с большим числом различных значений, например в идентификаторе заказа.

Для модели на таблице в ответе также указано, является ли поле колонкой партиционирования или частью ключа кластеризации. Фильтр по колонке партиционирования и держит большую модель дешёвой, поэтому агент сэмплирует поле с датой до того, как по нему фильтровать.

Выполнение запроса

Единственное действие, которое возвращает строки данных. Оно принимает модель, набор полей и условия.

В запросе должно быть хотя бы одно из полей dimensions, measures или time_dimensions. Результат всегда агрегирован, поэтому измерение, выбранное без мер, возвращает свои различные значения.

Справочник по запросу

Правила ниже проверяются при компиляции запроса. Запрос, который нарушает любое из них, возвращается со статусом 400 и сообщением о том, что именно не так, поэтому агент исправляет запрос, не прочитав ни одной строки данных.

Ссылки на поля

Поле записывается как идентификатор модели, точка и имя поля. Это касается dimensions, measures, time_dimensions, filters и order одинаково, а короткое имя поля отклоняется.

В именах мер всегда есть агрегация, поэтому колонка leads запрашивается как leads_sum. Сырая колонка сама по себе не агрегируется.

Фильтры

Фильтр это либо одно условие, либо группа условий, объединённых через and или or. Группы вкладываются друг в друга, чем и выражаются условия вида «одна страна с суммой выше одного порога или другая страна с суммой выше другого».

Фильтр по измерению ограничивает читаемые строки. Фильтр по мере ограничивает уже агрегированный результат, и так отвечают на вопрос вида «кампании со ста и более лидами». В одной группе or эти два вида фильтров не сочетаются, потому что применяются на разных стадиях запроса. Объедините их через and верхнего уровня или задайте два вопроса.

Измерения времени

Измерение времени задаёт колонку с датой и, по желанию, гранулярность группировки и период. Гранулярность принимает значения hour, day, week, month, quarter и year.

Период задаётся либо парой дат ISO, где включены обе границы, либо одним из относительных токенов.

Сортировка и постраничная выдача

Сортировка ссылается на поле, которое запрос выбирает. Сортировка по невыбранному полю отклоняется, а не игнорируется молча.

limit принимает от 1 до 10 000 строк, по умолчанию 1000. offset листает длинный результат, и это важно, потому что лимит обрезает ответ без предупреждения о том, что строк больше.

Ответ

Успешный запрос возвращает строки, метаданные колонок и статистику запроса.

Имя колонки состоит из идентификатора модели и имени поля через двойное подчёркивание, а измерение времени с гранулярностью добавляет её в конец. Помесячная динамика leads_sum поэтому приходит в колонке, которая заканчивается на __date_month.

В статистике приходят обработанные байты, оплаченные байты, оценка стоимости, признак попадания в кеш, длительность, количество строк и идентификатор job в BigQuery. Дорогой вопрос показывает свою цену сразу после выполнения.

Контроль стоимости запросов

Сэмплирование и запросы выполняются в вашем проекте BigQuery и попадают в ваш счёт. У каждого из них есть предел по объёму сканирования и по времени.

Запрос, который вышел бы за свой предел, отклоняется до выполнения, и об этом сказано в ответе. Это тот момент, когда стоит добавить фильтр, а не после выставленного счёта.

Самый дешёвый фильтр это фильтр по колонке партиционирования таблицы: BigQuery тогда читает только подходящие партиции. Сэмплирование поля с датой показывает, та ли это колонка.

Квоты и лимиты

В таблице значения по умолчанию. Персональные лимиты, настроенные для вашего аккаунта, имеют приоритет над лимитами на количество запросов.

Ошибки

Сбой возвращается кодом статуса с сообщением, а не пустым результатом.

Доступ через REST API

Те же четыре действия доступны по HTTP для клиентов с API-ключом, на базовом адресе Renta REST API.

Для этих эндпоинтов API-ключу достаточно права Read в категории Context Layer. Права Create, Update и Delete той же категории относятся к семантическим переопределениям модели, которые правятся через API и своего экрана в интерфейсе не имеют.

Что дальше