query-execution

---
name: query-execution
description: Выполнение запросов (Query Execution). Навык учит агента **проверять и выполнять запросы на языке запросов 1С** — валидация синтаксиса перед выполнением, получение данных из базы.
---

# Выполнение запросов (Query Execution)

**Справочник синтаксиса:** [`references/query-syntax-cheatsheet.md`](references/query-syntax-cheatsheet.md)

## Workflow

1. **Метаданные** (если не уверен в именах): `list_metadata_objects` → `get_metadata_structure`
2. **Построить запрос** с точными именами объектов и полей
3. **Валидация:** `validate_query`
4. **Выполнение:** `execute_query`

Никогда не угадывай имена — конфигурации 1С различаются. Один вызов за метаданными дешевле отладки провалившегося запроса.

---

## Критические ограничения MCP

При выполнении запросов через `execute_query` (HTTP/MCP без параметров) значения задаются **явно в тексте запроса**. Параметры `&Имя` могут не поддерживаться.

### 1. Ограничивать выборку через ПЕРВЫЕ N

Для запросов, возвращающих строки данных, всегда ограничивай количество записей:

```sql
ВЫБРАТЬ ПЕРВЫЕ 100
    Документы.Номер,
    Документы.Дата
ИЗ
    Документ.РеализацияТоваровУслуг КАК Документы
```

**Исключения — `ПЕРВЫЕ N` не нужен и вреден:**

| Случай | Почему не нужен |
|--------|-----------------|
| Агрегатные запросы (`КОЛИЧЕСТВО`, `СУММА`, `МАКСИМУМ`) | Возвращают одну строку; `ПЕРВЫЕ 1` избыточен и может дать неверный результат при группировке |
| Проверка существования (`ВЫБРАТЬ ПЕРВЫЕ 1 Ссылка ИЗ ... ГДЕ ...`) | `ПЕРВЫЕ 1` здесь уместен и уже ограничивает |
| `ОБЪЕДИНИТЬ ВСЕ` в подзапросах | Ограничение задаётся на внешнем уровне |

### 2. Параметры — если не поддерживаются

❌ **НЕПРАВИЛЬНО** (если `&Параметр` недоступен):
```sql
ГДЕ Товар = &Товар
```

✅ **ПРАВИЛЬНО** (сравнение через примитивные реквизиты):
```sql
ГДЕ Товар.Наименование = "iPhone 17 Pro Max"
ГДЕ Контрагент.ИНН = "7707083893"
```

### 3. Сравнение ссылочных полей — только через примитивы

`execute_query` через HTTP/MCP не поддерживает параметры `&Ссылка`, поэтому сравнивать ссылочные поля напрямую невозможно — используй примитивные реквизиты объекта.

❌ **НЕПРАВИЛЬНО** (сравнение ссылок напрямую):
```sql
ГДЕ Документ.Контрагент = Справочник.Контрагенты.Ссылка
```

✅ **ПРАВИЛЬНО** (сравнение через примитивные реквизиты):
```sql
ГДЕ Документ.Контрагент.Наименование = "ООО Ромашка"
ГДЕ Документ.Контрагент.Код = "000001"
ГДЕ Документ.Контрагент.ИНН = "7707083893"
```

> ⚠️ **Важно — риск неоднозначности.** Наименование и Код не гарантируют уникальность:
> - `Наименование` — может повторяться в разных папках или при дублях
> - `Код` — уникален внутри справочника, предпочтительнее
> - `ИНН`, `Артикул` и другие бизнес-идентификаторы — используй, если они уникальны в этой конфигурации
>
> Когда допустимо: диагностика, анализ данных, разовые запросы где дубли маловероятны.
> Когда недопустимо: критически важная выборка, где ложное совпадение по имени даст неверный результат — в этом случае уточни у пользователя точный идентификатор или используй `ПОДОБНО` с предупреждением о возможных дублях.

### 4. Работа с датами — функция ДАТАВРЕМЯ

```sql
ГДЕ Документы.Дата >= ДАТАВРЕМЯ(2026, 1, 1)
    И Документы.Дата < ДАТАВРЕМЯ(2026, 2, 1)
```

**Формат:** `ДАТАВРЕМЯ(Год, Месяц, День[, Час, Минута, Секунда])`

### 5. Строковые значения — двойные кавычки

```sql
ГДЕ Номенклатура.Наименование = "iPhone 17 Pro Max, 512 Гб"
ГДЕ Контрагент.ИНН = "7707083893"
```

---

## Типичные ошибки

| Ошибка | Решение |
|--------|---------|
| NULL в вычислениях | `ЕСТЬNULL(Поле, ЗначениеПоУмолчанию)` при LEFT JOIN |
| Медленный запрос с ИЛИ | Заменить на `В (...)` или `ОБЪЕДИНИТЬ ВСЕ` |
| Медленный запрос к Регистратору | `ВЫРАЗИТЬ(Регистратор КАК Документ.Имя)` + `ССЫЛКА` в ГДЕ |

---
depends_on: []
---