Термины и описание работы

Термины

Общие:

Термин

Описание

Атрибут (Attribute)

Свойство или ассоциация сущности

Сущность (Entity)

Некоторый объект в системе (договор, доверенность, человек, группа, форма и др.)

Запись (Record)

Сущность с набором атрибутов и идентификатором записи (RecordRef)

Идентификатор записи (RecordRef)

Ссылка вида appName/sourceId@localId. Часть приложения может быть опущена, если его можно определить из контекста

Источник данных (записей) (Records DAO)

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

Данные:

Термин

Описание

Граф данных (Data Graph)

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

Скаляр (Scalar)

Некоторое финальное значение в графе данных, у которого нельзя запросить вложенные атрибуты (строка, число и др.)

Схема атрибутов (Attributes Schema)

Описание запроса данных для преобразования графа данных в наборы (map и list) значений скаляров

Описание работы с данными

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

  • Заголовок (Title) - Строка

  • Имя (Name) - Строка

  • Контрагент (Counterparty) - Сложный объект
    • Полное наименование (Full Organization Name) - Строка

    • Адрес контрагента (Counterparty Address) - Строка

  • Валюта (Currency) - Сложный объект
    • атрибуты пропущены для простоты

Data Graph

С точки зрения Records API каждый узел этого графа данных может быть получен как значение одного из скаляров:

Примитивные скаляры:

Скаляр

Описание

disp

Человекочитаемый вид значения (примеры: для договора — «Договор №2», для пользователя — «Иванов Иван»)

str

Строка

num

Число (двойная точность; если точности Double не хватает, то следует использовать str)

bool

Булево значение

json

JSON представление значения. Допускаются массивы и объекты, см. ниже

id

Глобальный идентификатор значения, который содержит идентификатор источника данных и локальный идентификатор. Актуален для сложных значений вроде «Договор», «Контрагент», «Валюта» и др.

localId

То же, что и id, но без идентификатора источника данных

assoc

Идентификатор ассоциации; в мутациях используется также для связанных виртуальных записей, которые нужно создать

Непримитивные скаляры:

Скаляр

Описание

?raw

Возвращает необработанное представление, определённое для конкретного значения. Например, для ссылки на запись возвращается строка ссылки; это не универсальный способ получить все поля сущности

?bin

Возвращает бинарные данные. При использовании json-формата равнозначен использованию ?str (данные передаются в виде base64 строки), но с использованием форматов, которые поддерживают передачу массивов байт без необходимости трансформации в base64, даёт преимущество по размеру передаваемых данных (base64 даёт оверхед 33%)

?json возвращает JSON-представление значения. Его состав определяется источником: он не обязан включать все хранимые и вычисляемые атрибуты записи. Для MLText это карта локалей и соответствующих строк.

await Citeck.Records.get ('hr-table-wizard@0b5f0585-e0b4-4388-a6df-e4724eb2f0b7').load('?json')
../../../_images/json_1.png
recordsService.getAtt("integrations/edi-box@b12333d6-6207-4d9f-82da-8a92a281b7ab", "?json")
../../../_images/json_2.png

Например — чтобы одним запросом вытянуть все значения для всех локализаций у MLText поля, необходимо использовать при загрузке значения атрибута скаляр «?json».

Records.get("emodel/test-type@ed955b2d-44c2-4617-b48d-0a6b2e0d5a53").load("name?json")

->

{"ru":"Договор №17362","en":"Contract №17362"}
Data Graph with Scalars

Для примера рассмотрим получение полного наименования организации контрагента у договора.

Получение наименования контрагента

Здесь мы используем javascript Records API для загрузки нужного нам атрибута.

Первая строка - получение записи по её идентификатору RecordRef. см. подробно

Примечание

Общий вид идентификатора «приложение/источник_данных@локальный_id», но здесь присутствует только локальный_id.

Вторая строка - загрузка нужного нам атрибута. Вложенные атрибуты разделены точкой «.», а скаляр определяется знаком вопроса «?»

Примечание

Грамматика не задаёт фиксированной глубины вложенности. Практическая глубина чтения зависит от источников и доступных ресурсов.