Чтение данных из Первой Формы¶
Справочник по получению информации через смарт-выражения и смарт-фильтры.
Концепция¶
Смарт-выражения — SQL-подобные запросы, построенные через конструктор 1Ф. Возвращают значения любых типов.
Смарт-фильтры — смарт-выражения, возвращающие true/false или массив элементов. Используются для фильтрации выборок.
Оба инструмента могут работать в режимах: - SMART — визуальный конструктор - TSQL — прямой SQL-код
Основные сущности для чтения¶
Задача (Task)¶
| Атрибут | Тип | Описание |
|---|---|---|
| ID задачи | Integer |
Уникальный идентификатор |
| Номер задачи | Integer |
Номер в категории |
| Текст | String |
Текст/описание задачи |
| Заказчик | 1F.User |
Пользователь-заказчик |
| Исполнители | Collection<1F.User> |
Коллекция исполнителей |
| Ответственный исполнитель | 1F.User |
Ответственный |
| Подписчики | Collection<1F.User> |
Подписчики задачи |
| Категория | 1F.Subcat |
Категория задачи |
| Статус | 1F.State |
Текущий статус |
| Срок | DateTime |
Срок выполнения |
| Дата начала работ | DateTime |
Плановое начало |
| Дата создания | DateTime |
Когда создана |
| Дата закрытия | DateTime |
Когда закрыта |
| Приоритет | Integer |
0=низкий, 1=обычный, 3=высокий |
| Конфиденциальность | Boolean |
Признак конфиденциальности |
Пользователь (User)¶
| Атрибут | Тип | Описание |
|---|---|---|
| ID | Integer |
Уникальный идентификатор |
| Логин | String |
Имя входа |
| ФИО | String |
Полное имя |
String |
Адрес почты | |
| Телефон | String |
Номер телефона |
| Группы | Collection<1F.UserGroup> |
Группы пользователя |
| Орг.единица | 1F.OrgUnit |
Позиция в орг.структуре |
| Часовая зона | String |
Таймзона |
| Активен | Boolean |
Признак активности |
Категория (Subcat)¶
| Атрибут | Тип | Описание |
|---|---|---|
| ID | Integer |
Уникальный идентификатор |
| Название | String |
Наименование |
| Описание | String |
Описание категории |
| Родительский раздел | 1F.Section |
Раздел |
Файл (File)¶
| Атрибут | Тип | Описание |
|---|---|---|
| FileId | Integer |
ID файла |
| VersionId | Integer |
ID версии |
| Name | String |
Имя файла |
| IsDeleted | Boolean |
Удалён ли |
| LatestVersionId | Integer |
Последняя версия |
Работа с дополнительными параметрами (ДП)¶
Числовые ДП¶
-- Получение значения
ДП.Сумма
-- Арифметика
ДП.Сумма * 1.2
ДП.Цена / ДП.Количество
-- Важно: целочисленное деление
1 / 5 = 0
1.0 / 5 = 0.2
Функции преобразования:
- ВСтроку(число) — число → строка
- ВЦелоеЧисло(строка) — строка → целое
- ВДробноеЧисло(строка) — строка → decimal
- Округлить(число) — округление
- МинЦелоеНеМеньше(число) — ceiling
- МаксЦелоеНеБольше(число) — floor
Строковые ДП¶
-- Конкатенация
ДП.Фамилия + ' ' + ДП.Имя
-- Сравнение
ДП.Статус = 'Активен'
-- Строки в одинарных кавычках
'текст'
Функции работы со строками:
| Функция | Описание | Пример |
|---|---|---|
СтрокаСодержит(стр, подстр) |
Проверка вхождения | СтрокаСодержит(ДП.Название, 'срочно') |
НачинаетсяС(стр, подстр) |
Начинается ли с | НачинаетсяС(ДП.Код, 'PRJ-') |
ЗаканчиваетсяНа(стр, подстр) |
Заканчивается ли на | ЗаканчиваетсяНа(ДП.Email, '@company.ru') |
Подстрока(стр, начало, длина) |
Извлечение подстроки | Подстрока(ДП.Код, 1, 3) |
ВернутьСлева(стр, N) |
Первые N символов | ВернутьСлева(ДП.Артикул, 4) |
ВернутьСправа(стр, N) |
Последние N символов | ВернутьСправа(ДП.Телефон, 4) |
ДлинаСтроки(стр) |
Длина строки | ДлинаСтроки(ДП.Описание) |
ЗаменитьВСтроке(стр, что, на_что) |
Замена | ЗаменитьВСтроке(ДП.Текст, 'старое', 'новое') |
ВВерхРегистр(стр) |
ВЕРХНИЙ РЕГИСТР | — |
ВНижРегистр(стр) |
нижний регистр | — |
БезПробелов(стр) |
Trim | — |
СтрокаПуста(стр) |
Проверка на пустоту | — |
IsNullString(стр1, стр2) |
Если null → стр2 | IsNullString(ДП.Комментарий, '') |
Поиск в строке:
-- Позиция подстроки (0 если не найдено)
ПоискВСтроке('что', 'где', начальная_позиция)
-- Поиск по шаблону (% = любые символы, _ = один символ)
ПоискПоШаблону('%pattern%', строка)
Дата и время¶
-- Текущая дата/время
ТекущиеДатаВремя()
-- Создание даты
НовыеДатаВремя(2024, 12, 31, 18, 0, 0)
Извлечение компонентов:
| Функция | Возвращает |
|---|---|
Год(дата) |
Год |
Месяц(дата) |
Месяц (1-12) |
День(дата) |
День месяца |
Час(дата) |
Час (0-23) |
Минута(дата) |
Минуты |
ДеньГода(дата) |
День в году (1-366) |
ДеньНедели(дата) |
Название дня недели |
НерабочийДень(дата) |
true/false |
Арифметика с датами:
| Функция | Описание |
|---|---|
ДобавитьДней(дата, N) |
+/- N дней |
ДобавитьМесяцев(дата, N) |
+/- N месяцев |
ДобавитьЛет(дата, N) |
+/- N лет |
ДобавитьЧасов(дата, N) |
+/- N часов |
ДобавитьМинут(дата, N) |
+/- N минут |
ДобавитьРабочихДней(дата, N) |
+/- N рабочих дней |
ДобавитьРабочихЧасов(дата, N) |
+/- N рабочих часов |
Разница между датами:
| Функция | Возвращает |
|---|---|
РазницаДней(дата1, дата2) |
Целых дней |
РазницаМесяцев(дата1, дата2) |
Целых месяцев |
РазницаЛет(дата1, дата2) |
Целых лет |
РазницаЧасов(дата1, дата2) |
Целых часов |
РазницаМинут(дата1, дата2) |
Целых минут |
РазницаРабочихДней(дата1, дата2) |
Рабочих дней |
Округление дат:
| Функция | Результат |
|---|---|
УсечьВремя(дата) |
Дата 00:00 |
ОкруглитьКонецДня(дата) |
Дата 23:59 |
ОкруглитьНачалоНедели(дата) |
Понедельник 00:00 |
ОкруглитьКонецНедели(дата) |
Воскресенье 23:59 |
ОкруглитьНачалоМесяца(дата) |
1-е число 00:00 |
ОкруглитьКонецМесяца(дата) |
Последний день 23:59 |
ОкруглитьНачалоКвартала(дата) |
Начало квартала |
ОкруглитьКонецКвартала(дата) |
Конец квартала |
ОкруглитьНачалоГода(дата) |
1 января 00:00 |
ОкруглитьКонецГода(дата) |
31 декабря 23:59 |
Форматирование:
ОтформатироватьДату(дата, 'dd.MM.yyyy HH:mi')
Часовые зоны:
ПеревестиВЧасовуюЗонуПользователя(дата, ID_пользователя)
Логические ДП (Галочка/Checkbox)¶
ДП типа "Галочка" хранит и строковое ('да'/'нет'), и бинарное значение.
-- Через свойство Галочка (бинарное)
ДП.Активен.Галочка = cast(1 as bit)
-- Через текстовое значение
ДП.Активен = 'да'
-- Проверка наличия значения
ДП.Поле есть значение
ДП.Поле нет значения
ДП.Поле есть ложь
ДП "Выбор пользователей"¶
Содержит три типа значений: пользователи, группы, орг.единицы.
-- Обращение к разным типам
ДП.Согласующие.Пользователи
ДП.Согласующие.Группы
ДП.Согласующие.ОргЕдиницы
-- Проверка: содержит только пользователей (без групп)
(ДП.Согласующие.Группы нет значения)
ДП Lookup (ссылка на задачу)¶
Через Lookup можно обращаться к любым атрибутам связанной задачи:
-- Атрибуты связанной задачи
ДП.Проект.Название
ДП.Проект.Заказчик.ФИО
ДП.Проект.Срок
-- ДП связанной задачи
ДП.Проект.ДП.Бюджет
Проверка вхождения в список:
ДП.Проект В списке {12345, 67890, 11111}
Обратные ссылки — если другая категория ссылается на текущую через Lookup, в дереве появляется объект для получения всех ссылающихся задач.
ДП "Выбор нескольких задач из категории" (Multilookup)¶
Значение — массив ID задач: {12345, 67890, 34567}
-- Количество выбранных
Количество(ДП.СвязанныеЗадачи)
-- Проверка наличия задачи в списке
12345 В списке ДП.СвязанныеЗадачи
ДП "Таблица"¶
Структура: строки × колонки. Обращение через ID строки и ID колонки.
-- Получение значения ячейки
ДП.Таблица[ID_строки][ID_колонки]
-- Агрегация по колонке
Сумма(ДП.Таблица.Колонки[ID_колонки])
Максимум(ДП.Таблица.Колонки[ID_колонки])
Типы колонок: - Текст, Большой текст - Число - Дата, ДатаВремя - Выпадающий список - Выбор пользователей - Файл, Мультифайл
ДП "Файл"¶
-- Для единичного файла (без Мультифайл)
ДП.Документ.Name
ДП.Документ.FileId
-- Для мультифайла (коллекция)
Количество(ДП.Документы)
ДП.Документы[0].Name
Файлы, вложенные в задачу:
-- Все файлы задачи
Связи файлов с задачами
-- Файлы в ДП
Связи файлов с ДП
Версии файла:
-- Ссылка на конкретную версию
FileId.VersionId
-- Например, первая версия
ДП.Документ.FileId + '.' + ВСтроку(1)
Работа с коллекциями¶
Агрегатные функции¶
| Функция | Описание | Пример |
|---|---|---|
Сумма(коллекция) |
Сумма значений | Сумма(Подзадачи.ДП.Часы) |
Среднее(коллекция) |
Среднее | Среднее(Задачи.ДП.Оценка) |
Минимум(коллекция) |
Минимальное | Минимум(Задачи.Срок) |
Максимум(коллекция) |
Максимальное | Максимум(Задачи.Срок) |
Количество(коллекция) |
Число элементов | Количество(Исполнители) |
Сконкатенировать в строку¶
Преобразует коллекцию в строку:
Сконкатенировать(
EVALXML(выборка_данных),
'атрибут',
',' -- разделитель
)
Условная логика¶
В случае
если условие1 то результат1
если условие2 то результат2
иначе результат_по_умолчанию
конец
Пример:
В случае
если ДП.Приоритет = 3 то 'Срочно'
если ДП.Приоритет = 1 то 'Обычно'
иначе 'Низкий'
конец
Операторы сравнения¶
| Оператор | Описание |
|---|---|
= |
Равно |
<> |
Не равно |
<, <=, >, >= |
Сравнение |
В списке {a, b, c} |
Входит в список |
Не в списке {a, b, c} |
Не входит в список |
И |
Логическое И |
ИЛИ |
Логическое ИЛИ |
НЕ |
Отрицание |
Примеры типовых запросов¶
Получить задачи по статусу¶
Статус.ID = ID_статуса
Задачи за период¶
Дата создания >= НовыеДатаВремя(2024, 1, 1, 0, 0, 0) И
Дата создания <= НовыеДатаВремя(2024, 12, 31, 23, 59, 59)
Просроченные задачи¶
Срок < ТекущиеДатаВремя() И
Статус.ID Не в списке {ID_закрытого_статуса}
Задачи пользователя¶
ID_пользователя В списке Исполнители.ID
Задачи без исполнителя¶
Исполнители нет значения
Поиск по тексту¶
СтрокаСодержит(Текст, 'ключевое слово') ИЛИ
СтрокаСодержит(ДП.Описание, 'ключевое слово')
Задачи с вложениями¶
Количество(Связи файлов с задачами) > 0
Суммы по связанным задачам¶
Сумма(
Отобрать(
Связанные задачи,
Статус.ID = ID_закрытого_статуса
).ДП.Сумма
)
Работа с ресурсами и трудозатратами¶
Коллекции для чтения¶
| Коллекция | Таблица БД | Содержит |
|---|---|---|
| Плановые трудозатраты | TaskResourcesPlanEntries |
План по дням |
| Плановые ресурсы | TaskResources |
Общий план по видам |
| Фактические трудозатраты по исполнителям | TaskResourceFactAggregated |
Факт в разрезе исполнителей |
| Фактические трудозатраты по дням | TaskResourcesFactEntries |
Факт по дням |
Примеры¶
-- Сумма плановых часов по задаче
Сумма(Плановые ресурсы.Часы)
-- Фактические трудозатраты конкретного исполнителя
Отобрать(
Фактические трудозатраты по исполнителям,
Исполнитель.ID = ID_пользователя
)
TSQL-режим (прямые SQL-запросы)¶
Для сложных случаев доступен прямой SQL:
Файлы задачи¶
SELECT
CAST(f.FileId AS varchar(MAX)) + '.' +
CAST(f.LatestVersionId AS varchar(MAX)) AS FileRef
FROM FileStorageFiles f
JOIN FileStorageFileToTaskLinks l ON f.FileId = l.FileId
WHERE l.IsDeleted = 0
AND l.TaskId = @TaskId
Файлы из ДП¶
SELECT
CAST(f.FileId AS varchar(MAX)) + '.' +
CAST(f.LatestVersionId AS varchar(MAX)) AS FileRef
FROM FileStorageFiles f
JOIN FileStorageFileToExtParamLinks l ON f.FileId = l.FileId
WHERE l.TaskId = @TaskId
AND l.ExtParamId = @ExtParamId
Основные таблицы файлового хранилища¶
| Таблица | Описание |
|---|---|
FileStorageFiles |
Метаданные файлов |
FileStorageFileVersions |
Версии файлов |
FileStorageFileToTaskLinks |
Связи файлов с задачами |
FileStorageFileToExtParamLinks |
Связи файлов с ДП |
FileProviders |
Провайдеры хранилища |
Типы возвращаемых значений¶
| Тип | Описание |
|---|---|
String |
Строка |
Integer |
Целое число |
Decimal |
Десятичная дробь |
Boolean |
Логическое (true/false) |
DateTime |
Дата и время |
Entity.User |
Пользователь |
Entity.Task |
Задача |
Entity.File |
Файл |
Collection<T> |
Коллекция объектов |
Использование в MCP-контексте¶
Смарт-выражения можно использовать для:
- Фильтрации задач — получение списка по условиям
- Вычисляемых полей — расчёт значений на лету
- Валидации — проверка условий перед действиями
- Отчётности — агрегация данных по коллекциям
Рекомендации¶
- Используйте
IsNullString()для защиты от null - Проверяйте типы при конвертации
- Для сложных запросов предпочитайте TSQL
- Тестируйте выражения на реальных данных через интерфейс
Источники: