.. _smev_ql_concept:

Основные понятия СМЭВ QL
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _source:

Ресурс
#########

Ресурс представляет собой объект (таблица) хранилища Поставщика, данные которого могут быть получены или изменены Потребителем при 
запросе к СМЭВ 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"]         
            }


.. _state_machine_concept:

Машина состояний
#################

СМЭВ QL содержит встроенную машину состояний (или стэйт-машина) для изменения ресурсов витрин данных. Одновременно с этим стейт машина 
может в качестве подтверждения перехода состояния использовать внешний источник. 

Карта состояний и переходов машины состояний описывается в виде YAML-файла ``state.yaml`` располагаемого в папке 
``states/<имя-модели>/<х.х версия модели>`` инстанса СМЭВ QL сервера.

.. _basic_data_model:

Базовая модель данных
#######################

Базовая модель данных - это описание типовых элементов и форматов данных, которые могут использоваться (наследоваться) при 
создании пользовательских моделей (:ref:`data_model`).

Базовая модель не описывает схему данных витрины и не участвует в логике СМЭВ QL при обработке запросов. Хранится в файловой 
системе СМЭВ QL сервера по пути: ``models>base>1.0>model.yaml``



.. _data_model:

Модель данных
###############

Модель данных (пользовательская модель данных, custom-модель) - описание метаданных витрины, извлекаемых при обращении потребителя к 
СМЭВ QL серверу. Содержит названия ресурсов (таблиц), атрибутов ресурсов, связи с другими моделями, ограничения на использование 
ресурсов для потребителей, а так же источники хранения ресурсов.

Каждая модель представляет из себя YAML-файл, которая может ссылаться на базовую модель данных (:ref:`basic_data_model`) для оптимизации описания. 

Хранится в виде YAML-файла ``model.yaml`` по пути: ``models>custom>1.0>model.yaml`` инстанса СМЭВ QL сервера.

.. _disturbed_query:

Распределённый запрос
######################

При обращении Потребителя к СМЭВ QL серверу, исполнение запроса (получение данных по запросу) может происходить с участием одного или 
нескольких источников (поставщиков данных). В случае если для получения данных шло обращение к двум и более источникам, то такой запрос 
называется распределенным. 

Описание источников получения данных задается на уровне :ref:`data_model` в блоке ``extract:`` :ref:`sources_by_conditions`. 
При этом Потребитель всегда обращается к одному СМЭВ QL, от которого ожидает получение всех данных о всех источников. 

.. _disturbed_query_img:

.. figure:: img/disturbed_query.png
    :align: center
    :alt: Пример схемы распределенного запроса

    Пример схемы распределенного запроса