Средства языка обработки данных (DML) в SQL MCP Server

Это важно

Сервер протокола контекста модели SQL (MCP) доступен в Data API Builder версии 1.7 и выше. Для последних возможностей и исправлений ошибок используйте последний выпуск версии 2.0.

Сервер контекста модели SQL (MCP) предоставляет семь средств языка обработки данных (DML) агентам ИИ. Эти средства предоставляют типизированные поверхности CRUD для операций с базами данных— создание, чтение, обновление и удаление записей, агрегирование данных, а также выполнение хранимых процедур. Все инструменты поддерживают управление доступом на основе ролей (RBAC), разрешения сущностей и политики, определённые в вашей конфигурации.

Предупреждение

Чтобы агенты эффективно запрашивали сущности, настройте метаданные поля в сущностях. Без имен полей и описаний агенты видят только имена сущностей и могут неправильно угадать имена столбцов. Подробнее см. в разделе Добавление описаний сущностям.

Что такое средства DML?

Средства DML (язык обработки данных) обрабатывают операции с данными: создание, чтение, обновление и удаление записей, агрегирование данных, а также выполнение хранимых процедур. В отличие от DDL (язык определения данных), который изменяет схему, DML работает исключительно на плоскости данных в существующих таблицах и представлениях.

Семь средств DML:

describe_entities — обнаруживает доступные сущности и операции
create_record — вставка новых строк
read_records — выполнение запросов к таблицам и представлениям
update_record — изменяет существующие строки
delete_record — удаляет строки
execute_entity — выполняет хранимые процедуры
aggregate_records — выполняет агрегирование запросов

Замечание

Функции SQL MCP Server, описанные в этом разделе, доступны в построителе данных версии 2.0 и более поздних версий. Дополнительные сведения см. в статье "Новые возможности" версии 2.0.

Доступность средства по версии

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

инструмент	1.7.x	2.0+	Включен по умолчанию
`describe_entities`	Да	Да	Да
`create_record`	Да	Да	Да
`read_records`	Да	Да	Да
`update_record`	Да	Да	Да
`delete_record`	Да	Да	Да
`execute_entity`	Да	Да	Да
`aggregate_records`	Нет	Да	Да

Замечание

Если вы используете версию 1.7.x, aggregate_records недоступен. Вместо этого агенты, пытающиеся выполнить подсчет или агрегирование запросов, должны считывать все соответствующие строки. Обновитесь до версии 2.0 или выше для встроенной поддержки агрегации.

Если средства DML включены глобально и для сущности, SQL MCP Server предоставляет их через протокол MCP. Агенты никогда не взаимодействуют напрямую со схемой базы данных — они работают через уровень абстракции Data API builder.

Средства

ответ команды list_tools

Когда агент вызывает list_tools, SQL MCP Server возвращает:

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" },
    { "name": "aggregate_records" }
  ]
}

describe_entities

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

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

Замечание

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

Параметры

Параметр	Тип	Обязательный	Описание
`nameOnly`	булевый	Нет	Когда `true`возвращает упрощенный список имен сущностей и описаний без метаданных поля.
`entities`	массив строк	Нет	Ограничивает ответ указанными сущностями. Если параметр не указан, возвращаются все сущности, поддерживающие MCP.

Пример запроса

{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

Пример ответа

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

Замечание

Параметры сущности, используемые любыми инструментами CRUD и выполнения DML, берутся непосредственно из describe_entities. Внутреннее семантическое описание, присоединенное к каждому инструменту, применяет этот двухэтапный процесс.

create_record

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

Параметры

Параметр	Тип	Обязательный	Описание
`entity`	струна	Да	Имя сущности, в которой будет создана запись.
`data`	объект	Да	Пары имен полей и значений в формате «ключ-значение» для новой записи.

чтение_записей

Запрашивает таблицу или представление. Поддерживает фильтрацию, сортировку, разбиение на страницы и выбор полей. Средство создает детерминированный SQL из структурированных параметров, применяет разрешения на чтение и проекции полей и применяет политики безопасности на уровне строк.

Параметры

Параметр	Тип	Обязательный	Описание
`entity`	струна	Да	Имя сущности для чтения.
`select`	струна	Нет	Разделенный запятыми список имен полей для возврата (например, `"id,title,price"`).
`filter`	струна	Нет	Выражение фильтра в стиле OData (например, `"Price gt 10 and Category eq 'Books'"`).
`orderby`	массив строк	Нет	Сортировать выражения. Каждый элемент — это имя поля с необязательным направлением (например, `["Price desc", "Name asc"]`).
`first`	целое число	Нет	Максимальное количество возвращаемых записей.
`after`	струна	Нет	Курсор продолжения из предыдущего ответа для разбивки на страницы.

Предупреждение

Параметр orderby должен быть массивом строк, а не одной строкой. Передача строкового значения приводит к ошибке UnexpectedError. Используйте ["Name asc"] вместо "Name asc".

Ответ на страницы

Когда доступны дополнительные результаты, ответ включает after курсор. Чтобы получить следующую страницу, передайте это значение в качестве after параметра в следующем запросе.

{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

Наличие поля указывает на наличие дополнительных after страниц. При after отсутствии ответ содержит последнюю страницу.

Это важно

Результаты из read_records автоматически кэшируются с помощью системы кэширования API данных. Вы можете глобально настроить время жизни в кэше (TTL) или для каждой сущности, чтобы уменьшить нагрузку на базу данных.

Операции JOIN

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

Однако операции JOIN не являются пограничным вариантом, а построитель API данных (DAB) уже поддерживает сложные запросы через конечную точку GraphQL. Для более сложных запросов рекомендуется использовать представление вместо таблицы. Вы также можете использовать execute_entity средство для выполнения хранимых процедур для инкапсуляции параметризованных запросов.

обновить_запись

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

Параметры

Параметр	Тип	Обязательный	Описание
`entity`	струна	Да	Имя сущности для обновления.
`keys`	объект	Да	Пары "ключ-значение", определяющие запись (например, `{"id": 42}`).
`fields`	объект	Да	Пары «ключ-значение» для имен полей и новых значений.

удалить_запись

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

Параметры

Параметр	Тип	Обязательный	Описание
`entity`	струна	Да	Имя сущности, из которой нужно удалить.
`keys`	объект	Да	Пары "ключ-значение", определяющие запись (например, `{"id": 42}`).

Замечание

Некоторые рабочие сценарии отключают это средство глобально для широкого ограничения моделей. Этот выбор подходит для вас, и стоит помнить, что разрешения на уровне сущностей остаются самым важным способом управления доступом. Даже с включенным delete-record, если у роли нет разрешения на удаление сущности, эта роль не может использовать этот инструмент для этой сущности.

execute_entity

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

Параметры

Параметр	Тип	Обязательный	Описание
`entity`	струна	Да	Имя объекта хранимой процедуры.
`parameters`	объект	Нет	Пары "ключ-значение", состоящие из названий входных параметров и их значений.

агрегировать записи

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

Параметры

Параметр	Тип	Обязательный	Описание
`entity`	струна	Да	Имя сущности для агрегирования.
`function`	струна	Да	Агрегатная функция: `count`, `sum`, `avgmin`или `max`.
`field`	струна	Да	Поле для агрегации. Используйте `"*"` для `count`.
`filter`	струна	Нет	Фильтр в стиле OData применяется перед агрегированием.
`distinct`	булевый	Нет	При `true`удалении повторяющихся значений перед агрегированием удаляется.
`groupby`	массив строк	Нет	Имена полей для группировки результатов (например, `["Category", "Status"]`).
`having`	объект	Нет	Фильтрует группы по статистическому значению. Использует операторы: `eq`, `neq`, `gt`. `gteltltein`
`orderby`	массив строк	Нет	Сортировка выражений для группированных результатов (например, `["count desc"]`).
`first`	целое число	Нет	Максимальное количество возвращаемых сгруппированных результатов.
`after`	струна	Нет	Курсор продолжения для группированных результатов с разбивкой на страницы.

Пример: подсчет с группой и наличием

{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

Средство aggregate-records можно настроить как логический объект или как объект с дополнительными параметрами:

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Свойство query-timeout задает максимальное время выполнения в секундах (диапазон: 1–600). Этот параметр помогает предотвратить долгосрочные агрегатные запросы от чрезмерного потребления ресурсов.

Конфигурация среды выполнения

В разделе среды выполнения dab-config.json глобально настройте средства DML.

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

Каждое свойство средства в разделе runtime.mcp.dml-tools принимает true или false. Средство aggregate-records также поддерживает объектный формат с enabled и query-timeout.

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Чтобы включить или отключить все средства DML одновременно, установите "dml-tools" в true или false.

Использование интерфейса командной строки

Устанавливайте свойства индивидуально, используя командную строку построителя Data API.

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

Отключение инструментов

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

Распространенные сценарии

Отключить delete-record чтобы предотвратить потерю данных в производственной среде
Отключите create-record для конечных точек отчетов в режиме только для чтения
Отключить execute-entity, если хранимые процедуры не используются
Отключите aggregate-records когда запросы агрегирования не требуются.

Если средство отключено глобально, средство скрыто из list_tools ответа и не может вызываться.

Параметры сущности

Сущности участвуют в MCP автоматически, если вы явно не ограничиваете их. Свойство mcp сущности управляет ее участием в MCP. Используйте формат объекта для явного управления.

Формат объекта

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Если вы не указываете mcp для сущности, средства DML включаются по умолчанию, когда MCP включен глобально.

Пользовательские средства для хранимых процедур

Для сущностей хранимой процедуры можно также зарегистрировать процедуру как именованное средство MCP с помощью custom-tool свойства. Инструкции по настройке см. в разделе Настройка пользовательских инструментов MCP.

Область управления для каждого инструмента

Переключатели для каждого инструмента настраиваются только на глобальном уровне среды выполнения в разделе runtime.mcp.dml-tools.

На уровне сущности mcp является логическим шлюзом или объектом с dml-tools и custom-tool свойствами.

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": false,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

Средство доступно только в том случае, если оно включено глобально, и сущность разрешает средства DML.

Интеграция RBAC

Каждая операция средства DML применяет правила управления доступом на основе ролей. Роль агента определяет, какие сущности видны, какие операции разрешены, какие поля включены и применяются ли политики на уровне строк.

anonymous Если роль разрешает только чтение на Products:

describe_entities только показывает read_records в операциях
create_record, update_recordи delete_record недоступны
Только поля, разрешенные для anonymous, отображаются в схеме.

Настройте роли в вашем `dab-config.json`

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-06-19

Средства языка обработки данных (DML) в SQL MCP Server

Что такое средства DML?

Доступность средства по версии

Средства

ответ команды list_tools

describe_entities

Параметры

Пример запроса

Пример ответа

create_record

Параметры

чтение_записей

Параметры

Ответ на страницы

Операции JOIN

обновить_запись

Параметры

удалить_запись

Параметры

execute_entity

Параметры

агрегировать записи

Параметры

Пример: подсчет с группой и наличием

Конфигурация среды выполнения

Использование интерфейса командной строки

Отключение инструментов

Распространенные сценарии

Параметры сущности

Формат объекта

Пользовательские средства для хранимых процедур

Область управления для каждого инструмента

Интеграция RBAC

Настройте роли в вашем dab-config.json

Связанный контент

Обратная связь

Дополнительные ресурсы

Настройте роли в вашем `dab-config.json`