.. _smev_ql_doc:

Назначение СМЭВ QL сервера
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

О системе
###########

СМЭВ QL сервер - это компонент взаимодействия с витриной данных, который реализует её типовое API согласно внутренней спецификации 
СМЭВ QL. 

Основным назначением  СМЭВ QL сервер является обработка REST-запросов Потребителей на получение или изменение данных за счёт 
формирования оптимальных (простых) SQL-запросов к витрине.

Для Потребителя взаимодействие со СМЭВ QL сервером равнозначно виду информационного обмена - Обмен с использованием регламентированных 
запросов типа «Rest-сервис».

Основной принцип работы СМЭВ QL сервера заключается в следующем:

1. СМЭВ QL принимает на вход REST-запрос, который содержит перечень запрашиваемых ресурсов, условий выбора данных, требуемые атрибуты ответа и 
   пр. После чего определяет данные каких объектов и из каких источников необходимо извлечь. При этом определение источников происходит на 
   основании заранее описанных моделей данных, которые хранятся на сервере в файлах вида ``model.yaml`` (что извлекать) и ``source.yaml`` 
   (откуда извлекать). Запросы также могут быть заранее сохранены в файлах ``query.json`` (Регламентированные СМЭВ QL запросы).
2. Далее формирует, в определенной последовательности (на основании плана выполнения запросов), столько SQL-запросов к источникам данных, 
   сколько ресурсов было запрошено в исходном запросе от клиента. При этом запросы могут выполняться как последовательно, в случае если в 
   запросе ресурсы имеют вложенность (иерархию) или параллельно, если ресурсы указаны на одном уровне. Это позволяет значительно упростить 
   SQL-выражения и уменьшить сложность запроса к БД.
3. Обрабатывает результаты выполнения SQL-запросов по мере их поступления от источников.
4. Затем формирует и передает комплексный ответ клиенту.

.. _system_smev_ql:
.. figure:: /_static/img/modules/smevql/system_smev_ql.jpg
    :align: center
    :alt: Схема СМЭВ QL Сервера

    Схема СМЭВ QL Сервера

Цели СМЭВ QL сервера
#####################

Целями создания СМЭВ QL сервера являются:

1. Повышение скорости предоставления ответов от витрины данных Поставщика по сравнению с типовым видом взаимодействия Агент - Витрина. 
2. Защита витрины данных Поставщика от неоптимальных запросов.
3. Сокращение объёма ответов.
4. Сокращение количества передаваемых запросов от Потребителей.
5. Повышение скорости развития услуг ЕПГУ.

Задачи СМЭВ QL сервера
#############################

Основные задачи СМЭВ QL сервера:

1. Формирование API и модели данных витрины .
2. Приём REST-запросов от Потребителей через Агент СМЭВ4.
3. Формирование простых SQL-запросов к витрине.
4. Формирование распределенных запросов к нескольким витринам.
5. Формирование и передача ответа Потребителю.
6. Проверка и формирование цифровых подписей ответов.
7. Описание и исполнение при вызове модели машины состояний.
8. Нотификация подписчиков при изменении данных витрины.
9. Предоставление внешним клиентам OpenAPI для управления.

Место СМЭВ QL сервера в ИТ-ландшафте
#####################################

СМЭВ QL сервер взаимодействует со следующими компонентами СМЭВ4:

1. Агент СМЭВ4.
2. Сервис исполнения запросов ядра витрины данных.
3. Сервер криптографии (Notarius).
4. Сервис формирования документов.

.. _landscape:
.. figure:: /_static/img/modules/smevql/landscape.png
    :align: center
    :alt: Схема взаимодействия СМЭВ QL Сервера с компонентами СМЭВ4

    Схема взаимодействия СМЭВ QL Сервера с компонентами СМЭВ4

Язык и синтаксис
#################

Моделирование
"""""""""""""""""

Для моделирования документного слоя данных в спецификации выбран язык разметки ``YAML``.

Запросы и ответы
"""""""""""""""""""

Для написания запросов, а также в качестве сериализатора ответов, спецификация определяет использование ``JSON``.

Типизация
###########

Фактические типы данных наследуют типы данных ``JSON`` (включая NULL):

- string;
- number;
- object;
- array;
- boolean;
- null.

Типы данных в модели и приведение типов
"""""""""""""""""""""""""""""""""""""""""

В описании модели допускается указание фактического типа данных атрибута ресурса **вторым элементом массива type**. 
Указание является опциональным, по умолчанию подразумевается неограниченный **STRING**. 

Пример из описания модели:

.. code-block:: yaml
  
  fields:
    id:
      name: Идентификатор записи
      type:
        - number
        - SHORT
      length: 20
      nullable: not NULL
      key: PRIMARY


В качестве второго уточняющего типа следует применять типы НСУД:

- STRING;
- DOUBLE;
- FLOAT;
- BOOLEAN;
- BYTE (не поддерживается Компонентом "Витрина данных");
- BINARY;
- BIG_DECIMAL (не поддерживается Компонентом "Витрина данных");
- LONG;
- INTEGER;
- SHORT;
- DATE;
- TIME;
- TIMESTAMP.


Моделирование данных
#######################

Модели данных описываются в формате ``YAML`` в папке проекта ``models`` согласно спецификации СМЭВ QL.

Структура базовой модели приведена в :numref:`basic_data_model`.

Структура базовой модели приведена в :numref:`data_model`.


Метрики
#############

Для обеспечения возможности сбора информации о работе СМЭВ QL Сервера реализован набор метрик, 
обеспечивающий формирование показателей:

- время исполнения входящих запросов;
- количество успешных / не успешных выполнений входящих запросов;
- время исполнения исходящих запросов или обращений к СПО;
- количество успешных / не успешных выполнений исходящих запросов или обращений к СПО.