Rules: экспорт данных

Область действия

Рекомендации по экспорту данных оператором EXPORT. Общие обязательные правила находятся в Rules; эта статья не входит в набор, который всегда передается ассистенту, и запрашивается по мере необходимости.

Выбор источника экспорта

1. Экспорт списка свойств (EXPORT FROM ...) используется, когда результат — одна плоская таблица колонок и структура выгрузки не совпадает ни с одной формой.

2. Экспорт формы (EXPORT formName ...) используется, когда выгрузка повторяет уже существующую форму или когда в результате нужна иерархия групп объектов. Иерархия сохраняется только в JSON и XML; в плоских форматах каждая группа объектов дает отдельный файл, поэтому для них нужно перечислить приемники всех групп в блоке TO.

3. Форму, созданную исключительно ради выгрузки, следует объявлять рядом с действием экспорта и не добавлять в навигатор.

Явное указание того, что влияет на результат

1. Формат следует указывать явно даже тогда, когда нужен JSON: умолчание делает выгрузку зависимой от того, что читающий код помнит про умолчание.

2. Условие WHERE следует указывать явно. Без него условием считается дизъюнкция всех экспортируемых свойств, то есть в выгрузку попадут наборы объектов, у которых заполнено хотя бы одно поле, — это почти никогда не совпадает с нужным набором строк.

3. Идентификаторы колонок следует задавать явно (columnId = expr). Умолчание expr1, ..., exprN привязывает имена полей во внешнем формате к порядку выражений, поэтому вставка колонки в середину списка молча меняет контракт выгрузки.

4. В ORDER допускаются только выражения из списка экспортируемых, поэтому колонку, нужную для упорядочивания, следует включать в выгрузку.

Опции формата

1. Опции, у которых умолчание отличается для разных форматов, следует задавать явно: наличие строки заголовка (HEADER / NOHEADER) в CSV, XLS, XLSX, разделитель CSV (по умолчанию ;) и кодировку (CHARSET, по умолчанию UTF-8, а для DBF — CP1251).

2. NOESCAPE в CSV допустимо использовать только тогда, когда разделитель гарантированно не встречается в данных; в остальных случаях следует оставлять ESCAPE.

3. Кодировку следует определять требованиями принимающей стороны, а не значением по умолчанию: получатели DBF-файлов обычно ожидают однобайтовую кодировку, отличную от UTF-8.

Приемник результата

1. Свойство-приемник в TO следует объявлять локальным для действия экспорта и файлового класса (FILE, RAWFILE, JSONFILE), а не использовать общее свойство: одно свойство, разделяемое несколькими выгрузками, делает результат зависящим от порядка выполнения.

2. Умолчание System.exportFile допустимо только для отладочных и разовых выгрузок.

3. При экспорте формы в плоский формат приемники следует перечислять для всех выгружаемых групп объектов; группа объектов без имени называется root.

Передача результата

1. Действие следует разделять на подготовку данных, собственно EXPORT и передачу файла получателю — записью в файловую систему, отправкой во внешнюю систему или сохранением в свойстве. Такое разделение позволяет повторно использовать выгрузку с разными способами доставки.

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

Примеры

exportedFile = DATA LOCAL FILE ();

exportShipments (Store store) {
    EXPORT CSV ';' HEADER FROM number = number(Shipment s), date = date(s), sum = sum(s)
        WHERE store(s) = store AND shipped(s)
        ORDER date(s)
        TO exportedFile;
}

FORM exportOrders
    OBJECTS st = Store
    OBJECTS o = Order
    PROPERTIES(o) number, date
    FILTERS store(o) = st
;

exportOrders (Store store) {
    EXPORT exportOrders OBJECTS st = store JSON TO exportedFile;
}