Термины и описание работы
Термины
Общие:
Термин |
Описание |
|---|---|
Атрибут (Attribute) |
Свойство или ассоциация сущности |
Сущность (Entity) |
Некоторый объект в системе (договор, доверенность, человек, группа, форма и др.) |
Запись (Record) |
Сущность с набором атрибутов и идентификатором записи (RecordRef) |
Идентификатор записи (RecordRef) |
Ссылка вида |
Источник данных (записей) (Records DAO) |
Реализация источника данных. Поддерживаемые операции задаются отдельными интерфейсами поиска, чтения атрибутов, мутации и удаления; весь CRUD реализовывать необязательно |
Данные:
Термин |
Описание |
|---|---|
Граф данных (Data Graph) |
Представление данных, которые может запросить клиент по схеме атрибутов |
Скаляр (Scalar) |
Некоторое финальное значение в графе данных, у которого нельзя запросить вложенные атрибуты (строка, число и др.) |
Схема атрибутов (Attributes Schema) |
Описание запроса данных для преобразования графа данных в наборы (map и list) значений скаляров |
Описание работы с данными
Очень часто данные не являются плоским списком, а представляют из себя граф, где сущности ссылаются друг на друга. Ниже показан пример такого среза данных, где у нас есть договор с четыремя атрибутами:
Заголовок (Title) - Строка
Имя (Name) - Строка
- Контрагент (Counterparty) - Сложный объект
Полное наименование (Full Organization Name) - Строка
Адрес контрагента (Counterparty Address) - Строка
- Валюта (Currency) - Сложный объект
атрибуты пропущены для простоты
С точки зрения 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 это карта локалей и соответствующих строк.
Например — чтобы одним запросом вытянуть все значения для всех локализаций у MLText поля, необходимо использовать при загрузке значения атрибута скаляр «?json».
Records.get("emodel/test-type@ed955b2d-44c2-4617-b48d-0a6b2e0d5a53").load("name?json")
->
{"ru":"Договор №17362","en":"Contract №17362"}
Для примера рассмотрим получение полного наименования организации контрагента у договора.
Здесь мы используем javascript Records API для загрузки нужного нам атрибута.
Первая строка - получение записи по её идентификатору RecordRef. см. подробно
Примечание
Общий вид идентификатора «приложение/источник_данных@локальный_id», но здесь присутствует только локальный_id.
Вторая строка - загрузка нужного нам атрибута. Вложенные атрибуты разделены точкой «.», а скаляр определяется знаком вопроса «?»
Примечание
Грамматика не задаёт фиксированной глубины вложенности. Практическая глубина чтения зависит от источников и доступных ресурсов.