.. _smev_ql_concept: Основные понятия СМЭВ QL ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ресурс ######### Ресурс представляет собой объект (таблица) хранилища Поставщика, данные которого могут быть получены или изменены Потребителем при запросе к СМЭВ QL серверу. Ресурс описывается в модели данных СМЭВ QL, а так же указывается в исходном запросе от Потребителя. Пример определения ресурса в модели данных СМЭВ-QL: .. code-block:: yaml resources: - tickets: *base_model name: Билеты fields: "id", "passengerid", "tripid", "number", "bycard", "price", "sold" Пример определения ресурса в запросе Потребителя: .. code-block:: yaml "query": { "tickets": { "conditions": { "number": 1 }, "attributes": ["id", "passengerid", "tripid", "number", "bycard", "price", "sold"] } .. _basic_data_model: Базовая модель данных ####################### Базовая модель данных - это описание типовых элементов и форматов данных, которые могут использоваться (наследоваться) при создании пользовательских моделей. Автоматически генерируется при создании СМЭВ QL и не может быть отредактирована вручную. Базовая модель не описывает схему данных витрины и не участвует в логике СМЭВ QL при обработке запросов. Хранится в файловой системе СМЭВ QL сервера по пути: models>base>1.0>model.yaml Описание базовой модели: .. code-block:: yaml default_string: &ds name: Строка type: - string - STRING length: 0 nullable: NULL key: NONE source: NONE default_number: &dn name: Число type: - integer - INTEGER length: 0 nullable: NULL key: NONE source: NONE primary_key: &pk name: Ключ type: - string - STRING length: 0 nullable: NULL key: PRIMAY source: NONE static_value: &sv name: Статическое значение type: - string - STRING length: 0 nullable: NULL key: NONE source: STATIC //зарезервированное значение default_value: Значение //статическое значение без извлечения env_value: &ev name: Значение из окружения type: - string - STRING length: 0 nullable: NULL key: NONE source: ENV //зарезервированное значение default_value: Значение если нет переменной окружения env_key: ключ_переменной_окружения base_model: &base_model default_fields: &default_fields .. _data_model: Модель данных ############### Модель данных (пользовательская модель данных, custom-модель) - описание метаданных витрины, извлекаемых при обращении потребителя к СМЭВ QL серверу. Содержит названия ресурсов (таблиц), атрибутов ресурсов, связи с другими моделями, ограничения на использование ресурсов для потребителей, а так же источники хранения ресурсов. Каждая модель представляет из себя YAML-файл, который должен быть соединен с базовой моделью (:ref:`basic_data_model`) данных для прохождения валидации. Хранится в файловой системе СМЭВ QL сервера по пути: ``models>custom>1.0>model.yaml`` Структура модели данных """"""""""""""""""""""""" Первый блок модели определяет ее мета-данные и атрибутивный состав. **Мета-данные и поля модели** .. code-block:: yaml resources: # slots — техническое название модели, по нему производятся все связи - slots: *base_model # значение name — название модели на русском языке name: Слоты # fields — список полей модели fields: # список полей может включать перечень полей из default_fields <<: *default_fields # поля по-умолчанию наследуются от ds (default_string) из базовой модели id: *ds resource_id: *ds # у поля может быть переопределен source (по-умолчанию у каждого поля источник всей модели) type: *ds source: field: tag_type age: *ds source: field: tag_age visitTime: *ds duration: *ds status: *ds create_ts: *ds update_ts: *ds update_ts: *ds Второй блок модели описывает связи моделей друг с другом через ключи ``primary_key`` и ``foreign_key``. Ключи могут быть составными (описывается массивом), ключи не обязательно должны быть ключами из БД. Связи имеют два типа: 1. belongs_to 2. has_many (один ко многим) **Связи модели** .. code-block:: yaml # Блок connections описывает связи модели (по названию) через явно указываемых два ключа connections: belongs_to: - resource: primary_key: [ id ] foreign_key: [ resource_id ] has_many: - book: primary_key: [ id ] foreign_key: [ slot_id ] - unaccessible_period: primary_key: [ resource_id, type ] foreign_key: [ resource_id, type ] Блок ограничений и разрешений использования условий поиска. **Связи модели** .. code-block:: yaml # Блок conditions описывает ограничения и разрешения на использование условий поиска conditions: allowed: [id, name] # если заполнено, то поиск разрешен только по этим полям и полям с ключами denied: [snils] # если заполнено, то поиск запрещен по этим ключам always: # наличие условий в блоке always должно ко всем запросам ресурса добавлять эти условия, если указаны в запросе, то перетирать - region: ["=", "77"] - blocked: ["=", true] Блок — **extract**, описывает названия **source** из которого нужно извлекать модель и ее таблицу. **Источники модели** .. code-block:: yaml extract: source: - name: prostore table: misdm.slots .. _sources_by_conditions: **Источники по условиям** В блоке c указанием источника в модели допускается указание условий его выбора через блок ``conditions``. Блок ``conditions`` содержит массив условий применения источника на основании значений полученных в запросе атрибутов: .. code-block:: yaml extract: source: - name: prostore1 table: misdm.slots conditions: # попадание в промежуток - range: field: age from: 0 to: 2 - eq: field: color not: "blue" - name: prostore2 table: misdm.39slots conditions: # ограничения по (не)равенству - eq: field: resource_id is: 1 - name: prostore3 table: misdm.39slots conditions: # ограничения по наличию в источнике - eq: field: snils extract: source: redis table: default_table key: resource_hashed_id algorithm: md5 # select count(*) > 0 from offices.offices where resource_hashed_id = ? # параметр: md5(snils) is: true - name: prostore_default table: misdm.39slots conditions: - fallback: true Загрузка """""""""""" Модели данных считываются, валидируются и загружаются в память из папки **models** при запуске СМЭВ QL сервера. По-умолчанию используется версия **model**, на которую ссылается symlink **current**, при его отсутствии по-умолчанию считается **старшая** версия. .. note:: Модели и версии, **начинающиеся с подчеркивания (_) НЕ загружаются**, они находятся в стадии проектирования. Guard-атрибуты """""""""""""""" Для ограничения возможности получения некоторых атрибутов без предварительного предоставления их же (или дополнительных) значения, извлекающим необходимо определить атрибуты-ограничители в блоке guard. Пример: .. code-block:: yaml fields: <<: *default_fields first_name: *ds last_name: <<: *ds guard: [last_name] snils: <<: *ds guard: [last_name first_name snils] В примере извлечение **first_name** не ограничивается. Для получения **last_name** фамилия должна быть передана в блоке conditions, а для получения **snils** в conditions должны присутствовать фамилия, имя и сам СНИЛС. Распределённый запрос ###################### При обращении Потребителя к СМЭВ QL серверу, исполнение запроса (получение данных по запросу) может происходить с участием одного или нескольких источников (поставщиков данных). В случае если для получения данных шло обращение к двум и более источникам, то такой запрос называется распределенным. Описание источников получения данных задается на уровне модели данных в блоке ``extract:``(:ref:`sources_by_conditions`). При этом Потребитель всегда обращается к одному СМЭВ QL, от которого ожидает получение всех данных о всех источников. .. _disturbed_query: .. figure:: img/disturbed_query.png :align: center :alt: Пример схемы распределенного запроса Пример схемы распределенного запроса