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

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

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

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

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

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

.. _system_smev_ql:
.. figure:: img/system_smev_ql.png
    :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. Предоставление внешним клиентам OpenAPI для управления.

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

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

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

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

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

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

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

Для моделирования документного слоя данных в спецификации выбран язык разметки ``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.

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

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

.. note:: Заливка данных через через модуль RESt-Uploader и DATA-Uploader не предусматривают параллельную заливку в датамарты вместе с другими инструментами. Параллельная заливка данных в те же датамарты вручную или средствами ETL приведет к конфликту в работе с дельтами и к ошибкам соответственно.


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

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

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

`Пример по подключению журналирования. <https://platform-docs.v-serv.ru/online-documentation/home/maintain-tools/platform-v-monitor/applied-journal/quick-start/>`_

`Пример по подключению мониторинга. <https://platform-docs.v-serv.ru/online-documentation/home/maintain-tools/platform-v-monitor/monitoring/quick-start/>`_