composing-1c-queries

name: composing-1c-queries description: > Compose correct and optimized 1C:Enterprise query language queries. Covers ВЫБРАТЬ/ИЗ/ГДЕ structure, table naming (catalogs, documents, registers, virtual tables), field selection, joins, grouping, totals, temporary tables, and parameter usage. Use when the agent needs to compose a 1C query for execute_query, or when the user asks to query, filter, aggregate, or analyze data from a 1C database. Triggered by requests involving 1C data retrieval, report building, or query debugging.

Composing 1C Queries

Rules and patterns for writing correct 1C:Enterprise query language (язык запросов 1С). Queries are executed via the execute_query tool/endpoint.

CRITICAL: Verify Metadata Before Querying

NEVER guess or invent metadata object names, attribute names, or tabular section names. 1C configurations vary greatly — object and field names are unique to each database.

Before composing a query, if you are not certain about the exact names, use get_metadata or any other available tool to retrieve 1C configuration metadata to discover:

• Available metadata objects (catalogs, documents, registers, etc.)
• Object attributes (реквизиты) and their types
• Tabular sections (табличные части) and their columns
• Register dimensions, resources, and attributes

Workflow: retrieve metadata → confirm names → compose query → execute query

A query with a wrong object or field name will fail with a runtime error. Spending one call on metadata retrieval is always cheaper than debugging a failed query.

Formatting: Always write the entire query text in a single line. Do not use line breaks or multiline formatting.

Query Structure

Canonical order of clauses (required section marked, rest optional):

ВЫБРАТЬ [РАЗРЕШЕННЫЕ] [РАЗЛИЧНЫЕ] [ПЕРВЫЕ <N>]
    <field list>
ИЗ
    <data sources>
[ГДЕ <condition>]
[СГРУППИРОВАТЬ ПО <fields>]
[ИМЕЮЩИЕ <condition>]

[ОБЪЕДИНИТЬ [ВСЕ]
ВЫБРАТЬ ...]

[УПОРЯДОЧИТЬ ПО <fields> [ВОЗР | УБЫВ]]
[АВТОУПОРЯДОЧИВАНИЕ]

[ИТОГИ <aggregate expressions> ПО [ОБЩИЕ] <control points>]

Keywords:

Comments: // single-line only.

Minimal example:

ВЫБРАТЬ Ссылка, Наименование
ИЗ Справочник.Контрагенты
ГДЕ НЕ ПометкаУдаления

Table Names and Sources

Every 1C metadata object has a fixed query-name pattern. Use exact names from get_metadata.

Real tables

Enum values and predefined items

// Enum value (used in conditions, not as a table):
ЗНАЧЕНИЕ(Перечисление.ТипыЦен.Оптовая)

// Predefined catalog item:
ЗНАЧЕНИЕ(Справочник.Валюты.USD)

// Empty reference:
ЗНАЧЕНИЕ(Справочник.Контрагенты.ПустаяСсылка)

Virtual tables

Virtual tables are computed on-the-fly from real register data. Always pass filter conditions as virtual table parameters, NOT in WHERE — this is critical for performance.

Accumulation register (Регистр накопления):

// Current balances (no date = latest):
РегистрНакопления.ОстаткиТоваров.Остатки(, Номенклатура = &Ном)

// Balances at specific date:
РегистрНакопления.ОстаткиТоваров.Остатки(&Дата, Склад = &Склад)

// Turnovers for period:
РегистрНакопления.ОстаткиТоваров.Обороты(&НачДата, &КонДата, , Номенклатура = &Ном)

// Balances and turnovers:
РегистрНакопления.ОстаткиТоваров.ОстаткиИОбороты(&НачДата, &КонДата, , , Номенклатура = &Ном)

Information register (Регистр сведений):

// Latest values (slice of last):
РегистрСведений.КурсыВалют.СрезПоследних(&Дата, Валюта = &Валюта)

// Earliest values (slice of first):
РегистрСведений.КурсыВалют.СрезПервых(&Дата, Валюта = &Валюта)

Parameter syntax inside virtual tables: Dimension = Value joined by commas. Keep it simple — no subqueries or joins inside parameters.

Accumulation register resource suffixes:

When using virtual tables, resource fields get automatic suffixes:

// Example — turnovers with all suffixes:
ВЫБРАТЬ
    Об.Номенклатура,
    Об.КоличествоПриход,
    Об.КоличествоРасход,
    Об.КоличествоОборот,
    Об.КоличествоНачальныйОстаток,
    Об.КоличествоКонечныйОстаток
ИЗ
    РегистрНакопления.ТоварыНаСкладах.ОстаткиИОбороты(&Нач, &Кон, , , ) КАК Об

Table aliases

Справочник.Номенклатура КАК Товары

Always assign short aliases — improves readability and is required when self-joining or using the same table twice.

Hierarchical catalogs

Catalogs with hierarchy support nested groups:

// Direct children (one level) — preferred:
ВЫБРАТЬ Наименование
ИЗ Справочник.Номенклатура
ГДЕ Родитель = &Родитель
// params: {"Родитель": {"_objectRef": true, "УникальныйИдентификатор": "...",
//                        "ТипОбъекта": "СправочникСсылка.Номенклатура", "Представление": "..."}}

// Or by name:
ГДЕ Родитель.Наименование = "Бытовая техника"

// All items in group and subgroups — preferred:
ВЫБРАТЬ Наименование
ИЗ Справочник.Номенклатура
ГДЕ Ссылка В ИЕРАРХИИ (&Группа)
// params: {"Группа": {"_objectRef": true, "УникальныйИдентификатор": "...",
//                      "ТипОбъекта": "СправочникСсылка.Номенклатура", "Представление": "..."}}

// Or by name:
ГДЕ Ссылка В ИЕРАРХИИ (
    ВЫБРАТЬ Ссылка ИЗ Справочник.Номенклатура
    ГДЕ Наименование = "Бытовая техника"
)

// Only leaf items (not groups):
ГДЕ ЭтоГруппа = ЛОЖЬ

// Only groups:
ГДЕ ЭтоГруппа = ИСТИНА

Rules:

• Родитель = &Родитель — direct children only (one level)
• Ссылка В ИЕРАРХИИ (&Группа) — all nested levels
• ЭтоГруппа — ИСТИНА = groups only, ЛОЖЬ = leaf items only
• AVOID: В ИЕРАРХИИ (ПустаяСсылка) — very slow

Field Selection

• * selects all real fields (virtual fields are NOT included)
• Aliases: <expression> КАК <Alias> — aliases must be unique within the query
• Access nested fields with dot notation: Товары.Номенклатура.Наименование

CRITICAL: Compound-type field dereferencing

When a field can reference multiple table types (compound/composite type), accessing it through dots creates implicit JOINs to ALL possible target tables. This severely degrades performance.

Always narrow the type with ВЫРАЗИТЬ:

// BAD — joins to every possible Регистратор table:
ВЫБРАТЬ Регистратор.Номер ИЗ РегистрНакопления.ОстаткиТоваров

// GOOD — single join:
ВЫБРАТЬ ВЫРАЗИТЬ(Регистратор КАК Документ.РеализацияТоваровУслуг).Номер
ИЗ РегистрНакопления.ОстаткиТоваров
ГДЕ Регистратор ССЫЛКА Документ.РеализацияТоваровУслуг

NULL handling

• Use ЕСТЬNULL(field, default) for fields that may be NULL (e.g., from LEFT JOIN)
• Check NULL with ЕСТЬ NULL / НЕ ЕСТЬ NULL (not = NULL)

Empty table for UNION

When unioning queries with different nested table structures:

ПУСТАЯТАБЛИЦА.(Номенклатура, Количество, Цена)

WHERE and HAVING

Operators

Operator precedence: НЕ > И > ИЛИ. Use parentheses () for explicit priority.

Key rules

• ИЛИ (OR) degrades index usage. Replace with В (...) where possible, or split into ОБЪЕДИНИТЬ ВСЕ
• ВЫБОР (CASE) in WHERE: Only in additional (non-indexed) conditions
• String comparison: Case-insensitive, ignores trailing spaces
• Arithmetic in WHERE: Only in additional conditions (prevents index use)
• Pattern ПОДОБНО: Must not start with % or _ if in indexed condition

For index-aware optimization strategy, see optimization-and-pitfalls.md.

Joins

ИЗ Документ.РеализацияТоваровУслуг КАК Док
    ЛЕВОЕ СОЕДИНЕНИЕ Справочник.Контрагенты КАК Конт
    ПО Док.Контрагент = Конт.Ссылка

Rules:

• NEVER use nested joins (join of a subquery that itself contains joins). Replace with temporary tables or sequential joins
• For LEFT JOIN: index the right table's join fields
• For INNER JOIN: index the larger table's join fields

Grouping and Totals

GROUP BY

ВЫБРАТЬ
    Контрагент,
    СУММА(СуммаДокумента) КАК Итого,
    КОЛИЧЕСТВО(РАЗЛИЧНЫЕ Ссылка) КАК КолДок
ИЗ Документ.РеализацияТоваровУслуг
СГРУППИРОВАТЬ ПО Контрагент
ИМЕЮЩИЕ СУММА(СуммаДокумента) > 1000

Aggregate functions: СУММА (SUM), СРЕДНЕЕ (AVG), МИНИМУМ (MIN), МАКСИМУМ (MAX), КОЛИЧЕСТВО (COUNT), КОЛИЧЕСТВО(РАЗЛИЧНЫЕ ...) (COUNT DISTINCT).

Every non-aggregated field in SELECT must appear in GROUP BY.

TOTALS (brief)

ИТОГИ СУММА(СуммаДокумента) ПО ОБЩИЕ, Контрагент

Computes subtotal rows interleaved with detail rows. For full syntax (ПЕРИОДАМИ, hierarchical control points, grouping sets), see query-syntax-reference.md.

Temporary Tables

Use temporary tables to break complex queries into steps, avoid nested subqueries, and improve performance.

// Step 1: collect items into temp table
ВЫБРАТЬ Ссылка КАК Номенклатура
ПОМЕСТИТЬ ВТ_Товары
ИЗ Справочник.Номенклатура
ГДЕ Наименование ПОДОБНО &Маска
ИНДЕКСИРОВАТЬ ПО Номенклатура
;
// Step 2: get balances for those items
ВЫБРАТЬ
    Ост.Номенклатура КАК Номенклатура,
    Ост.КоличествоОстаток КАК Остаток
ИЗ РегистрНакопления.ОстаткиТоваров.Остатки(
        ,
        Номенклатура В (ВЫБРАТЬ Номенклатура ИЗ ВТ_Товары)
    ) КАК Ост

Rules:

• Separate queries in a batch with ;
• ПОМЕСТИТЬ <Name> creates the temp table (place right after SELECT fields, before ИЗ)
• ИНДЕКСИРОВАТЬ ПО <field> — add after the query for temp tables with >1000 rows used in joins or В subqueries
• Minimize data volume and field count in temp tables
• NEVER create/drop temp tables in a loop
• Prefer temp tables over nested subqueries in JOIN conditions

Parameters

Parameters are external values passed into the query. Syntax: &ParameterName.

ВЫБРАТЬ * ИЗ Справочник.Контрагенты ГДЕ Наименование ПОДОБНО &Маска

Passed via execute_query params: {"Маска": "%Рога%"}.

Rules:

• Always use parameters for external values — never concatenate strings into query text
• Enum values: use ЗНАЧЕНИЕ() in query text, not as parameter: ГДЕ Тип = ЗНАЧЕНИЕ(Перечисление.ТипыЦен.Оптовая)
• Date format in params: ISO 8601 ("2024-01-15" or "2024-01-15T10:30:00")
• Boolean: ИСТИНА / ЛОЖЬ in query text, or pass true/false as parameter

Comparing Reference Fields

When comparing reference fields (link-type attributes), pass the reference as a parameter:

// GOOD — reference passed as parameter from previous query result:
ВЫБРАТЬ * ИЗ Документ.ПродажаТоваров
ГДЕ Контрагент = &Контрагент
// params: {"Контрагент": {"_objectRef": true, "УникальныйИдентификатор": "...",
//                           "ТипОбъекта": "СправочникСсылка.Контрагенты", "Представление": "..."}}

// ALSO GOOD — compare via primitive attribute:
ГДЕ Контрагент.Наименование = "ООО Ромашка"
ГДЕ Контрагент.Код = "000001"

// AVOID — direct comparison with another table's reference:
ГДЕ Документ.Контрагент = Справочник.Контрагенты.Ссылка

Rules:

• First choice: pass reference object from previous query result as &Parameter
• Fallback: compare via primitive fields (Наименование, Код, etc.)
• Never compare reference fields directly from different sources

Common Patterns

1. Find by name (fuzzy):

ВЫБРАТЬ Ссылка, Наименование ИЗ Справочник.Контрагенты ГДЕ Наименование ПОДОБНО &Маска
// params: {"Маска": "%рога%"}

2. Latest N documents:

ВЫБРАТЬ ПЕРВЫЕ 10 Ссылка, Дата, Номер, СуммаДокумента
ИЗ Документ.РеализацияТоваровУслуг
УПОРЯДОЧИТЬ ПО Дата УБЫВ

3. Current balances (virtual table, no date = now):

ВЫБРАТЬ Номенклатура, КоличествоОстаток
ИЗ РегистрНакопления.ОстаткиТоваров.Остатки(, Номенклатура = &Ном) КАК Ост

4. Latest register slice:

ВЫБРАТЬ Валюта, Курс ИЗ РегистрСведений.КурсыВалют.СрезПоследних(&Дата,) КАК Курсы

5. Count by group:

ВЫБРАТЬ Контрагент, КОЛИЧЕСТВО(*) КАК Кол
ИЗ Документ.РеализацияТоваровУслуг
СГРУППИРОВАТЬ ПО Контрагент
УПОРЯДОЧИТЬ ПО Кол УБЫВ

6. Check existence:

ВЫБРАТЬ ПЕРВЫЕ 1 Ссылка ИЗ Справочник.Контрагенты ГДЕ ИНН = &ИНН

7. Exclude items marked for deletion:

ГДЕ НЕ ПометкаУдаления

8. Explore table structure (zero-row query with schema):

ВЫБРАТЬ ПЕРВЫЕ 0 * ИЗ Справочник.Контрагенты
// use with include_schema: true in execute_query

References

• Query syntax reference — ВЫБОР (CASE), ОБЪЕДИНИТЬ, УПОРЯДОЧИТЬ ПО, ИТОГИ, ПОДОБНО patterns, ССЫЛКА, subqueries
• Optimization and pitfalls — index strategy, ИЛИ alternatives, compound types, virtual table rules, RLS impact
• Functions and expressions — aggregate, date, string, type, math functions and type casting with ВЫРАЗИТЬ