Updated at 2024-05-09 03:30:39.608072

Introduction to Tarantool Data Grid 2.0

Tarantool Data Grid (TDG) - это комплексный продукт для быстрого создания и поддержки бизнес-решений на платформе Tarantool. Tarantool Data Grid создан на основе Tarantool Enterprise и включает ряд дополнительных компонентов, позволяющих создавать решения быстро и с минимальным участием разработчиков.

Уже «из коробки» вы получаете максимум готовой функциональности для реализации типовых сценариев, таких как проверка целостности данных или обработка ошибок. Остаётся только настроить их под конкретную схему данных и бизнес-логику решения.

Here are the guides that explain how to work with the Tarantool Data Grid system:

Основные возможности

Хранение данных

Хранилище данных TDG предоставляет все возможности Tarantool Enterprise: хранение в памяти и на диске, шардирование, репликацию и многое другое. Кроме этого, в TDG реализованы дополнительные возможности, такие как управление схемой данных в формате Apache Avro и контроль целостности.

Хранение и исполнение бизнес-логики

TDG позволяет создавать сервис-функции для реализации бизнес-логики и работы с данными. Эти функции могут выполняться автоматически по расписанию или вызываться извне с помощью API.

Интеграция/API

TDG предоставляет широкие возможности по интеграции с внешними системами. Для интеграции могут использоваться протоколы GraphQL, REST API, Apache Kafka, iproto (бинарный протокол Tarantool) и другие.

Безопасность

Встроенные инструменты TDG позволяют гибко настраивать параметры безопасности системы. Среди них – настраиваемая ролевая модель, интеграция с Active Directory, аудит доступа и другие инструменты.

Практическое применение

Наши клиенты применяют TDG для таких задач как:

Пример бизнес-решения на TDG

Пример решения: витрина для интеграции данных по счетам и кредитам клиента, чтобы отображать их в мобильном и веб-приложении.

Пример решения

Задачи:

Чтобы создать такое бизнес-решение на Tarantool Data Grid, нужно выполнить всего 3 шага:

Шаг 1: Описать модель объекта данных

Модель объекта данных

Шаг 2: Задать логику объединения данных

Логика объединения данных

Шаг 3: Запустить решение на одном сервере

Решение

Release notes

What’s new in Tarantool Data Grid 2.0

Tarantool Data Grid (TDG) version 2.0 brings a lot of new features. This document tells about all major changes and new capabilities in version 2.0:

Simplified architecture

Tarantool Data Grid 2.0 has four easily scalable components:

Узлы можно добавлять в кластер мгновенно, при этом данные перераспределяются автоматически. Один кластер TDG состоит из нескольких наборов реплик. Если один из серверов остановится, набор реплик продолжит работать, не теряя при этом никаких данных.

You can create as many replica sets with storage, runner, and connector components as you like. The only exception is the core. There can be only one replica set that contains the core component.

Handlers instead of data pipelines

When Tarantool Data Grid receives a data package from an external system, it needs to process the data before putting it into a storage.

In version 1.6, data pipelines processed the incoming data by consecutively calling multiple functions. However, writing code to build these pipelines was a bit of a challenge.

In version 2.0, there are handlers instead of pipelines. Handlers are functions that process the incoming and outcoming data. You can write a handler function using Lua and then bind it to any connector.

Input-процессор обрабатывает все входящие данные. После этого объекты данных проверяются и помещаются в хранилище. Если процесс проверки завершается с ошибкой, объекты попадают в ремонтную очередь.

Visual data model constructor

Data model explicitly determines the structure of data. All incoming data is verified, validated, and stored by the provided data model.

Tarantool Data Grid uses Avro Schema to describe data model. In version 2.0, there is no need to write code to describe data structure. Everything is done via an interface that is called a model editor. Model editor has multiple options like adding a field, naming it, setting its type and value, as well as leaving comments.

Optional data versioning

Data versioning allows one to trace what changes have been made to a data package and when. Data package is a collection of data.

Когда пакет данных попадает в хранилище Tarantool Data Grid, он идентифицируется по первичному индексу. Если первичный индекс у входящего пакета совпадает с уже имеющимся пакетом, TDG не будет удалять хранящиеся данные. Он сохранит новые данные как новую версию этого пакета.

Version history often comes in handy, but it has one side effect. The bigger version history is, the more it influences the performance of the storage.

In TDG 2.0, versioning is off by default. It means that data packages with the same primary index will rewrite each other. This increases performance and reduces the amount of space taken up by the database. But if you need to keep version history, you can always switch this option on.

Changelog

This document contains up-to-date information regarding Tarantool Data Grid release notes. The log format is based on Keep a Changelog, and the versioning follows Semantic Versioning rules.

[2.11.2] – 2024-03-13

[2.11.1] – 2024-02-27

[2.11.0] – 2024-02-26

[2.10.0] – 2023-12-11

[2.9.0] – 2023-11-21

Updated

  • SDK обновлен до версии 2.11.1-0-r605.

  • Cartridge обновлен до версии 2.8.4.

  • Обновлены зависимости web UI.

Added

  • [Breaking change] Частично удалена функциональность тенантов.

  • Добавлена опция handler для Kafka-коннектора.

  • Добавлена обработка ошибок в Kafka-коннекторе.

  • Добавлены метрики обработчика исходнящих данных.

  • Добавлена возможность использования (require) кода из конфигурации в расширениях.

Fixed

  • Исправлен вызов deinit до вызова init в роли scheduler.

  • Исправлено отсутствие сообщений об ошибках в Kafka consumer.

  • Исправлено удаление частей конфигурации коннекторов в web UI.

[2.8.0] – 2023-08-30

Updated

  • SDK обновлен до версии 2.11.1-0-r579.

  • Cartridge обновлен до версии 2.8.2.

  • expirationd обновлен до версии 1.5.0.

  • Обновлены зависимости для веб-интерфейса.

Added

  • [Breaking change] Удалены настройки тенантов из веб-интерфейса.

  • Модуль compress добавлен в sandbox.

  • Добавлены настройки Kafka consumer в sandbox: consumer_seek_partitions и consumer_metadata.

  • Добавлены настройки Kafka consumer в sandbox: consumer_pause, consumer_resume и consumer_status.

  • Добавлен параметр initial_state во входящую конфигурацию Kafka.

  • Добавлен менеджер для управления вводом Kafka с помощью флагов в etcd.

  • В сообщение Kafka consumer добавлено название коннектора.

  • Добавлены метрики для обработчика REST.

  • Для tdg_service_user добавлена возможность вызова функции box.info().

  • Добавлена поддержка алгоритма сжатия zlib для полей типов данных.

Fixed

  • Исправлен запуск задач перед бутстрапом vshard.

  • Исправлена обработка сложных нулевых типов в сервисах.

  • Исправлена визуальная ошибка в EditDataActionForm.

  • Исправлена обработка параметра lifetime_hours=0.

[2.7.2] – 2023-07-21

[2.7.1] – 2023-06-07

[2.7.0] – 2023-05-30

Updated

  • SDK обновлен до версии 2.11.0-0-r563.

  • Cartridge обновлен до версии 2.8.0.

  • metrics обновлен до версии 1.0.0.

  • kafka обновлен до версии 1.6.6.

Added

  • icu-date заменен на модуль datetime во внутренних механизмах.

    Note

    Поведение модулей datetime и timezone могло измениться в некоторых редких случаях. В рамках тестирования такие изменения не выявлены.

  • LuaJIT переведен в режим GC64.

  • Добавлена функция repository.update_batch.

  • Добавлена функция repository.call_on_storage_batch.

  • Добавлен экспериментальный режим построения индексов в фоне. Включается опцией background_index_build.

  • Модуль clock добавлен в sandbox.

  • Добавлена возможность установки ключа (key) для отправки сообщений в kafka.

  • Watchdog выключен по умолчанию. Вместо него используется механизм fiber.slice.

  • Для HARD_LIMITS_SCANNED установлено значение unlimited. Вместо него используется механизм fiber.slice.

Fixed

  • Запрещены union-типы с одним полем.

  • Удалены некорректные предупреждения в веб-интерфейсе при выполнении некоторых GraphQL-запросов.

  • Исправлена ошибка при передаче аргументов сервисов через REST API.

  • Исправлена ошибка при изменении union-типа на другой тип.

[2.6.9] – 2023-04-27

[2.6.8] – 2023-04-07

Updated

  • Cartridge updated to build (5c30d1cc).

  • expirationd updated to 1.4.0.

  • metrics updated to 0.17.0.

  • avro-schema updated to 3.1.0

  • smtp updated to 0.0.7.

  • SDK updated to 2.10.6-0-r549.

Added

  • Added aarch64 support to Docker build.

  • Added validation for fields being indexed twice.

  • Changed the behavior of the Submit button in the Model and KeepVersionModal components.

  • Added the validation that the jobs.max_jobs_in_parallel option value is positive.

Fixed

  • Fixed a bug that occurred on adding a nullable logical type field.

  • Fixed possible freezing on local RPC calls.

  • Fixed a possible crash of the fiber that runs jobs on storages.

[2.6.7] – 2023-02-27

[2.6.6] – 2023-02-20

[2.6.5] – 2023-02-03

[2.6.4] – 2022-11-16

Updated

  • SDK updated to 2.10.4-0-r518.

  • Cartridge updated to build (f4258ae2).

  • metrics updated to 0.15.1.

  • kafka updated to 1.6.2

Added

  • Added the ability to specify in the config the user arguments to pass to the task function body.

  • Added the ability to run tasks on specific runners, which are marked with labels in the config.

  • Improved editor components:

    • Full-text search on the Model and Code tabs.

    • Display line numbers on the Model and Test tabs.

    • Save the state of GraphQL and Test tabs when switching tabs and refreshing the page.

  • Token names now appear in audit logs.

Fixed

  • Fixed the inability to use the Enum type in service arguments.

[2.6.3] – 2022-10-06

Updated

  • SDK updated to 2.10.3-0-r510.

Added

  • Added lifetime_hours value 0 (“forever”).

  • Added the msgpack module to the sandbox.

[2.6.2] – 2022-09-05

Updated

  • Cartridge updated to 2.7.6.

  • metrics updated to 0.15.0.

  • SDK updated to 2.10.2-0-gf4228cb7d-r502.

Added

  • Display errors that occur in services called via IPROTO.

Fixed

  • Fixed incorrect display of errors.

[2.5.3] – 2022-08-18

Fixed

  • Fixed affinity calculation with pagination.

  • Fixed a confusing warning in the Kafka connector.

  • Fixed assignment of nested records in repository.update.

[2.5.2] – 2022-08-12

Added

  • Added the support for Kafka headers in the input connector.

[2.6.1] – 2022-08-11

Added

  • Added the new logical type Timestamp.

  • Added keep_version_count value 0 (“unlimited”).

  • Added the skip_result option for repository.put and repository.put_batch.

  • Added the new function tonumber64 to the sandbox.

  • Allowed to specify collations for specific parts of an index.

  • Implemented the audit log based on the Tarantool 2.10 audit module.

Fixed

  • Добавлена валидация для обнуляемых полей в repository.update.

  • Disabled the first option in repository.delete.

  • Fixed affinity calculation with pagination.

  • Fixed incorrect validator creation.

[2.6.0] – 2022-06-30

Breaking changes

  • Renamed tdg_expiration metrics to expirationd.

Added

  • Added the LDAP settings page.

  • Enabled the Tarantool flightrec feature by default.

  • Implemented the tuple compression.

  • Added the support for Kafka headers in the input connector.

  • Enhanced the datetime sandbox module with new onboard Tarantool datetime module functions.

Fixed

  • Fixed several frontend bugs.

  • Fixed a confusing warning in the Kafka connector.

  • Fixed an incorrect GraphQL error message in logs.

  • The file connector now waits until at least one runner instance is available.

  • Fixed assignment of nested records in repository.update.

[2.5.1] – 2022-06-30

Added

  • Added the Config file name column to the Configuration Files table.

  • Added the Docker image with dev mode enabled.

  • Support logical type in repository for non-indexed fields.

Fixed

  • Boolean kafka metrics are now numeric.

  • Reworked log and audit log filtration.

  • Added error handling in repository.put_batch.

[2.5.0] — 2022-04-25

Breaking changes

  • all is now the default debug option in Kafka debug mode.

  • Query plan field name changed to _query_plan (with single underscore) to conform to the GraphQL specification.

  • Removed all string metrics from Kafka and file connectors.

Added

  • Added skip_result flag for update and delete interfaces (iproto, REST, graphql, repository).

  • Added logger checkboxes to the Kafka connector modal.

  • The list of roles on the user/token creation and editing form can now be filtered by tenant.

  • Added GraphQL for Kafka consumers check (config.kafka_check_input).

  • Added the indexed_by option to the REST interface to choose scan index.

  • Options can now be passed to LDAP connections.

  • Added the “Test Connection” button to the Kafka configuration modal.

  • Added availability to load custom roles by config.

  • Added new functions table.make_map and table.make_array to the sandbox.

  • Added scanned and returned tuples count histogram to metrics.

Fixed

  • The default hard limits returned value is no more equal to scanned value.

  • The default value of tenant field in the “new user” modal is now “Default”.

  • Disable output mode is now removed for the Kafka logger.

  • topic, key, offset, and partition are now passed to the handler with a Kafka message.

  • A LDAP user that has several groups can now use access actions from all corresponding roles mapped for these groups.

  • Finalized the validation of the “Expires in” field in the user creation pop-up.

  • Fixed “Cannot perform action with bucket” error on repository.put_batch call.

  • Fixed the error that appeared if a service used utf8 enums in args.

  • In case of problems with the Kafka connector, an issue is now displayed.

  • Fixed the error that appeared when a LDAP user accessed the GraphQL API.

  • Banned deletion of data action if it is used in a role.

[2.4.0] — 2022-01-28

Updated

  • Updated bundle to 2.8.3-0-g01023dbc2-r442.

Added

  • Added metrics for IProto API.

  • Error messages are now displayed in the “Edit tenant” pop-up.

  • Case-insensitive UPN can now be used with LDAP.

  • Introduced the enable_debug configuration option for Kafka connectors.

  • It is now allowed to specify the read, balance, and mode options for GraphQL.

  • Introduced data queries via the @options directive.

  • Custom headers and status code can now be returned by the auth plugin.

  • Added metrics for the Kafka connector.

  • Added new metrics for the file connector.

  • Logger can now be configured for Kafka connectors (with the logger option that can have one of the following values: stderr, tdg, disable).

  • The maintenance.clear_data API can now accept type name to clear spaces of single type.

  • Introduced graceful shutdown for the connector role.

Fixed

  • Improved the “Compare configuration” popup.

  • The metrics format for the REST data API is now more convenient.

  • Disabled autocompletion in the role editing form.

  • The error message in the delete tenant modal is now cleared after the error is fixed.

  • Removed the Kafka connector ssl.key.password option from the UI.

  • Fixed the issue when a task could hang in pending state if a runner was unavailable for some time.

[2.3.0] — 2021-10-27

Updated

  • Cartridge updated to 2.7.3.

Added

  • Custom timeout can now be specified for map_reduce and call_on_storage.

  • Expiration statistics added to exported metrics.

  • Added the use_active_directory option for LDAP.

  • Added the organizational_units option for LDAP.

Fixed

  • Expired tuples are not returned anymore.

  • Fixed empty filters handling in queries.

  • Fixed an issue that could lead to deadlock in several TDG subsystems.

  • Fixed several task/job issues.

  • Fixed array assignment in updates.

  • Fixed LDAP subsystem issues.

  • Cluster cookie authorization is now banned.

  • The null type in GraphQL requests is now banned.

Deprecated

  • The “Expiration” configuration section was renamed to “Versioning”.

[2.2.0] — 2021-09-29

Added

  • Added support for ILIKE, case-insensitive LIKE.

  • LIKE/ILIKE is allowed only for string fields and explicitly banned for indexes.

  • Tracing now supports inheritance.

  • Added metrics for the REST data interface.

  • Added a GraphQL interface for locking config sections to prevent section deletion.

  • The model and expiration GraphQL APIs were replaced with the data_type API.

  • Introduced a GraphQL interface for metrics settings.

Fixed

  • Some multitenancy bugs fixed.

  • Backward iteration without cursor is now banned.

  • The namespace field is now banned in model.

[2.1.1] — 2021-09-01

Added

  • Enums are now validated during updates.

  • Added input_processor.storage.type validation.

  • It is now possible to setup more than one kafka input.

  • Вместо файбера TDG time_delta теперь нужно использовать параметр Cartridge issues_limits.

  • Added validation in cases where absent data types are used as arguments/return values and listed as nullable array elements.

Fixed

  • The case when expiration was defined, but the model wasn’t, is now processed correctly.

  • Nullable array elements are now processed correctly.

  • Multipart indexes with 2+ logicalTypes now work correctly.

  • It is now impossible to assign identical names to different connectors in the configuration.

[2.1.0] — 2021-08-24

Initial public release 2.1.0.

Архитектура

В этой главе описывается архитектура Tarantool Data Grid.

Основные архитектурные компоненты TDG изображены на схеме ниже.

Архитектурная диаграмма

Как видно из схемы, различные аспекты работы TDG разделены по соответствующим кластерным ролям: Storage, Connector, Runner и Core. Каждый экземпляр (узел) в кластере может иметь одну или более ролей. Подробнее о кластерных ролях рассказывается в разделе Кластерные роли.

Хранение данных: Tarantool

Для хранения данных в TDG используется распределённое хранилище Tarantool. Его функциональность включает:

Таким образом, TDG обеспечивает “из коробки” распределённое, высокопроизводительное, отказоустойчивое и масштабируемое хранение данных.

Кроме того, в TDG доступны другие функции хранения данных, такие как:

Доступ к данным: GraphQL и REST API

Для доступа к данным TDG используются два основных способа: GraphQL и REST API.

Оба способа поддерживают запросы с использованием индексов (первичных, вторичных и составных), операторы сравнения, множественные условия и другие возможности выборки данных.

Точки доступа создаются автоматически на основе модели данных и доступных сервисов. Эти сервисы также можно вызывать через GraphQL и REST API.

Исполнение бизнес-логики: Lua

TDG предоставляет возможность хранения и исполнения пользовательской бизнес-логики, например, валидации или преобразования данных.

Для добавления необходимой бизнес-логики нужно реализовать её в виде функций на языке Lua и загрузить их в TDG.

Загруженные функции можно использовать несколькими способами:

Взаимодействие с внешними системами

Для обмена данными с внешними системами в TDG используются коннекторы. Коннекторы бывают двух типов: входящие (input) для получения данных извне и исходящие (output) для отправки данных из TDG.

Коннекторы позволяют обмениваться данными с такими источниками как:

Администрирование и безопасность

TDG предоставляет инструменты для управления различными техническими функциями, в том числе:

Для управления конфигурацией TDG доступны два способа:

Для мониторинга и расследования инцидентов TDG предоставляет метрики кластера в формате Prometheus. Метрики доступны для получения через REST API и визуализации в Grafana.

Встроенные инструменты безопасности TDG позволяют настроить доступ к различным функциям для пользователей и внешних систем. Для этого используется ролевая модель доступа. Роли могут быть приписаны как к профилям (для настройки доступа пользователей), так и к токенам приложений – средству авторизации приложений для взаимодействия с TDG. Для расследования инцидентов безопасности доступен журнал аудита.

Кластерные роли

Экземпляры TDG в кластере выполняют те или иные функции в соответствии с назначенными им кластерными ролями. Каждый экземпляр может иметь одну или несколько ролей.

В TDG существует четыре основных кластерных роли:

Еще одна кластерная роль, failover-coordinator, позволяет включать режим восстановления после сбоев с сохранением состояния (stateful failover). Подробности можно найти в документации Tarantool Cartridge.

Кластерные роли назначаются наборам реплик (replica set). Каждый экземпляр получает роли того набора реплик, в который он входит. В каждом наборе реплик все экземпляры взаимозаменяемы: на них хранится одно и то же состояние. Таким образом обеспечивается резервирование и устойчивость к сбоям.

Архитектура кластерных ролей

Роль Core

Роль core используется для выполнения собственных функций TDG. Экземпляры с этой ролью обеспечивают управление моделью данных, сервисами, настройками безопасности и доступа и другими функциями. На этих экземплярах хранится внутренняя информация TDG и не хранятся пользовательские данные.

В кластере может быть только один набор реплик с ролью core.

Роль Storage

Роль storage используется для хранения пользовательских данных. На экземплярах с этой ролью создаются спейсы Tarantool в соответствии с моделью данных.

Объединение экземпляров storage в наборы реплик обеспечивает шардирование и репликацию данных: каждый набор реплик хранит своё подмножество данных (shard), и это подмножество реплицируется на все экземпляры набора реплик.

Количество наборов реплик Storage определяется объемом хранимых данных.

Роль Runner

Роль runner используется для выполнения пользовательской бизнес-логики. На этих экземплярах с помощью встроенного в Tarantool Lua-интерпретатора выполняются загруженные в TDG пользовательские скрипты: сервисы, задачи, обработчики входящих и исходящих данных.

Экземпляры runner не хранят состояние и используются только для исполнения кода. Таким образом, они все эквивалентны, и объединение в наборы реплик не влияет на их функциональность.

Роль Connector

Роль connector используется для сетевого взаимодействия с внешними системами. На экземплярах с этой ролью создаются адреса (endpoints) для обращения к кластеру через GraphQL и REST API, а также коннекторы для подключения по различным протоколам: HTTP (JSON или SOAP), Apache Kafka или iproto.

Экземпляры connector не хранят состояние и используются только для внешних подключений. Таким образом, они все эквивалентны, и объединение в наборы реплик не влияет на их функциональность.

Administrator’s guide

This document explains how to work with Tarantool Data Grid (TDG) if you are an administrator.

Deployment

В этой главе описаны способы, которыми можно развернуть TDG для разработки и тестирования (development environment).

Для получения помощи в развертывании кластера TDG для промышленной эксплуатации (production environment) заполните форму для связи на этой странице или напишите на sales@tarantool.io.

First deployment with Ansible

В этом руководстве описано, как впервые быстро развернуть Tarantool Data Grid (TDG) с помощью Ansible. Здесь приведен вариант развертывания TDG на двух виртуальных машинах с заданной конфигурацией.

Getting a TGZ file for deployment

To deploy Tarantool Data Grid, you need an RPM (.rpm), TGZ (tar.gz), or Docker image (docker-image.tar.gz) file. For deployment with Ansible, you can only use either an RPM or a TGZ file. For now, a TGZ file will do just fine. It is easier to deploy and does not require root access.

Download a TGZ file of the latest version at the customer zone of tarantool.io. Make sure your browser did not unarchive the downloaded file: the file extension should be tar.gz.

If you do not have access to the customer zone, contact us using the form on this page or write to sales@tarantool.io.

Setting up virtual machines

Чтобы развернуть TDG, вам нужно запустить две виртуальные машины с ОС Linux (желательно CentOS 7/RHEL 7) и доступом по SSH. Если у вас уже установлены приведенные ниже или альтернативные виртуальные машины, то пропустите эту главу. Если нет, то следуйте инструкции.

Установите VirtualBox для запуска виртуальных машин и Vagrant для автоматизации процесса конфигурации. Vagrant подготовит конфигурацию двух виртуальных машин с дополнительными сценариями для развертывания TDG.

Note

Перед установкой программного обеспечения проверьте, что разработчик не накладывает ограничений на использование — например, не ставит блокировки по IP-адресам. При возникновении проблем воспользуйтесь услугами альтернативных провайдеров виртуальных машин.

Make sure you have VBoxManage in your $PATH environment variable.

Check with the command:

$ which VBoxManage

In the downloaded TGZ file, there is a directory called deploy. There you’ll find Vagrantfile, which automates the creation of a test environment for cluster deployment.

Open the terminal, unpack the tar.gz archive, go to the deploy directory, and run virtual machines:

tar xzf tdg-<VERSION>.tar.gz # change <VERSION> for the TDG version you've downloaded
cd tdg2/deploy
vagrant up

This command will bring up two virtual machines with CentOS 7 and passwordless SSH access for user vagrant. IP addresses of those machines are: 172.19.0.2 and 172.19.0.3.

Deploying the cluster

Preparing

After you’ve created virtual machines, install locally Ansible and Tarantool Cartridge Ansible role (the latest 1.x version). If Ansible role version 2.x is available, you can choose it instead, but you may face some challenges.

Here is one of the ways to install Ansible and Ansible role:

pip install ansible~=4.1.0 # version 4.1 or later, but not version 5.x
ansible-galaxy install tarantool.cartridge,1.10.0

Configuring

In the deploy directory, there is the hosts.yml file. It contains cluster configuration.

Open it to set cluster cookie and path to package:

all
  vars:
    # cartridge_package_path: "../../packages/tdg-ENTER-VERSION-HERE.tgz" # path relative to playbook
    # cartridge_cluster_cookie: "ENTER-SECRET-COOKIE-HERE" # change for "secret-cookie"

Удалите #, чтобы раскомментировать эти строки, укажите версию TDG, которую вы скачали, и путь к TGZ-файлу. Также задайте cookie для кластера. Это должна быть уникальная строка, но для практики достаточно указать “secret-cookie”.

Here is an example:

all
  vars:
    cartridge_package_path: "../tdg-2.0.0-1132-g2358e716.tgz"
    cartridge_cluster_cookie: "secret-cookie"

If you need to, you can always edit this file to change cluster configuration. Here is some info about file sections:

  • all.vars — для общих переменных;

  • all.children.tdg_group.hosts for instances parameters

  • all.children.tdg_group.children to specify parameters for a group of instances:

    • to group the instances by the host, set their ansible_host parameter

    • to group the instances by replica set, set their replicaset_alias, roles, failover_priority parameters, and so on.

You can find more information about parameters in Tarantool Cartridge Ansible role documentation.

Deploying

В директории deploy находятся Ansible-плейбуки, которые помогут вам завершить развертывание. Есть два способа развернуть TDG с помощью плейбуков:

  • кластер TDG с полностью сконфигурированной топологией;

  • кластер TDG со списком экземпляров (инстансов, instances) без заданной конфигурации.

Чтобы полностью развернуть TDG с топологией, выполните эту команду:

$ ansible-playbook -i hosts.yml playbooks/deploy.yml

If you want to practice configuring the topology of the cluster via the web interface, run the playbook to deploy only instances:

$ ansible-playbook -i hosts.yml playbooks/deploy_without_topology.yml

Now you can open http://172.19.0.2:8081 in your web browser to see the cluster web interface. This is what you’ll see if you chose to deploy without topology:

Пример кластера

Managing the cluster

Configuring topology of the cluster

If you have deployed instances with topology, skip this topic.

If you have deployed instances without topology, you can now edit topology by creating replica sets and specifying their parameters in the web interface:

  1. On the Cluster tab, there is a set of unconfigured instances. Select the core instance with the 172.19.0.2:3001 URL and click Configure. You will get the Configure server dialog:

    Редактирование топологии

  2. In the Configure server dialog, specify two replica set parameters: replica set name and role.

    For the core instance, give the replica set name “core” and select the “core” role. After you’ve set the parameters, click Create replica set.

  3. Set the same parameters for the rest of the unconfigured instances as follows:

    Instance URL

    Replica set name

    Roles

    172.19.0.2:3002

    runner_1

    runner, connector, failover-coordinator

    172.19.0.2:3003

    storage_1

    storage

    172.19.0.2:3004

    storage_2

    storage

    172.19.0.3:3001

    runner_2

    runner, connector

  4. There are two instances left to configure, storage_1_replica with the 172.19.0.3:3002 URL and storage_2_replica with the 172.19.0.3:3003 URL.

    Join them to the already existing replica sets with storage roles:

    • Select storage_1_replica and click Configure.

    • In the Configure server dialog, switch to the tab called Join Replica Set.

    • Check storage_1 and click Join replica set.

    Присоединение экземпляра к набору реплик

    For storage_2_replica, repeat the same steps, but check storage_2 instead.

После того, как вы назначите все роли, нажмите “Bootstrap vshard”, чтобы “включить наборы реплик storage. Это инициализирует модуль Tarantool vshard. Подробнее об этом модуле можно узнать в документации по Tarantool.

Инициализация vshard

You’ve created virtual buckets that are allocated to storages according to the number of instances with the storage role.

Виртуальные сегменты

Starting or stopping instances

This step is optional.

In the deploy directory, there are also playbooks that start or stop the instances. You can stop and disable all instances by stop.yml playbook:

$ ansible-playbook -i hosts.yml playbooks/stop.yml

You can start and enable all instances by start.yml playbook:

$ ansible-playbook -i hosts.yml playbooks/start.yml

First manual deployment

В этом руководстве описано, как впервые быстро развернуть Tarantool Data Grid (TDG) вручную. В результате вы локально развернете кластер TDG с одним узлом.

Note

Чтобы развернуть TDG, вам понадобится ОС Linux (желательно CentOS 7/RHEL 7). Если у вас другая ОС, сначала вам нужно будет создать виртуальную машину с ОС Linux.

Getting a TGZ file for deployment

To deploy Tarantool Data Grid, you need an RPM (.rpm), TGZ (tar.gz), or Docker image (docker-image.tar.gz) file. For the first deployment, a TGZ file will do just fine. It is easier to deploy and does not require root access.

Download a TGZ file of the latest version at the customer zone of tarantool.io. Make sure your browser did not unarchive the downloaded file: the file extension should be tar.gz.

If you do not have access to the customer zone, you can get one by applying this form or writing to sales@tarantool.io.

Deployment

  1. Unpack tar.gz file:

    $ tar xzf tdg-<VERSION>.tar.gz # change <VERSION> for the TDG version that you've downloaded

  2. Запустите кластер TDG с одним узлом внутри распакованного архива tar.gz:

    $ ./tarantool ./init.lua --bootstrap true

    Если у вас уже установлен Tarantool, убедитесь, что для развертывания TDG вы используете ту версию Tarantool, которая была упакована в только что скачанный архив tar.gz.

  3. Перейдите на http://127.0.0.1:8080/, чтобы проверить развернутый кластер TDG:

    Сконфигурированный экземпляр

    By running tarantool ./init.lua --bootstrap true, you’ve deployed a configured instance with assigned roles. If you want to try and assign roles by yourself, run:

    $ tarantool ./init.lua

    В результате у вас будет экземпляр TDG в исходном состоянии:

    Экземпляр без заданной конфигурации

    Если вы хотите заново развернуть TDG с нуля, не забудьте сначала удалить файлы конфигурации, а также xlog- и snap-файлы, которые были созданы при первом развертывании TDG:

    $ rm -rf ./dev/output

Running Tarantool Data Grid in Docker

Вы можете запустить TDG в Docker-контейнере, чтобы разработать свое решение или проверить, подходит ли Tarantool Data Grid для вашего проекта.

This guide will show you how to:

  1. Download the Docker image file.

  2. запустить экземпляр (инстанс, instance) |project_name| в Docker-контейнере;

  3. Configure the instance.

Getting Docker image file for deployment

Download the Docker image file of the latest version at the customer zone of tarantool.io. The download link looks like tdg-<version>-<hash>-docker-image.tar.gz.

If you do not have access to the customer zone, you can get one by applying this form or writing to sales@tarantool.io.

Running an instance

  1. First, load the Docker image from the file that you’ve downloaded:

    $ # change <version> and <hash> for the TDG version that you've downloaded
$ docker load --input tdg2_tdg-<version>-<hash>docker-image.tar.gz

    The output will look like the following:

    $ docker load --input tdg2_tdg-2.0.0-1197-g1144f0c9-docker-image.tar.gz
174f56854903: Loading layer [==================================================>]  211.7MB/211.7MB
3755a040b03f: Loading layer [==================================================>]  124.4kB/124.4kB
62e0389f69ce: Loading layer [==================================================>]   80.7MB/80.7MB
6230a7f7e181: Loading layer [==================================================>]   2.56kB/2.56kB
e714472acbb5: Loading layer [==================================================>]  54.62MB/54.62MB
32e4a08d6732: Loading layer [==================================================>]  2.048kB/2.048kB
63380e3c2f5c: Loading layer [==================================================>]  127.6MB/127.6MB
9a6936065be6: Loading layer [==================================================>]  4.348MB/4.348MB
e70d4b034a27: Loading layer [==================================================>]  12.29kB/12.29kB
Loaded image: tdg:2.0.0-1197-g1144f0c9

    For details about docker load, refer to the Docker documentation.

  2. Find an archive named tdg in the list of images:

    $ docker image ls tdg
REPOSITORY   TAG                    IMAGE ID       CREATED       SIZE
tdg          2.0.0-1197-g1144f0c9   564a45b770f8   10 days ago   463MB

  3. Теперь запустите контейнер с экземпляром TDG:

    $ docker run --rm -it -p 8080:8080 tdg:<tag>

    For example:

    $ docker run --rm -it -p 8080:8080 tdg:2.0.0-1197-g1144f0c9

    You will now find the unconfigured instance at localhost:8080:

    Экземпляр без заданной конфигурации

Configuring instance

On the Cluster tab, there is an unconfigured instance. To access all basic functions to work with data, click Configure. You will get the Configure server dialog:

Окно "Configure server"

In the Configure server dialog, specify two replica set parameters: replica set name and roles. Set any name and choose Select all option to switch on these roles:

failover-coordinator role enables by default. You can read more about this role in Tarantool Cartridge documentation.

After assigning all roles, click Create replica set.

Note

В этом примере все роли включаются одновременно в одном наборе реплик. Это удобно для практики и позволяет больше узнать о возможностях TDG, но в производственной среде так делать не стоит.

Initialize Tarantool vshard module by clicking Bootstrap vshard:

Кнопка инциализации vshard

You can read more about this module in Tarantool documentation.

Web UI

В этой главе рассказано, как получить доступ к веб-интерфейсу TDG и авторизоваться в системе. Кроме того, в главе описаны элементы управления и функции, представленные в веб-интерфейсе.

В примере ниже описана ситуация, когда авторизация в системе TDG уже включена. Подробнее о том, как включить авторизацию, вы можете узнать из руководства по авторизации.

Signing in

Чтобы получить доступ к веб-интерфейсу TDG, выполните следующие шаги:

  1. Contact your administrator to get your credentials:

    • Username: login that is automatically generated when the administrator creates a user profile. For example, ui8896 or gz1200.

    • Password: automatically generated when the administrator creates a user profile.

    • TDG server address: http://<address>:<http_port>, is set by the administrator in the configuration file. This guide uses the http://172.19.0.2:8080 server address as an example.

  2. В браузере введите адрес сервера TDG, чтобы открыть диалоговое окно авторизации.

    Окно авторизации

  3. Введите учетные данные: в поле Username – имя пользователя, а в поле Password – пароль.

  4. Click Login.

Во время авторизации система TDG проверяет правильность ваших учетных данных и права доступа к определенным вкладкам TDG. После успешной авторизации вы увидите интерфейс TDG с доступом только к определенным вкладкам. Набор вкладок зависит от роли пользователя, которую вам назначил администратор.

Если в учетных данных окажется опечатка, TDG не сможет вас идентифицировать. В этом случае появится сообщение “Authentication failed”:

Ошибка аутентификации

Try to input your credentials one more time.

Web UI overview

Интерфейс TDG состоит из двух частей:

  1. Панель вкладок отображает список вкладок для навигации по разделам TDG.

  2. Working area: displays the contents of the selected tab.

Web UI

Tab pane

The contents of the tab pane vary depending on the user role. Users with the “admin” and “supervisor” rights can see all tabs. Users with the access rights of the “user” role have access to a limited set of tabs.

At the bottom of the page, there is a Collapse menu button. Click it to hide the full tab pane view.

The tab pane consists of the following tabs:

Cluster

Cluster configuration and administration.

Configuration files

Управление параметрами конфигурации TDG.

Test

Sending test queries in JSON or XML (SOAP) format.

GraphQL

Sending queries in GraphQL format.

Model

Актуальная модель данных, загруженная в систему.

Repair Queues: Input

Repair queue for the uploaded objects.

Repair Queues: Output

Repair queue for the objects replicated to external systems.

Repair Queues: Jobs

Repair queue for pending jobs that ended with an error.

Logger

Event log.

Audit Log

Audit log.

Tasks

Task management.

Data types

Data types that are represented in the uploaded data model.

Connectors

Connector creation and management.

Settings

System settings management.

Doc

Версия документации TDG на английском языке, доступная локально из разворачиваемого пакета TDG. Таким образом, она содержит только ту информацию, которая была опубликована до формирования пакета. Более актуальную документацию на русском языке вы можете найти на сайте tarantool.io.

Cluster tab

На вкладке Cluster отображается текущий статус кластера экземпляров TDG. На этой вкладке вы можете администрировать кластер через веб-интерфейс. Элементы управления можно разделить на несколько групп:

Replica sets

Статистика по наборам реплик

In the highlighted area, you can see general replica set statistics:

Total

Total number of replica sets in the cluster.

Unhealthy

Number of replica sets with the “unhealthy” status.

Servers

Общее количество экземпляров TDG.

Filter

A dropdown menu to filter replica sets by status or cluster role.

Search box

A search box to display replica sets filtered by URI, UUID, role, alias, or labels.

Replica set widget

Replica set widget

The following statistics are available in the replica set widget:

Name and role

For example, replica set “storage_1” with the role “storage”.

Status

“Healthy” means the current replica set functions properly. “Unhealthy” means the current replica set is not available or does not function properly.

Storage group and replica set weight

Only for replica sets with the “storage” role. For example, storage group “default”, replica set weight “1”.

Edit button

Opens a dialog where you can edit the parameters of the replica set.

Instances widgets

The widgets of the instances included in this replica set.

Instance widget

Instance widget

The widget of the instance is in the highlighted area. It allows you to see the following information about the instance:

Instance name

For example, “storage_1” or “storage_1_replica”.

URI

Instance URI for binary port access. Is set in the cluster configuration via the advertise_uri parameter. For example, 172.19.0.2:3003.

Status

“Healthy” means the current instance functions properly. “Unhealthy” means the current instance is not available or does not function properly.

Leader indicator

Indicates if the instance is the leader in the replica set.

Memory usage indicator

The actual memory used / memory limit set for the instance. For example, 3.3 MiB / 1024.0 MiB.

Virtual buckets indicator

Indicates the number of virtual buckets on the instance. Only for replica sets with the “storage” role.

… button

Options to see instance details, promote the instance as a leader, disable or expel the instance.

Instance details

For each instance, you can view detailed information about its parameters in read-only mode. On the Cluster tab of the instance, click … > Server details:

Server details: подробная информация об экземпляре

You will see a pop-up window with detailed information about the instance parameters:

Параметры экземпляра

More functions

Другие функции управления кластером

Several more TDG functions are also available on the Cluster tab:

Issues

The history of issues occurring in the cluster operation.

Probe server

Manual server availability check. Used when configuring a cluster.

Auth

Enable and disable mandatory authorization mode.

Failover: disabled/eventual/stateful

Switch for automatic recovery mode after failure.

Вкладка Connectors

В TDG роль connector предназначена для соединения и обмена данными с внешними системами. Для подключения доступно несколько протоколов соединения:

На вкладке Connectors отображается список всех input-коннекторов. Здесь вы можете создавать новые коннекторы и управлять их. Ниже описаны доступные сценарии работы с вкладкой:

Создание коннектора

Во вкладке Connectors нажмите кнопку Add connector:

Вкладка Connectors

Появится окно Create connector, где нужно ввести параметры коннектора:

Окно создания коннектора

Параметры коннектора

При добавлении коннектора доступна настройка маршрутизации и input-параметров – параметров для получения и парсинга входящих запросов. Чтобы узнать больше об этих параметрах, обратитесь к разделу Параметры коннекторов. Ниже в таблице приведены поля, доступные для настройки в редакторе:

Название параметра

Тип коннектора

Описание

Обязательный параметр

Name

Любой

Имя коннектора, должно быть уникальным

Да

synchronous mode

Любой

Режим работы TDG в качестве producer. По умолчанию, режим асинхронный: подтверждение о доставке сообщения отправляется сразу после того, как сообщение добавлено в очередь на отправку. При синхронном режиме подтверждение о доставке отправляется только после того, как сообщение было доставлено.

Да

Routing key

Любой

ключ маршрутизации

Да

Protocol type

Любой

Тип коннектора. Доступные типы: http (по умолчанию), soap, kafka, tarantool_protocol.

Да

Path

http

Адрес для отправки запроса в TDG

Да

WSDL

soap

Схема WSDL, описывающая структуру входящего XML

Да

Success response template

soap

Шаблон ответа в случае успешной обработки запроса

Нет

Error response template

soap

Шаблон ответа в случае ошибки

Нет

Brokers

kafka

URL-адреса брокеров сообщений

Да

Topics

kafka

Топики в терминологии Kafka

Да

Group ID

kafka

Идентификатор группы подписчиков

Да

Token name

kafka

Имя токена приложения

Нет

Options

kafka

Опции библиотеки librdkafka

Нет

Print debug logs

kafka

Режим отладки. По умолчанию, отладка отключена. При включении отладки по умолчанию используется параметр debug: "all". Если в логах не требуются все атрибуты, установите необходимое значение параметра debug в секции options при конфигурации.

Нет

Direct all non-error logs to TDG logger

kafka

Запись всех логов Kafka, включая сообщения об ошибках, в логи TDG. Соответствует параметру logger: tdg. По умолчанию, в редакторе опция включена.

Нет

Пример

Создадим новый коннектор типа http:

Создание http-коннектора

Для поля Path часть адреса определена заранее и не может быть изменена. Предопределенный адрес – это URL, на котором запущен экземпляр TDG (например, http://localhost:8080/). В поле можно указать только последнюю часть адреса – endpoint. Значение по умолчанию для endpoint: http.

Когда все необходимые поля заполнены, нажмите кнопку Submit. Теперь список коннекторов выглядит следующим образом:

Список коннекторов

Столбцы Name, Protocol type, Routing key и Options в таблице можно сортировать по возрастанию и убыванию.

Управление коннекторами

Справа от каждого коннектора в списке находятся кнопки, позволяющие отредактировать его параметры или удалить коннектор:

Редактирование и удаление коннектора

Доступные функции:

Редактирование коннектора

При изменении настроек существующего коннектора доступны все параметры, кроме типа коннектора.

Данные о коннекторах в редакторе можно перезаписать и извне. Например, если загрузить во вкладку Configuration Files файл с новыми настройками коннектора, созданного ранее в редакторе, новая конфигурация отобразится во вкладке Connectors после обновления страницы.

Удаление коннектора

При попытке удалить коннектор появится диалоговое окно с подтверждением удаления.

Кластерные роли

В этой главе приводятся рекомендации и инструкции по настройке кластерных ролей на экземплярах TDG.

В TDG существует четыре основных кластерных роли:

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

Рекомендации по назначению ролей на экземплярах

Исходя из сущности ролей и механизмов их работы, можно дать следующие рекомендации по организации кластера и назначению ролей на экземплярах:

Настройка кластерных ролей через WebUI

Для настройки кластерных ролей через веб-интерфейс TDG используются инструменты на вкладке Cluster.

Назначение ролей новым экземплярам

Чтобы назначить роль экземпляру впервые, найдите его в списке Unconfigured Instances и нажмите соответствующую кнопку Configure.

Вкладка Cluster

В открывшемся окне вы можете назначить роль одним из двух способов:

  • Создать новый набор реплик с нужными ролями. Для этого введите имя нового набора реплик, выберите необходимые роли и нажмите Create replica set.

    Добавление экземпляра в набор реплик

  • Добавить экземпляр в существующий набор реплик. Для этого перейдите на вкладку Join replica set, выберите один из существующих наборов реплик с необходимыми ролями и нажмите Join replica set.

    Создание нового набор реплик

Изменение ролей

Чтобы изменить роли набора реплик, откройте окно его редактирования (Edit replica set) и включите или отключите роли. Эти изменения применятся ко всем экземплярам выбранного набора реплик.

Редактирование ролей набора реплик

Warning

При отключении роли storage на наборе реплик необходимо перераспределить сегменты данных, которые на нём хранятся, на другие наборы реплик. Для этого перед отключением роли storage установите набору реплик вес (Replica set weight) равным 0 и нажмите Save.

После этого убедитесь, что в наборе реплик не осталось сегментов данных и отключите на нём роль storage.

Настройка кластерных ролей через Ansible

Если вы разворачиваете кластер TDG с помощью Ansible, вы можете определить наборы реплик и их роли в inventory-файле hosts.yml.

Наборы реплик и их роли определяются в inventory-файле в разделе all.children.

Для каждого набора реплик необходимо создать узел с именем replicaset_<name>, где <name> – название, под которым набор реплик будет использоваться в кластере. Пример создания набора реплик с именем storage_01:

all:
   children:
    replicaset_storage_01:

В узле набора реплик задаются два раздела:

Пример конфигурации набора реплик с ролью storage из двух узлов:

all:
   children:
    replicaset_storage_01:
      vars:  # replica set configuration
        replicaset_alias: storage-01
        weight: 1
        failover_priority:
          - storage-01  # leader
          - storage-01-r
        roles:
          - 'storage'

Конфигурация кластера из пяти узлов с тремя наборами реплик (два storage и один с ролями core, runner, connector) может выглядеть следующим образом:

all:
   children:
    replicaset_storage_01:
      vars:  # replica set configuration
        replicaset_alias: storage-01
        weight: 1
        failover_priority:
          - storage-01  # leader
          - storage-01-r
        roles:
          - 'storage'

      hosts:   # replica set instances
        storage-01:
        storage-01-r:

    replicaset_storage_02:
      vars:  # replica set configuration
        replicaset_alias: storage-02
        weight: 1
        failover_priority:
          - storage-02  # leader
          - storage-02-r
        roles:
          - 'storage'

      hosts:   # replica set instances
        storage-02:
        storage-02-r:

    replicaset_app_01:
      vars:  # replica set configuration
        replicaset_alias: app-01
        failover_priority:
          - app-01  # leader
        roles:
          - 'core'
          - 'connector'
          - 'runner'

Security settings

This chapter explains how to administer security policy settings.

Role-based access control

В Tarantool Data Grid используется основанная на ролях модель доступа к системным функциям и данным, хранящимся в системе. Администратор настраивает права доступа к данным, используя UI или такие внешние инструменты, как LDAP. Каждая роль имеет набор разрешений, которые определяют, что пользователи или внешние приложения могут просматривать или изменять.

You can find the list of roles on the Settings > Roles tab:

Список ролей

Default roles

There are three default roles that you can assign to users and external applications for authorized access and actions in the system:

The default roles have a predefined set of permissions, and they cannot be edited or deleted.

Role

Authority

Data access

admin

Полный доступ ко всем функциям TDG

Read and write access for all aggregates

supervisor

Full read-only access to TDG functions

Read access for all aggregates

user

Default access: has access to the Test tab to send test objects, the Repair Queues tab, the Tasks tab, and the GraphQL tab.

None

Adding new user roles via UI

You can create new user roles based on the default roles or the roles you’ve already created.

To create a new user role:

  1. Switch to the Settings > Roles tab and click Add new role.

  2. In the New role dialog, set the following parameters:

    • Name: the name of the new role.

    • Description: an optional description of the new role.

    • Roles: an optional selection of the existing role on the basis of which the new role will be created.

  3. В списке выберите действия, которые будут доступны для роли пользователя. Не забудьте проверить, есть ли у роли доступ к интерфейсу. Например, если вы собираетесь дать роли права на выполнение запросов GraphQL, отметьте Pages Access > Show GraphQL page.

  4. Click Add new role.

Окно создания роли

After you’ve created a new user role, you can edit or delete it any time.

Managing users

В этой главе рассматриваются операции управления пользователями TDG:

The list of users is in the Settings > Users tab:

Список пользователей

Creating and editing user profiles

Creating a new user

Чтобы создать профиль пользователя TDG, выполните следующие шаги:

  1. Switch to the Settings > Users tab. Click Add new user. You will get the New user dialog:

Окно "New user"

  1. In the New user dialog, set the following parameters:

    • Name: user name.

    • Email: user email.

    • Password: a password to log into the system. There are several options here: you can generate a password by clicking Generate or leave an empty field. In the second case, the system will automatically generate and send a password to the user’s Email, but it requires a configured SMTP server.

    • Expires in: password expiration date. This field is optional. Passwords are checked for expiration approximately every 30 minutes. Accounts with expired passwords are blocked.

    • Role: user role according to the role-based model of access.

  2. Click Submit.

You will now see the new user in the list of users. After you’ve created a user, you can edit the user’s profile: change profile settings, reset password, block or delete the user.

Editing a user profile

To edit a user profile, open the Settings > Users tab and click the pencil edit button:

Изменение профиля пользователя

Change profile settings and click Submit.

Deleting a user

The administrator can delete any user from the user list:

  1. In the Actions column, choose the user profile you want to delete, click the ... button, and select Delete user.

  2. In the dialog tab, confirm the deletion of the user by clicking OK.

The deleted user will be automatically removed from the list of users.

Changing user status

After you’ve created a user’s profile, it is automatically activated in the system. You’ll see the “ACTIVE” status in the Status column in the list of users. As an administrator, you can change this status and block the user:

  1. In the Actions column, click the ... button and select Block:

    Блокировка пользователя

  2. In the dialog tab, write the reason why you are blocking this user and click Block:

    Блокировка пользователя

After that, the user’s status will change to “BLOCKED”. To unblock the user, click the ... button and select Unblock.

Resetting a password

The administrator can reset the password of any user:

  1. In the Actions column, choose the user profile you want to update, click the ... button, and select Reset password.

  2. In the dialog tab, confirm the resetting of the password by clicking OK.

The user will get a temporary password via email that is set in the user’s profile.

Note: to send a temporary password, you need a configured SMTP server.

To set the workflow for sending temporary passwords:

  1. Install and start the SMTP server.

  2. В файле конфигурации TDG config.yml пропишите следующие настройки:

connector:
  output:
    - name: to_smtp
      type: smtp
      url: <URL of SMTP server>
      from: <sender's address>
      timeout: <timeout value, seconds>

account_manager:
  only_one_time_passwords: true
  output:
    name: to_smtp

For example:

output:
    - name: to_smtp
      type: smtp
      url: localhost:2525
      from: tdg@example.com
      timeout: 5

  1. Upload the changed configuration to the system.

Exporting and importing users

You can export and import user profiles in JSON format:

Exporting and importing users

Exporting users

In the Settings > Users tab, click Export. The system will generate and export a JSON file. This file will contain an array with profiles of all current users.

Here is a user profile example:

[
   {
    "expires_in":2592000,
    "login":"ui8896",
    "email":"test@mail.ru",
    "created_at":1626360261875418600,
    "state_reason":"test@mail.ru state is changed to active: recover from disabled",
    "failed_login_attempts":1,
    "uid":"bd2e91f3-ce0f-4ff1-8aae-bc4212f99c7d",
    "role":"admin",
    "state":"active"
    ,"username":"User1",
    "last_login":1628058891852268000,
    "last_password_update_time":null
   },
   {
   ...
   }
]

Importing users

To import users, you need a JSON file with an array of user profiles. You can make this file manually or generate it as described in the previous topic about the export. The JSON file must include the fields listed above in the user profile example, except for the fields called state_reason, last_login, last_password_update_time, password.

As for the password, there are several ways to set it:

  1. Manually: In the JSON file, set a password for every user. Make sure the passwords meet the password policy requirements. In the Import users from JSON file dialog, do not check any boxes. The passwords will be uploaded from the JSON file as-is.

  2. Generate passwords: Set null in the password field or don’t include this field in the JSON file at all. In the Import users from JSON file dialog, check the box Generate passwords. The password will be automatically generated according to the current password policy.

  3. Send password via users email: You need a configured SMTP server for this. In the Import users from JSON file dialog, check the Send password via users email box.

You need to choose only one of the listed options for all imported users.

Here is how to import users:

  1. In the Settings > Users tab, click Import.

  2. In the Import users from JSON file dialog, check one of the boxes or leave the boxes empty. It depends on the option you chose to set the users’ passwords.

    Importing users

  3. Upload the JSON file with user profiles and click Apply.

The new user profiles will now be added to the Users list table. The profile data will be shown in the web interface in the message containing the results of the import operation.

You can save the imported data, including the generated passwords, by clicking Download. The data will be saved as a .csv file.

Managing password policy

Авторизацию пользователей в системе регулирует политика TDG в отношении паролей. Она применима в равной степени как к паролям, которые пользователи задают вручную, так и к автоматически сгенерированным паролям. Управлять политикой в отношении паролей можно на вкладке Settings > Password Policy:

Политика в отношении паролей

Default password settings include lowercase and uppercase characters and digits from 0 to 9, inclusive. The default password length is 8 characters. You can change the default settings and click Save.

Токены приложений

Токен приложений – уникальный идентификатор, который генерируется в кластере TDG. Такой токен служит средством авторизации внешних приложений для взаимодействия с данными и функциями TDG. Администратор создает токен, назначает для него нужные права доступа к объектам TDG и передает его разработчикам внешней системы. Доступны два способа управления токенами приложений – в веб-интерфейсе TDG и через GraphQL API.

Токен приложений также используется для авторизации HTTP-запросов и авторизации коннекторов. Подробнее об этих процедурах рассказывается в разделе Авторизация Руководства разработчика.

Управление токенами в веб-интерфейсе

Добавление токена

Сгенерировать токен через веб-интерфейс можно на вкладке Settings > Tokens:

  1. Нажмите кнопку Add token.

  2. В диалоговом окне Create token укажите следующие параметры:

    • Name: имя (ключ) токена, по которому он будет идентифицироваться в системе;

    • Expires in: срок действия токена (опционально). Чтобы создать токен без срока действия, оставьте поле пустым;

    • Role: роль токена. Аналогична роли пользователя в ролевой модели доступа;

    Окно добавления токена

  3. Нажмите кнопку Submit, чтобы сгенерировать токен. В веб-интерфейсе появится сообщение, где токен будет представлен в явном виде:

    Сгенерированный токен

Important

Сохраните созданный токен в надежном месте. В целях безопасности токен в явном виде показывается только один раз, при его генерации. Сообщение с токеном исчезнет, как только вы покинете данную страницу или создадите новый токен.

Имя созданного токена редактировать невозможно. Однако вы можете изменять роль токена и его срок действия.

Как и профили пользователей, токены приложений в веб-интерфейсе можно удалять, блокировать, экспортировать и импортировать.

Удаление токена

Администратор может удалить из списка любой токен приложения. Для этого:

  1. Найдите нужный токен в колонке Actions. В меню действий ... выберите пункт Delete token.

  2. В диалоговом окне подтвердите удаление токена, нажав кнопку OK. Токен будет удален из общего списка автоматически.

Блокировка токена

Созданный токен будет сразу активирован в системе, для него в колонке Status появится статус ACTIVE. Администратор может изменить этот статус и заблокировать токен:

  1. В колонке Actions в меню действий ... выберите Block.

  2. В диалоговом окне опишите причину блокировки токена и нажмите Block. После этого статус токена изменится на BLOCKED. Чтобы разблокировать токен, в меню действий ... выберите Unblock и в диалоговом окне опишите причину разблокировки токена.

Кроме того, токен будет заблокирован автоматически (просрочен), если пользователь будет неактивен в системе дольше определенного времени. Задать необходимое время (не более 45 дней) можно в параметре ban_inactive_more_seconds в секции account_manager файла конфигурации. Разблокировать просроченный токен можно, если задать для него новое значение параметра Expires in.

Экспорт и импорт токенов

Токены приложений можно экспортировать из системы и импортировать в нее в формате JSON. Для этого на вкладке Settings > Tokens нажмите кнопку Import или Export. Действия выполняются аналогично экспорту и импорту профилей пользователей.

Пример JSON-файла с токенами:

[
  {
    "expires_in": 900,
    "token": null,
    "state_reason": "App01 state is changed to blocked",
    "uid": "jdsDAY3Y-wcwYBkdS7Kma2wyEYLwIv_qjQvxeUsFeyh0txDuqgHWmIMzLFCWp8S3GTgbxRQw7dq7Rz-k2Tddyg",
    "role": "user",
    "state": "blocked",
    "last_login": null,
    "name": "Token1",
    "created_at": 1686839870157890300
  },
  {
    "expires_in": 0,
    "token": null,
    "state_reason": null,
    "uid": "pLQIQDvHvGsymbfI1jt37BUhYLuZOzWNSB8kbDoWDx4mwYLDEdJFz-pUwK7mASyojYl-O83t1Iqtqr4HUGyKbQ",
    "role": "user",
    "state": "active",
    "last_login": null,
    "name": "App02",
    "created_at": 1686927801987245300
  }
]

Управление токенами через GraphQL API

Токенами приложений в TDG можно управлять с помощью GraphQL-запросов на изменение настроек, используя протокол HTTP. HTTP-запросы при этом должны иметь заголовок схемы admin и соответствующий заголовок для авторизации. Подробнее о таких запросах рассказывается в разделе Управление настройками через GraphQL API. Пример выполнения curl-запроса на изменение настроек можно найти на странице Авторизация Руководства разработчика.

Используя GraphQL API, можно выполнять следующие действия:

Все операции, относящиеся к токенам, выполняются внутри блока token {}. Полный список параметров запросов и их описание приведены на странице Основные настройки TDG.

Чтение информации о токенах

Чтобы вывести список всех токенов приложения, используйте запрос list (query):

query {
  token {
    list {
      name
         }
        }
      }

Чтобы вывести информацию о токене по его имени, используйте запрос get (query):

query {
  token {
    get(name: "Token1")
          {
            name
            expires_in
            created_at
            uid
            role
            state
            unblocked_at
            state_reason
            last_login
          }
        }
      }

Добавление токена

Для создания токена приложения используйте запрос add (mutation):

mutation {
    token {
        add(
          name: "App01"
          expires_in: 0
          role: "user"
        ) {
            name
            token
            created_at
        }
    }
}

При успешной генерации токена система возвращает ответ с указанием токена в явном виде в параметре token:

{
  "data": {
    "token": {
      "add": {
        "name": "App01",
        "token": "b773dbec-b86b-41aa-5541-887ba722c62e",
        "created_at": 1567758613669985599
      }
    }
  }
}

Important

Сохраните созданный токен в надежном месте. В целях безопасности токен в явном виде показывается только один раз, при его генерации. При повторных запросах существующего токена система возвращает его только в виде хеша.

При попытке повторно создать токен с уже существующим именем система возвращает сообщение об ошибке.

Редактирование токена

Изменить можно только срок действия токена и его роль. Для редактирования токена приложения используйте запрос update (mutation):

mutation {
    token {
        update(
          name: "App01"
          expires_in: 25000
          role: "admin"
        ) {
            name
            expires_in
            role
        }
    }
}

Блокировка токена

Для изменения статуса токена приложения используйте запрос set_state (mutation):

mutation {
    token {
        set_state(
          name: "App01"
          state: "blocked"
        ) {
            name
            role
            state
        }
    }
}

Кроме того, токен будет заблокирован автоматически (просрочен), если пользователь будет неактивен в системе дольше определенного времени. Задать необходимое время (не более 45 дней) можно в параметре ban_inactive_more_seconds в секции account_manager файла конфигурации. Разблокировать просроченный токен можно, если задать для него новое значение параметра Expires in.

Импорт токена

Для импорта токена приложения используйте запрос import (mutation):

mutation {
  token {
    import(
      uid: "9d9fec89-c1f0-467f-b756-156fe9d29840"
      name: "App02"
      expires_in: 2592000
      role: "admin"
      state: "active"
      created_at: 1686927801987245300
    ) {
      name
      uid
    }
  }
}

Удаление токена

Для удаления токена приложения используйте запрос remove (mutation):

mutation {
    token {
        remove(name: "App01") {
            name
            created_at
            role
        }
    }
}

Mandatory authentication mode

Сразу после развертывания TDG любые анонимные пользователи и внешние приложения могут получать неавторизованный доступ ко всем функциям и данным, что ненадежно с точки зрения безопасности. Поэтому в TDG появляется соответствующее предупреждение.

Предупреждающее сообщение

To enable mandatory authentication mode:

  1. Create a user profile with the “admin” role.

  2. Sign in to the system as this user.

  3. On the Cluster tab, enable the Auth toggle switch:

Включение авторизации

  1. In the Authorization dialog, click Enable:

Кнопка "Enable"

The mandatory authentication mode is on.

Теперь пользователи могут входить в систему, используя логин и пароль. В интерфейсе TDG пользователю предоставляется доступ к определенным вкладкам. Набор вкладок зависит от роли пользователя. Чтобы предоставить авторизованный доступ к данным и функциям TDG внешнему приложению, используйте токены приложений.

Авторизация внешних пользователей и систем через LDAP

TDG поддерживает технологию единого входа (Single Sign-On) – механизм аутентификации, позволяющий пользователям получать доступ к нескольким приложениям и сервисам c одним набором учетных данных. Это означает, что авторизоваться в TDG можно как через пользователей и токены приложений, так и с использованием такого внешнего инструмента, как LDAP.

LDAP (Lightweight Directory Service Protocol) – открытый протокол для хранения и получения данных из службы каталогов. LDAP позволяет централизованно настраивать права доступа к данным.

В TDG доступны три способа настройка протокола LDAP:

В этом руководстве рассмотрим первые два способа настройки протокола.

Для выполнения примера требуются:

Note

Для локального тестирования LDAP-авторизации можно использовать сервер GLAuth. Гарантируется работа с версией GLAuth 2.0.0

Руководство включает в себя следующие шаги:

Особенности конфигурации LDAP

По умолчанию, логин в систему – это строка вида user@domain, где:

Пример: tdguser@my.domain.ru.

Если подключена Active Directory, служба каталогов Microsoft, для входа в систему используется адрес электронной почты пользователя LDAP. В качестве фильтра при этом используется атрибут Active Directory userprincipalname=email, где email – адрес электронной почты пользователя.

Каждый пользователь LDAP состоит в одной или нескольких группах LDAP (domain group). Группе LDAP задается определенная роль (например, admin), которая определяет права доступа для пользователя из этой группы. Если пользователь LDAP состоит сразу в нескольких группах, он получает разрешения на действия из всех ролей, заданных для этих групп.

Настройка LDAP в веб-интерфейсе

Добавим новую конфигурацию LDAP через веб-интерфейс TDG.

  1. На вкладке Settings > LDAP нажмите кнопку Add Configuration.

    Окно создания конфигурации LDAP

  2. В диалоговом окне LDAP укажите параметры, необходимые для вашей конфигурации:

    • Domain – доменное имя, используемое в доменном логине пользователя (tdguser@my.domain.ru). Пример: my.domain.ru;

    • Hosts – адрес подключения к серверу LDAP. Пример: server.my.domain.ru:389;

    • Organizational units (опционально) – названия организационных подразделений или групп пользователей. Параметр будет пропущен, если для него не задано явное значение. Пример: tarantool;

    • Options (опционально) – настройки LDAP. Параметр будет пропущен, если для него не задано явное значение;

    • Roles – описание ролей, которые будут назначаться пользователю в зависимости от групп LDAP, в которых он состоит. Для каждой роли описаны название роли и соответствующие ей LDAP-группы. Описание LDAP-группы состоит из общего имени (CN), названия организационного подразделения или LDAP-группы (OU) и компонентов домена (DC).

      Пример: добавьте роль admin. Для нее в поле Domain Groups укажите значение CN=tarantool, OU=groups, OU=other_groups, DC=my, DC=domain, DC=ru;

    • Search timeout (опционально) – время ожидания ответа от сервера LDAP в секундах. Значение по умолчанию: 2;

    • Use TLS (опционально) – использование TLS. Значение по умолчанию: false;

    • Use Active Directory (опционально) – использование Active Directory. Значение по умолчанию: false.

    При настройке обратите внимание на параметры domain и organizational_units. Эти параметры используются при аутентификации для поиска пользователя в соответствующем домене и организационном подразделении.

    Полное описание параметров LDAP приведено в разделе ldap справочника конфигурации.

  3. Нажмите кнопку Submit, чтобы добавить конфигурацию LDAP.

  4. Чтобы войти в систему как пользователь LDAP, нажмите кнопку Log in в правом верхнем углу. В диалоговом окне Authorization введите логин (вида user@domain) и пароль пользователя LDAP, затем нажмите кнопку Login.

Настройка LDAP в файле конфигурации

Указать конфигурацию LDAP можно:

Полное описание параметров LDAP приведено в разделе ldap справочника конфигурации.

Пример конфигурации с включенными TLS и Active Directory:

ldap:
  - domain: 'my.domain.ru'
    organizational_units: ['tarantool']
    hosts:
      - server.my.domain.ru:389
    use_active_directory: true
    use_tls: true
    search_timeout: 2
    options:
      - LDAP_OPT_X_TLS_CACERTFILE: /certs/CA_Root.crt
    roles:
      - domain_groups:
          - 'cn=tarantool,ou=groups,ou=other_groups,dc=my,dc=domain,dc=ru'
        role: 'admin'

Созданный yml-файл с настройками конфигурации нужно упаковать в zip-архив и загрузить в TDG согласно инструкции.

Setting up data actions

TDG позволяет управлять правами пользователей на чтение и запись данных, обрабатываемых и хранимых в системе. Чтобы роль пользователя получила права доступа к данным, создайте в веб-интерфейсе профиль доступа (data action) и назначьте этот профиль для нужной роли.

Creating a new data action

To set up a new data action:

  1. Open the Settings > Data actions tab.

  2. Click Add data action.

  3. In the New data action dialog, set the data action’s Name and check the Read/ Write rights for each aggregate:

Окно создания профиля доступа

  1. Save the data action by clicking Save.

After creating a data action, you can edit any of its parameters.

Assigning data actions to user roles

You can assign data action to any user role created by the administrator. However, assigning data actions to default roles is impossible, as they cannot be edited.

To assign a data action to a user role:

  1. Switch to the Settings > Roles tab.

  2. In the list of roles, choose the role you want to edit and click the pencil edit button.

  3. In the list of all actions, find Data actions section and tick the checkbox of the data action you want to assign to the role:

Привязка профиля доступа к роли пользователя

  1. Click Apply.

Likewise, you can assign data actions while creating a new role.

Security checklist

This chapter will help you audit the security of Tarantool Data Grid. It explains certain security aspects, their rationale, and the ways to check them.

Audit log

Журнал аудита содержит записи о событиях безопасности в TDG.

To view the log:

  1. Configure at least one instance with the storage role.

  2. Go to the Cluster tab and click the Bootstrap vshard button.

  3. Go to the Audit log tab.

Enabling and disabling the audit log

The audit log is enabled by default and records messages regardless of authorization settings.

To disable the audit log, click the Disable logging button on the Audit log tab. You can also go to the Graphql tab and run the following GraphQL request:

mutation {
  audit_log {
    enabled(value: false)
  }
}

To check if the audit log is enabled:

query {
  audit_log {
    enabled
  }
}

Clearing the audit log

The audit log is stored in memtx and doesn’t clear automatically.

To fully clear the space associated with the audit log, run the following GraphQL code:

mutation {
        audit_log {
          clear
        }
      }

Log structure

Each table entry provides the following information:

The audit log can be filtered by each of the parameters. Below is more information about every one of them.

Severity

Possible values (in order of ascending severity):

  • VERBOSE – детальная информация;

  • INFO – уведомление;

  • WARNING – предупреждение;

  • ALARM – тревога.

A filter by severity displays events of the specified level or more severe. Choose the “VERBOSE” filter to display all messages.

From - To

Date and time of the event. Displayed in GMT+0 (UTC) time.

Subject ID

Internal identifier of the access subject.

Subject

Access subject name and type. Possible values:

  • system %q: системное сообщение, где %q – имя сущности в системе.

  • token %q: доступ к HTTP API при помощи токена приложения (например, чтобы получить данные GraphQL), где %q – имя сущности, запросившей доступ.

  • user: access attempt from GUI.

  • anonymous: access attempt from GUI, if mandatory authorization is disabled.

  • unauthorized: access attempt from GUI by an unauthorized user.

Request ID

Internal identifier of the request.

Module

Name of the system module that initiated the event. Examples: common.admin.auth is the module responsible for authorization.

Message

Event description. Can be provided by the user.

Examples

Successful user authorization

Сообщение журнала аудита об успешной авторизации пользователя

Model update

Сообщение журнала аудита об обновлении модели

Clearing the audit log

Сообщение после очистки журнала аудита

Configuration via config.yml

The default settings that Tarantool Data Grid starts up with can be found in the file config.yml. Audit log settings can be listed in this

audit_log:
  remove_older_than_n_hours: 24 # how many hours a message should exist before being deleted
  severity: VERBOSE # record messages of this severity level and higher
  enabled: true

Задачи

В этой главе описаны возможности TDG по управлению задачами через веб-интерфейс.

Задачи позволяют запускать пользовательский код изнутри TDG. Инструкции по созданию и конфигурированию задач приведены в разделе Задачи руководства разработчика. Имя, вид и расписание выполнения задач определяются в конфигурации бизнес-логики.

Инструменты для управления задачами и отслеживания их выполнения расположены на вкладке Tasks.

Вкладка Tasks Страница результатов задачи

Repair queue

Если система TDG не может обработать входящий объект, она помещает его в ремонтную очередь. Затем администратор проверяет его, устраняет проблему и отправляет объект на повторную обработку.

Input

On the Repair queues > Input tab, there is a repair queue for submitted objects.

Repair queues > Input

Сюда попадают входящие объекты, которые система TDG не смогла обработать. Вот основные причины, по которым это происходит:

You can work with objects in the repair queue through the web interface on the Input tab:

Объекты ремонтной очереди

On this tab, you can see the list of objects, their status (“New”, “In Progress”, “Reworked”), and the date and time when they were placed in the repair queue.

The Repair queue interface lets you do the following:

Click on the object to see its details:

Подробная информация об объекте

In the Object info dialog, you can see:

When an object gets into the repair queue, it has the status “New”. When it is processed for a second time, the object’s status changes to “In Progress”. If the object was processed successfully, it is removed from the repair queue. If an error occurs during reprocessing, the system will display an error message. The object will remain in the repair queue with the status “Reworked”.

Notifications

Пользователей системы TDG можно оповещать каждый раз, когда в ремонтную очередь попадает новый объект. Чтобы включить уведомления, нужен почтовый сервер и список подписчиков, которые будут их получать.

On the Settings > Mail server tab, set the following parameters:

  • Url: the SMTP server used to send notifications.

  • From: the sender that will be shown in the mail client.

  • Username: SMTP server user name.

  • Password: SMTP server user password.

  • Timeout (sec): SMTP server request timeout in seconds.

On the Settings > Subscribers tab, click the Add subscriber button to add a new subscriber. Specify the subscriber’s name and email. Later, you can edit the subscriber’s profile or delete it.

Output

The object replication mechanism allows you to send objects to external systems in the desired format. In case of an error during the replication process, the object gets in the replication repair queue on the Output tab.

This queue has the same functions as the repair queue on the Input tab. The only difference is that the repair queue on the Input tab is for submitted objects that could not be processed and saved, whereas the replication repair queue on the Output tab is for objects that could not be replicated.

To work with objects in the replication repair queue, open the Repair queues > Output tab:

Ремонтная очередь репликации

Like in the repair queue, you can filter objects, delete them, and try to replicate them again.

The object status shows the reason why the object ended up in the replication repair queue:

If you choose an object and click Try again, the object will be processed again. Its status will change from “New” to “In progress”. If the operation is successful, the object will be moved to the next stage or deleted from the repair queue. If the operation finishes with an error, the status will change to “Rereplicated (Preprocessing error)” or “Rereplicated (Sending error)”. The object will remain in the replication repair queue.

Jobs

This is a repair queue for pending jobs that ended with an error. To monitor these jobs, open the Repair queues > Jobs tab:

Ремонтная очередь для отложенных задач

This tab has the same functions as the repair queue for submitted objects on the Input tab.

Monitoring

Для мониторинга работы TDG предоставляются метрики в формате Prometheus. Для каждого из экземпляров кластера значения метрик доступны по адресу: http://<IP_адрес_экземпляра>/metrics. В системе-сборщике метрик необходимо подать на вход адреса для сбора метрик со всех экземпляров кластера.

Все доступные метрики можно разделить на несколько категорий:

Используются следующие типы метрик Prometheus:

Чтобы узнать больше про типы метрик, обратитесь к документации Prometheus.

Метрики TDG

Метрики запросов GraphQL

Мониторинг и оценка запросов GraphQL.

Метрики имеют теги:

Доступные метрики

Бакеты (bucket) гистограмм распределены в диапазоне от 0 до 1000 миллисекунд с интервалом в 100 миллисекунд (см. пример ниже).

Вызов сервиса аналогичен запросу (query) для типа данных. В тег entity при этом будет записано имя сервиса.

Каждый запрос может состоять из нескольких операций. В одной операции могут быть получены или модифицированы несколько типов данных. По каждому типу данных будет выдана отдельная метрика со своим набором тегов.

Пример:

# HELP tdg_graphql_query_time Graphql query execution time
# TYPE tdg_graphql_query_time histogram
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="100"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="200"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="300"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="400"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="500"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="600"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="700"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="800"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="900"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="1000"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="+Inf"} 25
tdg_graphql_query_time_sum{alias="core_1",schema="default",entity="City",operation_name="GetCity"} 55
tdg_graphql_query_time_count{alias="core_1",schema="default",entity="City",operation_name="GetCity"} 25

# HELP tdg_graphql_mutation_time Graphql mutation execution time
# TYPE tdg_graphql_mutation_time histogram
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="100"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="200"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="300"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="400"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="500"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="600"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="700"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="800"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="900"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="1000"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="+Inf"} 16
tdg_graphql_mutation_time_sum{alias="core_1",schema="default",entity="City",operation_name="InsCity"} 34
tdg_graphql_mutation_time_count{alias="core_1",schema="default",entity="City",operation_name="InsCity"} 16

# HELP tdg_graphql_query_fail Graphql query fail count
# TYPE tdg_graphql_query_fail counter
tdg_graphql_query_fail{alias="core_1",schema="default",entity="City",operation_name="GetCity"} 2

# HELP tdg_graphql_mutation_fail Graphql mutation fail count
# TYPE tdg_graphql_mutation_fail counter
tdg_graphql_mutation_fail{alias="core_1",schema="default",entity="City",operation_name="InsCity"} 4

Чтобы получить информацию о среднем количестве запросов GraphQL в секунду из Prometheus, воспользуйтесь запросом

rate(tdg_graphql_query_time_count[2m])

Период, по которому вычисляется rate() (в примере – 2m), должен быть как минимум в два раза больше периода сбора метрик. Если вы добавляете панель на стандартный Grafana Tarantool dashboard, воспользуйтесь переменной $rate_time_range.

Среднее время выполнения запроса GraphQL можно получить с помощью

rate(tdg_graphql_query_time_sum[2m])/rate(tdg_graphql_query_time_count[2m])

95-й перцентиль времени выполнения запроса GraphQL можно получить с помощью

histogram_quantile(0.95, sum(rate(tdg_graphql_query_time_bucket[2m])) by (le))

Метрики для задач и отложенных работ

Метрики для задач (tasks) и отложенных работ (jobs). Метрики актуальны только для экземпляров с ролью runner, так как задачи и отложенные работы запускаются на этих экземплярах.

Метрики задач имеют теги:

Метрики отложенных работ и системных задач имеют только теги alias и name. В TDG cистемные задачи (system task) используются для версионирования.

Доступные метрики

Метрики для кортежей

Статистика по операциям поиска кортежей в базе данных, где хранятся пользовательские данные:

Метрики запросов REST

Мониторинг и оценка запросов к данным через REST:

Метрики запросов iproto

Мониторинг и оценка запросов к данным через iproto:

Метрики файлового коннектора

Общая статистика по файловым коннекторам и статистика обработки файлов:

Метрики expirationd

Статистика модуля expirationd (время жизни объектов). Сбор статистики включен по умолчанию.

Тип метрик – counter.

Метрики имеют тег name – название задачи (task).

Доступные метрики

Метрики Kafka

В TDG доступен мониторинг сведений о коннекторе Kafka с помощью librdkafka. librdkafka – это реализация С-библиотеки протокола Apache Kafka, которая поддерживает как producer, так и consumer. Для библиотеки по умолчанию включено регулярное предоставление внутренней статистики.

Интервал обновления метрик можно настроить, используя опцию statistics.interval.ms. По умолчанию, значение statistics.interval.ms составляет 15000 миллисекунд. Диапазон доступных значений для параметра: 0–86400000 мс. Отключить сбор статистики можно, установив значение 0.

Полное описание параметров конфигурации для коннектора Kafka приведено в справочнике по настройке коннектора.

Метрики имеют тип gauge, если не указано иначе. Имеют префикс tdg_kafka_, общий для всех метрик Kafka.

Метрики Kafka состоят из нескольких уровней:

Большая часть операций – это оконные функции, которые применяются на отрезках времени. Поэтому уровни Topics и Brokers также включают в себя раздел про плавающие окна (Rolling Window Statistics), например, скользящую среднюю, наименьшую и наибольшую величины, сумму значений и процентные значения.

Общая статистика

Общая статистика по всем брокерам:

  • tdg_kafka_ts – внутренние монотонные часы библиотеки librdkafka в микросекундах;

  • tdg_kafka_time – время с начала эпохи в секундах;

  • tdg_kafka_age – время существования экземпляра клиента в микросекундах;

  • tdg_kafka_replyq – количество операций (триггеров, событий и т.д.) в очереди на обслуживание с помощью rd_kafka_poll();

  • tdg_kafka_msg_cnt – текущее количество сообщений в очереди продюсера;

  • tdg_kafka_msg_size – текущий общий размер сообщений в очередях продюсера;

  • tdg_kafka_msg_max – максимальное количество сообщений, разрешенное в очередях продюсера;

  • tdg_kafka_msg_size_max – общий размер сообщений, разрешенный в очередях продюсера;

  • tdg_kafka_tx – общее количество запросов, отправленных брокерам Kafka;

  • tdg_kafka_tx_bytes – общее количество байтов, отправленных брокерам Kafka;

  • tdg_kafka_rx – общее количество запросов, полученных от брокеров Kafka;

  • tdg_kafka_rx_bytes – общее количество байтов, полученных от брокеров Kafka;

  • tdg_kafka_txmsgs – общее количество сообщений, отправленных брокерам Kafka;

  • tdg_kafka_txmsg_bytes – общее количество байтов сообщений, отправленных брокерам Kafka (включая фрейм – например, фрейм по каждому сообщению и фрейм MessageSet/пакета);

  • tdg_kafka_rxmsgs – общее количество сообщений, полученных от брокеров Kafka. Не включает в себя сообщения, которые были проигнорированы – например, из-за смещения;

  • tdg_kafka_rxmsg_bytes – общее количество байтов сообщений (включая фрейм), полученных от брокеров Kafka;

  • tdg_kafka_simple_cnt – внутреннее отслеживание устаревшего и нового состояния API consumer;

  • tdg_kafka_metadata_cache_cnt – количество топиков в кэше метаданных.

Плавающее окно (Rolling Window Statistics)

Постфиксы для метрик, связанные с оконными функциями. Например, к ним относятся стандартное отклонение, наибольшая и наименьшая величина и процентные значения (процентили). Позволяют получить получать дополнительную информацию о значении некоторых метрик с уровней Topics и Brokers. Полный список доступных метрик вместе с постфиксами указан в описаниях соответствующих уровней.

Переменная {name} – имя метрики вместе с префиксом tdg_kafka_. Например, tdg_kafka_broker_int_latency_max – наибольшее значение метрики tdg_kafka_broker_int_latency.

  • name_min – наименьшее значение;

  • name_max – наибольшее значение;

  • name_avg – среднее значение;

  • name_sum – сумма значений;

  • name_cnt – количество выбранных значений;

  • name_stddev – стандартное отклонение на основе гистограммы;

  • name_hdrsize – объем памяти Hdr Histogram;

  • name_outofrange – значения, пропущенные из-за выхода за пределы диапазона гистограммы.

Процентные значения:

  • p50 – процентиль 0.5;

  • p75 – процентиль 0.75;

  • p90 – процентиль 0.9;

  • p95 – процентиль 0.95;

  • p99 – процентиль 0.99;

  • p99_99 – процентиль 0.9999.

Значения процентилей можно просмотреть для следующих метрик:

  • уровень Broker – tdg_kafka_broker_int_latency, tdg_kafka_broker_outbuf_latency, tdg_kafka_broker_rtt, tdg_kafka_broker_throttle;

  • уровень Topic – tdg_kafka_topic_batchcnt, tdg_kafka_topic_batchsize.

Статистика по брокеру

  • tdg_kafka_broker_stateage – время с момента последнего изменения состояния брокера в микросекундах;

  • tdg_kafka_broker_outbuf_cnt – количество запросов, ожидающих отправки брокеру;

  • tdg_kafka_broker_outbuf_msg_cnt – количество сообщений, ожидающих отправки брокеру;

  • tdg_kafka_broker_waitresp_cnt – количество запросов на пути к брокеру, ожидающих ответа;

  • tdg_kafka_broker_waitresp_msg_cnt – количество сообщений на пути к брокеру, ожидающих ответа;

  • tdg_kafka_broker_tx – общее количество отправленных запросов;

  • tdg_kafka_broker_txbytes – исходящий трафик в байтах;

  • tdg_kafka_broker_txerrs – число ошибок при передаче;

  • tdg_kafka_broker_txretries – общее количество повторных запросов;

  • tdg_kafka_broker_txidle – время с момента, как был отправлен последний сокет, в микросекундах. Если для текущего подключения еще ничего не отправлялось, имеет значение -1;

  • tdg_kafka_broker_req_timeouts – общее количество запросов, время ожидания для которых истекло;

  • tdg_kafka_broker_rx – общее число полученных ответов;

  • tdg_kafka_broker_rxbytes – входящий трафик в байтах;

  • tdg_kafka_broker_rxerrs – число ошибок при получении;

  • tdg_kafka_broker_rxcorriderrs – общее количество различающихся идентификаторов корреляции в ответе (обычно для запросов с истекшим временем ожидания);

  • tdg_kafka_broker_rxpartial – общее количество частично полученных MessageSets;

  • tdg_kafka_broker_rxidle – время с момента получения последнего сокета в микросекундах. Если для текущего соединенния еще нет полученных данных, имеет значение -1;

  • tdg_kafka_broker_zbuf_grow – общее количество увеличений размера для буфера декомпрессии;

  • tdg_kafka_broker_buf_grow – общее количество увеличений размера буфера (deprecated, не используется);

  • tdg_kafka_broker_wakeups – пробуждения пула потоков брокера;

  • tdg_kafka_broker_connects – количество попыток соединения. Включает в себя успешные и неудачные попытки, а также количество неудачных попыток разрешения имен;

  • tdg_kafka_broker_disconnects – количество разорванных соединений, вызванных брокером, сетью, балансировщиком нагрузки и т. д;

  • tdg_kafka_broker_req – счетчики типа запроса. Ключ объекта – это имя запроса, значение – количество отправленных запросов;

  • tdg_kafka_broker_int_latency – задержка внутренней очереди продюсера в микросекундах. Метрика используется только вместе с постфиксами из раздела Rolling Window Statistics.

    Список доступных метрик: tdg_kafka_broker_int_latency_avg, tdg_kafka_broker_int_latency_cnt, tdg_kafka_broker_int_latency_hdrsize, tdg_kafka_broker_int_latency_max, tdg_kafka_broker_int_latency_min, tdg_kafka_broker_int_latency_outofrange, tdg_kafka_broker_int_latency_stddev, tdg_kafka_broker_int_latency_sum;

  • tdg_kafka_broker_outbuf_latency – задержка внутренней очереди запросов в микросекундах. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

    Список доступных метрик: tdg_kafka_broker_outbuf_latency_avg, tdg_kafka_broker_outbuf_latency_cnt, tdg_kafka_broker_outbuf_latency_hdrsize, tdg_kafka_broker_outbuf_latency_max, tdg_kafka_broker_outbuf_latency_min, tdg_kafka_broker_outbuf_latency_outofrange, tdg_kafka_broker_outbuf_latency_stddev, tdg_kafka_broker_outbuf_latency_sum;

  • tdg_kafka_broker_rtt – задержка брокера, время обхода в микросекундах. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

    Список доступных метрик: tdg_kafka_broker_rtt_avg, tdg_kafka_broker_rtt_cnt, tdg_kafka_broker_rtt_hdrsize, tdg_kafka_broker_rtt_max, tdg_kafka_broker_rtt_min, tdg_kafka_broker_rtt_outofrange, tdg_kafka_broker_rtt_stddev, tdg_kafka_broker_rtt_sum;

  • tdg_kafka_broker_throttle – время регулирования брокера в миллисекундах. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

    Список доступных метрик: tdg_kafka_broker_throttle_avg, tdg_kafka_broker_throttle_cnt, tdg_kafka_broker_throttle_hdrsize, tdg_kafka_broker_throttle_max, tdg_kafka_broker_throttle_min, tdg_kafka_broker_throttle_outofrange, tdg_kafka_broker_throttle_stddev, tdg_kafka_broker_throttle_sum.

Статистика по топику

  • tdg_kafka_topic_age – возраст объекта клиентского топика в миллисекундах;

  • tdg_kafka_topic_metadata_age – возраст метаданных от брокера для данного топика в миллисекундах;

  • tdg_kafka_topic_batchsize – размер пакета в байтах. Метрика используется только вместе с постфиксами из раздела Rolling Window Statistics.

    Список доступных метрик: tdg_kafka_topic_batchsize_avg, tdg_kafka_topic_batchsize_cnt, tdg_kafka_topic_batchsize_hdrsize, tdg_kafka_topic_batchsize_max, tdg_kafka_topic_batchsize_min, tdg_kafka_topic_batchsize_outofrange, tdg_kafka_topic_batchsize_stddev, tdg_kafka_topic_batchsize_sum;

  • tdg_kafka_topic_batchcnt – счетчик пакетных сообщений. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

    Список доступных метрик: tdg_kafka_topic_batchcnt_avg, tdg_kafka_topic_batchcnt_cnt, tdg_kafka_topic_batchcnt_hdrsize, tdg_kafka_topic_batchcnt_max, tdg_kafka_topic_batchcnt_min, tdg_kafka_topic_batchcnt_outofrange, tdg_kafka_topic_batchcnt_stddev, tdg_kafka_topic_batchcnt_sum;

  • tdg_kafka_topic_partitions – разделы. Метрика используется только вместе с постфиксами из раздела Partitions.

Статистика по разделам топика

Метрики, связанные с разделами топика. Позволяют получить получать информацию о метрике tdg_kafka_topic_partitions.

  • tdg_kafka_topic_partitions_broker – ID брокера, сообщения из раздела которого извлекают в текущий момент;

  • tdg_kafka_topic_partitions_leader – ID текущего лидера брокеров;

  • tdg_kafka_topic_partitions_desired – раздел, явно требуемый при применении;

  • tdg_kafka_topic_partitions_unknown – раздел, который не отображен в метаданных топика брокера;

  • tdg_kafka_topic_partitions_msgq_cnt – количество сообщений, ожидающих отправки в очереди первого уровня;

  • tdg_kafka_topic_partitions_msgq_bytes – количество байтов в msgq_cnt;

  • tdg_kafka_topic_partitions_xmit_msgq_cnt – количество сообщений в очереди выборки, готовых к отправке;

  • tdg_kafka_topic_partitions_xmit_msgq_bytes – количество байтов в xmit_msgq;

  • tdg_kafka_topic_partitions_fetchq_cnt – количество предварительно выбранных сообщений в очереди выборки;

  • tdg_kafka_topic_partitions_fetchq_size – размер очереди выборки в байтах;

  • tdg_kafka_topic_partitions_query_offset – текущий/последний запрос на логическое смещение;

  • tdg_kafka_topic_partitions_next_offset – следующее смещение для выборки;

  • tdg_kafka_topic_partitions_app_offset – смещение в разделе последнего сообщения, переданного приложению, +1;

  • tdg_kafka_topic_partitions_stored_offset – смещение для фиксации в разделе;

  • tdg_kafka_topic_partitions_committed_offset – последнее зафиксированное смещение в разделе;

  • tdg_kafka_topic_partitions_eof_offset – последнее сигнализированное смещение PARTITION_EOF;

  • tdg_kafka_topic_partitions_lo_offset – минимальное доступное смещение для раздела на брокере;

  • tdg_kafka_topic_partitions_hi_offset – максимальное доступное смещение для раздела на брокере;

  • tdg_kafka_topic_partitions_ls_offset – последнее стабильное смещение раздела на брокере;

  • tdg_kafka_topic_partitions_consumer_lag – разница между hi_offset или ls_offset и commit_offset;

  • tdg_kafka_topic_partitions_consumer_lag_stored – разница между hi_offset или ls_offset и stored_offset;

  • tdg_kafka_topic_partitions_txmsgs – общее количество отправленных сообщений

  • tdg_kafka_topic_partitions_txbytes – общее количество байтов, переданных для txmsgs

  • tdg_kafka_topic_partitions_rxmsgs – общее количество полученных сообщений, за исключением игнорируемых сообщений;

  • tdg_kafka_topic_partitions_rxbytes – общее количество байтов, полученных для rxmsgs;

  • tdg_kafka_topic_partitions_msgs – общее количество полученных или общее количество отправленных сообщений;

  • tdg_kafka_topic_partitions_rx_ver_drops – удаленные устаревшие сообщения;

  • tdg_kafka_topic_partitions_msgs_inflight – текущее количество сообщений на пути к брокеру или от него (in-flight);

  • tdg_kafka_topic_partitions_next_ack_seq – следующая ожидаемая подтвержденная последовательность (идемпотентный продюсер);

  • tdg_kafka_topic_partitions_next_err_seq – следующая ожидаемая последовательность с ошибкой (идемпотентный продюсер);

  • tdg_kafka_topic_partitions_acked_msgid – ID внутреннего сообщения c последним подтверждением (идемпотентный продюсер).

Статистика группы consumer (cgrp)

  • tdg_kafka_cgrp_stateage – время с момента последнего изменения состояния в миллисекундах;

  • tdg_kafka_cgrp_rebalance_age – время с момента последней ребалансировки в миллисекундах;

  • tdg_kafka_cgrp_rebalance_cnt – общее количество ребалансировок;

  • tdg_kafka_cgrp_assignment_size – количество разделов для текущего назначения.

Статистика идемпотентного продюсера (EOS)

Библиотека librdkafka поддерживает семантику Exactly-Once Delivery (EOS) для доставки сообщений. Такая семантика гарантирует, что сообщения будут доставлены строго один раз. За реализацию семантики отвечает свойство идемпотентности в настройках продюсера и число подтверждений об успешной записи.

  • tdg_kafka_eos_idemp_stateage – время с момента последнего изменения состояния ID идемпотентного продюсера (idemp_state) в миллисекундах;

  • tdg_kafka_eos_txn_stateage – время с момента последнего изменения состояния транзакционного продюсера txn_state в миллисекундах;

  • tdg_kafka_eos_txn_may_enq – состояние транзакции позволяет добавлять в очередь новые сообщения;

  • tdg_kafka_eos_producer_id – текущий ID продюсера (или -1);

  • tdg_kafka_eos_producer_epoch – текущая эпоха (или -1);

  • tdg_kafka_eos_epoch_cnt – число назначений ID продюсера с момента запуска.

Метрики Tarantool

В системе TDG доступны метрики для мониторинга работы экземпляров Tarantool.

Общая статистика

Общая информация о различных параметрах экземпляров Tarantool. Тип метрик – gauge.

Общая статистика использования памяти

Тип метрик – gauge.

Статистика использования памяти для распределения slab

Распределение slab – это основное распределение, используемое для хранения кортежей. Метрики помогают отслеживать:

Тип метрик – gauge.

Чтобы узнать больше о вариантах использования распределения slab, обратитесь к документации модуля box.slab.

Доступная память (в байтах)

  • tnt_slab_quota_size – максимальный объем памяти в байтах, который механизм распределения slab может использовать как для кортежей, так и для индексов. Значение по умолчанию в параметре memtx_memory: 2^28 байт = 268 435 456 байт;

  • tnt_slab_arena_size – общий объем памяти в байтах, используемый для кортежей и индексов. Включает в себя выделенные распределения slab, свободные в текущий момент;

  • tnt_slab_items_size – общий объем памяти в байтах, используемый только для кортежей. Включает в себя выделенные распределения slab, свободные в текущий момент. Не используется для индексов.

Использование памяти (в байтах)

  • tnt_slab_quota_used – объем памяти в байтах, уже выделенный для распределения slab;

  • tnt_slab_arena_used – эффективный объем памяти в байтах, используемый для кортежей и индексов. Не включает в себя выделенные распределения slab, свободные в текущий момент;

  • tnt_slab_items_used – эффективный объем памяти в байтах, используемый только для кортежей. Не включает в себя выделенные распределения slab, свободные в текущий момент. Не используется для индексов.

Потребление памяти (в процентах)

  • tnt_slab_quota_used_ratio – соотношение quota_used / quota_size;

  • tnt_slab_arena_used_ratio – соотношение arena_used / arena_size;

  • tnt_slab_items_used_ratio – соотношение items_used / slab_count * slab_size. Это распределения slab, которые используются только для кортежей, не для индексов.

Статистика использования памяти в конкретных спейсах

Все метрики, за исключением tnt_space_index_bsize, имеют два тега:

Тип метрик – gauge.

Доступные метрики

Статистика сетевой активности

Мониторинг нагрузки сети, пиков использования и падения трафика. Начиная с версии Tarantool 2.10, метрики имеют тег thread, который отображает сетевую статистику для каждого потока.

Трафик

Тип метрик – counter.

  • tnt_net_sent_total – исходящий трафик в байтах;

  • tnt_net_received_total – входящий трафик в байтах.

Сетевые соединения

  • tnt_net_connections_total – общее количество входящих сетевых соединений с момента запуска экземпляра. Тип метрики: counter;

  • tnt_net_connections_current – текущее количество входящих сетевых соединений. Тип метрики: gauge.

Сетевые запросы

  • tnt_net_requests_total – общее количество входящих сетевых запросов с момента запуска экземпляра. Тип метрики: counter;

  • tnt_net_requests_current – текущее количество входящих сетевых запросов в обработке. Может быть ограничено параметром конфигурации базы данных net_msg_max. Тип метрики: gauge;

  • tnt_net_requests_in_progress_total – общее количество сетевых запросов, обработанных потоком процессора транзакций (TX thread). Тип метрики: counter;

  • tnt_net_requests_in_progress_current – количество сетевых запросов, которые обрабатывает поток процессора транзакций (TX thread) в текущий момент. Тип метрики: gauge;

  • tnt_net_requests_in_stream_queue_total – общее количество сетевых запросов, помещенных в очереди стримов за все время потоком процессора транзакций (TX thread). Тип метрики: counter;

  • tnt_net_requests_in_stream_queue_current – количество сетевых запросов, ожидающих обработки в очередях стримов в текущий момент. Тип метрики: gauge.

Информация о файберах

Статистика по файберам. Тип метрик – gauge.

Статистика входящих запросов (по типу запросов)

Тип метрики – gauge.

Метрика имеет тег operation – тип входящего запроса, приходящего по бинарному протоколу. Возможные типы запроса:

Информация о репликации

Текущий статус репликации. Тип метрик – gauge.

Информация о синхронной репликации

Текущее состояние синхронной репликации. Тип метрик – gauge.

Метрики работы экземпляров Tarantool в кластере

Тип метрик – gauge.

Информация о выборах лидера

Текущее состояние узла в наборе реплик относительно выборов лидера. Тип метрик – gauge.

Статистика использования памяти для среды выполнения Lua-кода

Тип метрик – gauge.

Метрики LuaJIT

Общая статистика JIT, работа сборщика мусора Lua и статистика выделения (аллокации) памяти. Метрики доступны, начиная с версии Tarantool 2.6

Общие метрики JIT

  • lj_jit_snap_restore_total – общее количество восстановлений стека при выходе с трассы. Тип метрики: counter;

  • lj_jit_trace_num – количество скомпилированных трасс. Тип метрики: gauge;

  • lj_jit_trace_abort_total – общее количество прерванных компиляций. Тип метрики: counter;

  • lj_jit_mcode_size – общий объем выделенного машинного кода в байтах. Тип метрики: gauge.

JIT-строки

  • lj_strhash_hit_total – количество интернированных строк. Тип метрики: counter;

  • lj_strhash_miss_total – общее количество выделенных строк. Тип метрики: counter.

Шаги сборщика мусора

  • lj_gc_steps_atomic_total – количество шагов инкрементального сборщика мусора (фаза atomic). Тип метрики: counter;

  • lj_gc_steps_sweepstring_total – количество шагов инкрементального сборщика мусора (фаза sweep для строк). Тип метрики: counter;

  • lj_gc_steps_finalize_total – количество шагов инкрементального сборщика мусора (фаза finalize). Тип метрики: counter;

  • lj_gc_steps_sweep_total – количество шагов инкрементального сборщика мусора (фаза sweep). Тип метрики: counter;

  • lj_gc_steps_propagate_total – количество шагов инкрементального сборщика мусора (фаза propagate). Тип метрики: counter;

  • lj_gc_steps_pause_total – количество шагов инкрементального сборщика мусора (фаза pause). Тип метрики: counter.

Выделение памяти

  • lj_gc_strnum – количество выделенных объектов string. Тип метрики: gauge;

  • lj_gc_tabnum – количество выделенных объектов table. Тип метрики: gauge;

  • lj_gc_cdatanum – количество выделенных объектов cdata. Тип метрики: gauge;

  • lj_gc_udatanum – количество выделенных объектов udata. Тип метрики: gauge;

  • lj_gc_freed_total – объем освобожденной памяти в байтах. Тип метрики: counter;

  • lj_gc_memory – текущий объем выделенной Lua-памяти в байтах. Тип метрики: gauge;

  • lj_gc_allocated_total – объем выделенной памяти в байтах. Тип метрики: counter.

Статистика CPU

Информация об использовании процессора. Метрики доступны только для Linux. Тип метрик – gauge.

Статистика работы движка vinyl

Информация о работе движка vinyl. Тип метрик – gauge.

Disk

Дисковые метрики используются для мониторинга общего объема данных на диске.

  • tnt_vinyl_disk_data_size – количество данных в байтах, которое хранится в файлах .run. Файлы .run расположены в директории vinyl_dir;

  • tnt_vinyl_disk_index_size – количество данных в байтах, которое хранится в файлах .index. Файлы .index расположены в директории vinyl_dir.

Regulator

Регулятор движка vinyl определяет, когда начинать действия по дисковому IO, и группирует их в пакеты.

  • tnt_vinyl_regulator_dump_bandwidth – пропускная способность дампа, байты в секунду;

  • tnt_vinyl_regulator_write_rate – фактическая средняя скорость выполнения операций записи, байты в секунду;

  • tnt_vinyl_regulator_rate_limit – ограничение скорости записи, байты в секунду;

  • tnt_vinyl_regulator_dump_watermark – максимальный объем памяти в байтах, используемый для in-memory хранения LSM-дерева движка vinyl.

  • tnt_vinyl_regulator_blocked_writers – количество файберов, заблокированных в ожидании квоты памяти движка vinyl для “Уровня 0” (L0).

Transactional activity

Работа с транзакциями.

  • tnt_vinyl_tx_commit – счетчик коммитов (успешных завершений транзакций). Включает в себя неявные коммиты. Например, операция на вставку вызывает неявный коммит, если только операция не находится в блоке begin–commit;

  • tnt_vinyl_tx_rollback – счетчик откатов (неудачных завершений транзакций). Включает в себя:

    • явные запросы на rollback;

    • запросы, завершившиеся с ошибкой;

  • tnt_vinyl_tx_conflict – счетчик конфликтов, которые привели к откату транзакций;

  • tnt_vinyl_tx_read_views – текущее количество транзакций, которые перешли в состояние read-only, чтобы временно избежать конфликта.

Memory

Области памяти, используемые движком vinyl для кэша и буферов записи.

  • tnt_vinyl_memory_tuple_cache – объем памяти в байтах, используемый в настоящее время для хранения кортежей (данных);

  • tnt_vinyl_memory_level0 – область памяти “Уровень 0” (L0) в байтах;

  • tnt_vinyl_memory_page_index – объем памяти в байтах, используемый в настоящее время для хранения индексов;

  • tnt_vinyl_memory_bloom_filter – объем памяти в байтах, используемый фильтрами bloom.

Scheduler

Планировщик движка vinyl, который раз в секунду вызывает регулятор и обновляет связанные с ним переменные.

  • tnt_vinyl_scheduler_tasks{status} – количество задач планировщика на дамп / сжатие. Метрика имеет тег status. Возможные значения тега:

    • inprogress – для задач, запущенных в данный момент;

    • completed – для успешно завершенных задач;

    • failed – для задач, прерванных из-за ошибок;

  • tnt_vinyl_scheduler_dump_time – общее время в секундах, затраченное всеми рабочими потоками на выполнение дампов;

  • tnt_vinyl_scheduler_dump_count – счетчик выполненных дампов.

Статистика цикла событий

Информация о потоке транзакций цикла событий. Тип метрик – gauge.

Рекомендации по анализу метрик

При мониторинге системы рекомендуется в первую очередь обращать внимание на следующие группы метрик:

Note

Рекомендуемые и критические значения для большинства метрик из списка ниже рассчитываются на основе статистических данных промышленной эксплуатации или предварительной статистики, собранной на стенде нагрузочного тестирования. Для получения помощи в настройке таких метрик обратитесь к команде поддержки.

Статистика использования CPU

Рекомендуемые и критические значения для метрик ниже определяются исходя из конкретного проекта. Узнать подробнее о метриках, связанных с использованием процессора, можно в разделе Статистика CPU.

tnt_cpu_user_time

Среднее время использования CPU в секундах, затраченное процессом экземпляра на исполнение логики базы данных. Срабатывает при высокой нагрузке на заданном сервере.

Решение

Определите место в коде приложения, которое вызывает всплеск нагрузки на CPU. Постоянно высокая загрузка CPU может говорить о нехватке вычислительных мощностей.

tnt_cpu_system_time

Среднее время использования CPU в секундах, затраченное процессом экземпляра на исполнение системного вызова.

Решение

Большое значение метрики указывает на проблему в одной из подсистем. Одна из причин проблемы – выросшее значение параметра iowait(), в этой ситуации приложение тратит много ресурсов на чтение или запись на диск.

Статистика использования памяти

Рекомендуемые и критические значения для метрик ниже определяются исходя из конкретного проекта, если не указано иначе.

tnt_info_memory_lua

Объем памяти в байтах, используемый средой выполнения Lua-кода. Объем памяти Lua ограничен 2 Гб на каждый экземпляр (более 2 Гб на версиях GC64). Отслеживание метрики помогает предотвратить переполнение памяти и выявить некорректные методы работы с Lua-кодом. Рекомендуемое значение метрики: 25-100 МБ.

Порог срабатывания: значение больше 1 Гб (за исключением версий GC64).

Решение

Одна из причин большой загруженности памяти – утечка памяти. Чтобы выяснить точную причину, вызовите функцию fiber.top(). Перезагрузите экземпляр после того, как определите причину проблемы.

tnt_runtime_used

Объем памяти в байтах, используемый средой выполнения Lua-кода (runtime arena) в данный момент. Среда выполнения хранит:

  • сетевые буферы;

  • кортежи, созданные с помощью box.tuple.new();

  • другие объекты, выделенные приложением, которые не охватывают базовые механизмы Lua.

Отслеживание метрики помогает предотвратить переполнение памяти и выявить некорректные методы работы с Lua-кодом. Рекомендуемое значение метрики близко к 0.

Порог срабатывания: значение заметно больше 0.

Решение

Обратитесь к разработчику приложения для анализа проблемы.

tnt_info_memory_tx

Объем памяти в байтах, используемый активными транзакциями. Для движка vinyl это общий размер всех выделенных объектов и кортежей, закрепленных для этих объектов. Рекомендуемое значение метрики близко к 0.

Порог срабатывания: значение заметно больше 0.

Решение

Обратитесь к разработчику приложения для анализа проблемы.

tnt_ev_loop_time

Продолжительность последней итерации цикла событий (поток TX) в миллисекундах.

Порог срабатывания: значение больше 1 секунды. Большое значение метрики может быть причиной ошибки Too long WAL write.

Решение

Обратитесь к разработчику приложения для анализа проблемы.

Статистика распределения slab

Использование выделенной оперативной памяти в процентах. Узнать подробнее о метриках, связанных с распределением slab, можно в разделе Статистика использования памяти для распределения slab.

Полезные метрики:

  • tnt_slab_quota_used_ratio – соотношение занятого объема памяти (tnt_slab_quota_used) к максимальному объему памяти, который можно выделить для slab (tnt_slab_quota_size);

  • tnt_slab_arena_used_ratio – соотношение занятого объема памяти (tnt_slab_arena_used) к максимальному объему памяти, который можно выделить для кортежей и индексов (tnt_slab_quota_size);

  • tnt_slab_items_used_ratio – соотношение занятого объема памяти (tnt_slab_items_used) к максимальному объему памяти, который можно выделить для кортежей (tnt_slab_items_size).

Отслеживание статистики распределения slab позволяет увидеть объем свободной оперативной памяти для хранения memtx кортежей и индексов на экземпляре. Если Tarantool превышает ограничения, экземпляр становится недоступен для записи. Оповещение может помочь понять, когда пора увеличить лимит box.cfg.memtx_memory или добавить новое хранилище в кластер vshard.

Порог срабатывания:

  • (tnt_slab_quota_used_ratio >= 80) и (tnt_slab_arena_used_ratio >= 80) – у экземпляра заканчивается выделенный объем оперативной памяти.

  • (tnt_slab_quota_used_ratio >= 90) и (tnt_slab_arena_used_ratio >= 90) – у экземпляра закончился выделенный объем оперативной памяти.

Решение:

Увеличьте лимит памяти Tarantool box.cfg.memtx_memory.

Порог срабатывания:

  • (tnt_slab_quota_used_ratio >= 80) и (tnt_slab_items_used_ratio <= 85) – у экземпляра заканчивается выделенный объем оперативной памяти. Возможна большая фрагментация данных.

  • (tnt_slab_quota_used_ratio >= 90) и (tnt_slab_items_used_ratio <= 85) – у экземпляра закончился выделенный объем оперативной памяти. Возможна большая фрагментация данных.

Решение:

Чтобы избавиться от фрагментации, выполните перезагрузку экземпляра. Если после перезагрузки значения метрик не изменились, рассмотрите возможность увеличения лимита памяти Tarantool box.cfg.memtx_memory.

Информация о файберах

Рекомендуемые и критические значения для метрик ниже определяются исходя из конкретного проекта.

Решение

Обратитесь к разработчику приложения для анализа проблемы.

Статистика сетевой активности

Рекомендуемые и критические значения для метрик ниже определяются исходя из конкретного проекта. Узнать подробнее о метриках, связанных с работой сети, можно в разделе Статистика сетевой активности.

tnt_net_requests_total

Общее количество входящих сетевых запросов, обработанных с момента запуска экземпляра.

Решение

При возникновении проблем проверьте сетевую доступность экземпляров Tarantool и наличие нагрузки с внешних сервисов.

tnt_net_requests_current

Текущее количество входящих сетевых запросов в обработке. Может быть ограничено параметром конфигурации базы данных net_msg_max.

Решение

Если количество сетевых запросов достигло лимита, заданного в параметре net_msg_max (по умолчанию 768), увеличьте значение этого параметра. Если Tarantool не успевает обрабатывать поступающие запросы, необходимо провести анализ поступающей нагрузки.

tnt_net_requests_in_stream_queue_current

Количество сетевых запросов, ожидающих обработки в очередях стримов в текущий момент.

Решение

  • Проверьте скорость работы жесткого диска при помощи системных утилит.

  • Проведите анализ потока процессора транзакций, используя функцию fiber.top().

tnt_net_connections_total

Общее количество входящих сетевых соединений с момента запуска экземпляра.

Решение

Проверьте профиль нагрузки в функции box.stat.net().

tnt_net_connections_current

Текущее количество входящих сетевых соединений.

Решение

Проверьте профиль нагрузки в функции box.stat.net().

Cartridge issues

tnt_cartridge_issues

Количество ошибок в работе экземпляра кластера. Срабатывает, когда возникает хотя бы одна ошибка:

  • в работе отдельного экземпляра кластера или набора реплик;

  • в работе кластера Cartridge.

Имеет два уровня критичности ошибок:

  • warning. Возможные причины: большой лаг или длительный простой репликации, проблемы с восстановлением после сбоев (failover) и переключением (switchover), проблемы со временем, фрагментация памяти, ошибки конфигурации, предупреждение о посторонних экземплярах в кластере;

  • critical. Возможные причины: критические сбои процесса репликации, нехватка доступной памяти.

Решение

При возникновении таких предупреждений обратите внимание на наличие ошибок в веб-интерфейсе Cartridge.

Статистика HTTP-запросов

В TDG доступен мониторинг статистики HTTP-сервера, в том числе отслеживание задержки HTTP-запросов.

http_server_request_latency

Задержка HTTP-запросов.

Порог срабатывания:

  • среднее время обработки запроса с ошибкой 4xx (зависит от проекта);

  • среднее время обработки запроса с ошибкой 5xx (зависит от проекта);

Решение:

Повышение значения метрики означает, что кластер не успевает обрабатывать поступающие изменения. Возможные причины:

  • возросшая нагрузка;

  • изменение кода;

  • проблемы с аппаратным обеспечением – например, появился новый потребитель ресурсов; диски работают медленно.

http_server_request_latency_count

Количество обработанных HTTP-запросов. Большое количество ответов с ошибками говорит о проблемах с API или неисправности приложения.

Порог срабатывания: зависит от проекта. Как правило, это больше 20 запросов, обработанных на стороне Tarantool с ошибкой 4xx.

Решение:

Проверьте работоспособность экземпляров и их сетевую доступность.

Порог срабатывания: зависит от проекта. Как правило, это больше 1 запроса, обработанного на стороне Tarantool с ошибкой 5xx.

Решение:

Возникла проблема с приложением. Определите экземпляр, на котором возникла проблема, проверьте файлы логов.

Maintenance

В этой главе описано, как обслуживать систему TDG, в том числе сохранять резервные копии данных и настроек, собирать сведения для отладки и выполнять другие действия.

Резервное копирование

Создание резервной копии

Для создания резервной копии кластера TDG, включая пользовательские данные и конфигурацию кластера, скопируйте и сохраните следующие файлы и директории из рабочих директорий всех экземпляров кластера:

Инструкции по резервному копированию экземпляров Tarantool приведены в документации Tarantool.

Восстановление из резервной копии

Для восстановления кластера TDG из резервной копии поместите содержимое резервной копии каждого экземпляра в соответствующую рабочую директорию. Содержимое резервной копии экземпляра включает:

После этого запустите кластер.

Cluster management

В этой главе рассказано, как управлять кластером TDG: изменять топологию, добавляя и исключая узлы, задавать настройки восстановления после сбоев (failover) и так далее.

Adding cluster nodes

Добавление нового узла (экземпляра) в кластер TDG – это фактически та же операция развертывания.

In this example, you will take the already deployed TDG cluster, deploy a new TDG instance and configure it via web interface by creating a new replica set with the storage cluster role.

For deploying a new instance, you will use the same tar.gz package and the Ansible tool with the predefined inventory and playbook configuration as for the initial cluster deployment.

  1. Navigate to the deploy directory extracted earlier from the tar.gz package and edit the Ansible inventory file hosts.yml. You need to add the description of a new instance and its parameters. In the code block below, parameters that should be added are marked with the comments # <-- Add ....

    children:
  tdg_group:

    ### Instances ###

    hosts:

      ...

      storage_3:  # <-- Добавьте новый экземпляр и параметры конфигурации для него
        config:
          advertise_uri: "172.19.0.2:3005"
          http_port: 8085
          memtx_memory: 1073741824  # 1024 Mb

    children:

      ### Machines ###

      vm1:
        hosts:
          stateboard_instance:
          core:
          runner_1:
          storage_1:
          storage_2:
          storage_3:  # <-- Добавьте этот экземпляр к hosts на vm1
        vars:
          ansible_host: "172.19.0.2"

    Important

    While editing hosts.yml, double-check the following parameters:

    • cartridge_package_path—use the same package of the same application version you used for initial cluster deployment.

    • cartridge_cluster_cookie—should be the same as it was during the initial deployment. Otherwise, the new instance won’t be included in the cluster.

  2. Deploy a new instance by using the deploy_without_topology.yml playbook:

    $ ansible-playbook -i hosts.yml --limit storage_3 playbooks/deploy_without_topology.yml

    The --limit option is used to apply the playbook steps only to the specified instance and avoid any changes for the existing ones.

  3. Откройте или обновите страницу с интерфейсом TDG. В нашем примере она находится по адресу http://172.19.0.2:8081. Новый экземпляр появится на вкладке Cluster в разделе Unconfigured servers.

    Добавлен несконфигурированный экземпляр

  4. The last step is to create a new replica set with the “storage” role. For the “storage_3” instance, click Configure. In the Configure server dialog, specify the following parameters and click Create replica set:

    • Replica set name: storage_3

    • Roles: storage

    • Replica set weight: 1

    Настройка нового набора реплик

The Replica set weight parameter should be set to the same value as for other replica sets with the “storage” role. It is necessary to run automatic data rebalancing between the storages upon creating a new storage.

You can verify if rebalancing was done correctly by checking out the Buckets parameter: the value should be the same for storage instances on the same server (172.19.0.2 in this example). Rebalancing process takes some time, so you may need to wait a bit and refresh the page to see the result in web interface.

Создан новый набор реплик

Developer’s guide

This document explains how to work with Tarantool Data Grid (TDG) if you are a developer.

Hello world with Lua

This guide explains how to set up a data model, run data queries, and write a couple of stored procedures in Lua.

Для начала вам понадобится запущенный экземпляр TDG. Можно запустить TDG в Docker-контейнере или же развернуть его на локальной машине вручную или с помощью Ansible.

Then you will learn how to:

  1. Set up the data model.

  2. Run data queries.

  3. Write stored procedures.

Setting up the data model

This guide uses a data model that contains two types of objects: music bands and artists. Each music band has a name, a genre, and a year it was formed. Artists have a name, a country, and the instruments they play.

Here is an example of such a model:

[
    {
        "name": "MusicBand",
        "type": "record",
        "fields": [
            {"name": "name", "type": "string"},
            {"name": "genre", "type": {"type":"array", "items":"string"}},
            {"name": "wasformed", "type":"long"}
        ],
        "indexes": ["name", "genre", "wasformed"]
    },
    {
        "name": "Artist",
        "type": "record",
        "fields": [
            {"name": "fullname", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "instruments", "type": {"type":"array", "items":"string"}}
        ],
        "indexes": ["fullname"]
    }
]

In the menu on the left, there is a tab called Model. Switch to this tab and paste the model to the Request field. Click Submit:

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

You have set up the data model. Now you can upload, select, and delete data.

Uploading data to TDG

In the menu on the left, there is a tab called Graphql. Switch to this tab, select default as the desired scheme, and clear the request field:

Вкладка Graphql

Paste the following data to the request field:

mutation all {
  rammstein:MusicBand(insert: {
      name: "Rammstein",
      genre: ["metal", "industrial", "gothic"],
      wasformed: 1994}) {
    name
    genre
    wasformed
  }
  linkinpark:MusicBand(insert: {
      name: "Linkin Park",
      genre: ["alternative", "metal"],
      wasformed: 1996}) {
    name
    genre
    wasformed
  }
  blacksabbath:MusicBand(insert: {
      name: "Black Sabbath",
      genre: ["gothic", "metal"],
      wasformed: 1968}) {
    name
    genre
    wasformed
  }
  deeppurple:MusicBand(insert:{
      name: "Deep Purple",
      genre: ["metal", "rock"],
      wasformed: 1968}) {
    name
    genre
    wasformed
  }
  maxkorzh:MusicBand(insert:{
      name:"Max Korzh",
      genre:["rap", "electro"],
      wasformed: 2006}) {
    name
    genre
    wasformed
  }
}

Execute query by clicking the play button:

Загрузка данных

The data is now uploaded.

Running data queries

Reading data

You can read data in the Graphql tab. Make sure the default scheme is switched on, clear the field on the left, and write a request that selects every music band:

query {
  MusicBand {
    name
    wasformed
    genre
  }
}

Click the play button. In the right field, you’ll get the result:

Чтение всех данных

Select data by the primary key:

query {
  MusicBand(name:"Black Sabbath") {
    name
    wasformed
    genre
  }
}

After clicking the play button, you will get all stored information about the Black Sabbath music band:

Чтение данных об одной музыкальной группе

Changing data

Add one more music genre to one of the music bands. In the Graphql tab, insert the data about the band with two genres instead of one:

mutation {
  MusicBand(insert:{
      name: "Deep Purple",
      genre: ["metal", "rock"],
      wasformed: 1968}) {
        name
        genre
        wasformed
  }
}

Click the play button. The information about the Deep Purple music band is now updated.

Deleting data

In the Graphql tab, write the query to delete all data about one of the music bands:

mutation {
  MusicBand(name:"Linkin Park" delete:true) {
    name
    genre
    wasformed
  }
}

Click the play button. You’ve deleted the data about the Linkin Park music band.

Writing stored procedures

Hello World

In the menu on the left, there is a tab called Code. Switch to the tab and create the src directory. In the src directory, create the hello.lua file, which is a Lua module that exports the functions:

function hello()
  return "Hello World"
end

return {
  hello = hello
}

Click Apply:

Создание файла hello.lua

This Lua module requires a GraphQL interface. In the Code tab, create a file called services.yml and specify the signature of the GraphQL call:

hello_world:
  doc: "Hello World script"
  function: hello.hello
  return_type: string

Click Apply:

Создание GraphQL-интерфейса

The code is validated and uploaded to the cluster. If there is an error, a notification at the bottom right corner will give you the details about it.

Now switch to the Graphql tab, select default the desired scheme, and call the stored procedure:

{
  hello_world
}

In the right field, you’ll get the result:

Hello World

Randomized playlist

In the dataset, there are various music bands. Make a stored procedure to give you a randomized playlist.

In the Code tab, open the src directory and create a file called playlist.lua. This file defines the logic to generate a randomized playlist:

local repository = require('repository')

function shuffle(tbl)
  for i = #tbl, 2, -1 do
    local j = math.random(i)
    tbl[i], tbl[j] = tbl[j], tbl[i]
  end
  return tbl
end

function playlist()
  local result = repository.find("MusicBand", {})
  result = result or {}
  shuffle(result)
  return result
end

return {
    playlist=playlist
}

In the services.yml, specify the signature of the GraphQL call:

playlist:
    doc: "Return randomized playlist"
    function: playlist.playlist
    return_type: {"type":"array", "items":"MusicBand"}

Switch to the Graphql tab and run this command:

{
    playlist { name }
}

Click the play button. As a result, you’ll get a randomized playlist:

Randomized playlist

Each time you click the play button, you’ll get a different playlist.

Data model

В этой главе подробно описана структура модели данных TDG, а также перечислены доступные способы работы с ней – в файле и в веб-интерфейсе. В главе рассмотрен пример создания модели данных и её загрузки в TDG. Для выполнения примера требуется настроенный кластер TDG.

Язык модели данных

Модель данных включает в себя:

В TDG для описания модели данных используются язык Avro Schema, а также расширения, разработанные специально для системы TDG.

Схема в стандарте Avro Schema – это JSON-файл с расширением .avsc, содержащий описание типов данных для объектов и для их полей. Приложение использует схему в качестве формата и понимает ее, как массив типов объектов:

[
    {"name": "TypeA", "type": "record", ...},
    {"name": "TypeB", "type": "record", ...}
]

Все типы объектов соответствуют стандарту Avro Schema, за исключением расширений для системы TDG. Расширения обратно совместимы, а модель, описанная с их помощью, успешно преобразуется стандартными парсерами (синтаксическими анализаторами).

Определение модели данных

Для начала зададим модель данных с двумя типами объектов – Country (страна) и City (город). В качестве примера возьмем следующую диаграмму объектов:

../../_images/data-model.svg

Теперь представим модель с диаграммы в виде схемы данных Avro:

[
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            { "name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country" }
        ]
    },
    {
        "name": "City",
        "type": "record",
        "doc": "Город",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ]
    }
]

где

Описания всех доступных расширений TDG приведены в разделе Расширения модели данных.

Загрузка модели данных

Чтобы применить модель данных и делать запросы к данным, нужно загрузить модель данных в TDG. Основные способы загрузки данных:

Загрузка через веб-интерфейс

Чтобы загрузить модель данных через веб-интерфейс TDG, выполните следующие шаги:

  1. Откройте веб-интерфейс на экземпляре, входящем в набор реплик с кластерной ролью runner. Если вы используете уже развернутый TDG-кластер, URL экземпляра будет следующий: http://172.19.0.2:8082.

  2. В веб-интерфейсе выберите вкладку Model.

  3. Вставьте созданную модель данных в поле Request.

  4. Нажмите Submit. Если модель данных загружена успешно, в окне Response появится ответ OK.

Загрузка в составе zip-архива

Загрузить модель данных можно также в составе zip-архива вместе с файлом конфигурации. Для этого:

  1. Упакуйте в zip-архив:

    • модель данных в файле с расширением .avsc, например, model.avsc;

    • файл конфигурации config.yml.

  2. Загрузите архив в TDG согласно инструкции.

Расширения модели данных

Расширения для системы TDG дополняют спецификацию Avro Schema. Эти расширения позволяют:

Задание отношений между объектами

Явно задавать связи между объектами нужно:

  • для валидации внешних ключей при вставке объектов;

  • для запросов связанных объектов через GraphQL.

Чтобы указать такую связь, используется поле relations в теле описания типа объекта. Это поле игнорируется существующими парсерами Avro Schema. Связываемые поля (внешние ключи в терминологии SQL) должны быть объявлены на уровне типов объектов.

Например, чтобы задать связь между страной и ее городами, требуются следующие поля:

  • title (Country) – первичный ключ доступен через обращение к типу объекта Country.title;

  • country (City) – внешний ключ доступен через обращение к типу объекта City.country.

Пример поля relations из заданной ранее модели данных:

{
    "relations": [
        {
            "name": "city_relation",
            "to": "City",
            "count": "many",
            "from_fields": "title",
            "to_fields": "country"
        },
        ...
    ]
}

где:

  • name – название поля, через которое можно получить связанные объекты в GraphQL-запросах;

  • to – тип объекта, с которым устанавливается связь;

  • count – вид связи. Возможные значения:

    • one – связь один к одному;

    • many – связь один ко многим;

  • from_fields – название поля или индекса, содержащего первичный ключ. Возможные значения:

    • название индекса ("from_fields": "title");

    • название поля ("from_fields": "field_name");

    • список названий полей ("from_fields": ["field_name1", "field_name2"]);

  • to_fields – название поля или индекса, содержащего внешний ключ. Возможные значения:

    • название индекса ("to_fields": "country");

    • название поля ("to_fields": "field_name");

    • список названий полей ("to_fields": ["field_name1", "field_name2"]).

Все параметры поля обязательные.

Поле relations можно задать как с одной стороны отношения, так и с обеих. Поле указывается только в одном типе объекта, когда запрашивать данные в обратном направлении не требуется.

Дополним модель данных еще одним полем relations (City), чтобы можно было запрашивать данные в обоих направлениях. Полный пример может выглядеть так:

[
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            {"name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country"}
        ]
    },
    {
        "name": "City",
        "type": "record",
        "doc": "Город",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ],
        "relations": [
            {"name": "country_relation", "to": "Country", "count": "one", "from_fields": "country", "to_fields": "title"}
        ]
    }
]

Задание индексов (ключей)

Для задания индексов используется поле indexes в описании типа объекта. Поле не меняет поведение, регулируемое стандартом Avro Schema, а добавляет дополнительные ограничения на хранение и запросы. Если для типа объекта указаны индексы, TDG создает спейсы под этот тип.

Note

Если поле indexes содержит список индексов, первичным индексом считается первый индекс в списке.

Синтаксис поля indexes:

{
    "indexes": ["<index1>", <"index2">, <"index3">, ...]
}

Каждый индекс в поле indexes может быть задан в виде:

  • строки с названием поля, по которому будет построен индекс ("indexes": ["title"]);

  • словаря, на основе которого строятся составной индекс или индекс по полю вложенного объекта. Такой индекс указывается в следующем формате:

    {
    "name": "<index_name>",
    "parts": [
        {"path": "<field_name>", "collation": "<collation_type>"},
        {"path": "<field_name>", "collation": "<collation_type>"},
        ...
    ]
}

    где:

    • name – название индекса, не совпадающее с именами существующих полей;

    • parts – части индекса. Включает в себя:

      • path – названия полей, по которым строится индекс;

      • collation (опционально) – способ сравнения строк. Возможные значения:

        • binary (по умолчанию) – бинарное сравнение ('A' < 'B' < 'a');

        • case_sensitivity – сравнение, зависящее от регистра ('a' < 'A' < 'B');

        • case_insensitivity – сравнение, не зависящее от регистра (('a' = 'A') < 'B' и 'a' = 'A' = 'á' = 'Á').

Note

Существуют ограничения при использовании в поле indexes мультиключевого индекса – индекса по полю, содержащему массив. Подробная информация об этих ограничениях приведена в разделе Запросы по мультиключевому индексу.

Пример составного индекса

{
    "name": "City",
    "type": "record",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int"},
        {"name": "capital", "type": "boolean"},
        {"name": "postcodes", "type": {"type":"array", "items":"int"}}
    ],
    "indexes": [
        {"name":"primary", "parts":["title", "country"]},
        "title",
        "country",
        "population",
        "postcodes"
    ]
}

Пример индексации по полю вложенного объекта

Иногда требуется построить индекс по полю не из самого объекта, а из его вложенного объекта. Вложенный объект при этом создается, чтобы сгруппировать логически набор стандартных полей.

Note

Тип объекта можно использовать как вложенный только в случае, если у этого типа не задано поле indexes.

Например, представьте, что каждая страна (Country) в примере содержит дополнительный блок информации для туристов. Создадим новый тип объекта Info и сложный индекс в типе объекта Country. Тип объекта Info включается здесь непосредственно в тип объекта Country, поэтому индекс может сослаться на поле из Info:

[
    {
        "name": "Info",
        "type": "record",
        "doc": "Информация для туристов",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "info_text", "type": "string"}
        ]
    },
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "info", "type": "Info"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": [
            "title",
            {"name": "info_id", "parts": ["info.id"]}
        ]
    }
]

Распределение объектов по хранилищам

В случае распределенного хранилища данных объекты распределяются с использованием хеш-функции от первичного ключа объекта. Указать такой индекс можно в поле affinity.

Note

Поле affinity может содержать только те поля, которые входят в первичный ключ (в том числе составной).

Пример

Перед загрузкой модели с новым полем affinity удалите старую модель данных. Кроме того, проверьте список спейсов во вкладке Settings > Unlinked spaces в веб-интерфейсе TDG. Если в списке есть спейсы с типом объекта City, удалите их, чтобы избежать ошибки при загрузке новой модели.

Теперь дополните модель данных новым полем и загрузите модель в TDG:

{
    "name": "City",
    "type": "record",
    "doc": "Город",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int"},
        {"name": "capital", "type": "boolean"},
        {"name": "postcodes", "type": {"type":"array", "items":"int"}}
    ],
    "indexes": [
        {"name":"primary", "parts":["title", "country"]},
        "title",
        "country",
        "population",
        "postcodes"
    ],
    "affinity": ["country"]
}

В примере города одной и той же страны размещены физически на одном хранилище. Поле affinity при этом содержит индекс из составного первичного ключа.

Атрибуты полей

Расширение для TDG дополняет список стандартных атрибутов полей Avro Schema:

  • default_function (function) – задает для поля динамическое значение по умолчанию. Значение атрибута – это функция, файл с которой хранится в директории src в корне проекта. При вставке в спейс новой записи вызывается указанная функция, и результат функции становится значением для данного поля. Атрибут не стоит путать со стандартным атрибутом default, который задает для поля статическое значение;

  • auto_increment (boolean) – значение true делает поле автоинкрементным. По умолчанию: false. Может использоваться в качестве числового идентификатора, уникального для объектов данного типа, даже при шардировании базы данных. Автоинкрементное поле обязательно должно иметь тип long. Атрибут несовместим с атрибутами default и default_function.

Пример

Расширьте тип объекта City этими атрибутами:

  • задайте по умолчанию для поля population динамическое значение;

  • добавьте поле с числовым идентификатором города.

Обновленные поля объекта могут выглядеть так:

{
    "name": "City",
    "type": "record",
    "fields": [
        {"name": "city_id", "type": "long", "auto_increment": true},
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int", "default" : "count_population.call"}},
        ...
    ],
    ...
}

Логические типы данных

Логический тип – это простой или составной тип данных Avro, содержащий дополнительные атрибуты для представления нового типа данных для поля. Чтобы объявить в модели поле с логическим типом, используется атрибут logicalType. Поля этих типов можно использовать при построении любых индексов, кроме мультиключевых. По умолчанию для логических типов задается строковый тип данных.

TDG поддерживает следующие логические типы:

Примеры объявления полей с логическими типами:

[
    {
        "name": "LogicalTypes",
        "type": "record",
        "fields": [
            {"name": "id", "type": {"type": "string", "logicalType": "Timestamp"}},
            {"name": "datetime", "type": ["null", {"type": "string", "logicalType": "DateTime"}]},
            {"name": "time", "type": ["null", {"type": "string", "logicalType": "Time"}]},
            {"name": "date", "type": ["null", {"type": "string", "logicalType": "Date"}]},
            {"name": "decimal", "type": ["null", {"type": "string", "logicalType": "Decimal"}]},
            {"name": "uuid", "type": ["null", {"type": "string", "logicalType": "UUID"}]}
        ],
    "indexes": ["id", "datetime", "time", "date", "decimal", "uuid"]
    }
]

Авторизация

Авторизация и отправка HTTP-запроса

Чтобы HTTP-запрос был обработан, он должен пройти авторизацию по токену приложений. Заранее сгенерированный (например, в веб-интерфейсе TDG) токен приложений необходимо передать в HTTP-заголовке запроса по схеме Authorization: Bearer <token>, где:

Пример

Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d

Important

Токен должен быть сформирован в кластере TDG, к которому осуществляется доступ, иначе он не пройдет авторизацию. Кроме того, ему должны быть выданы соответствующие права для выполнения операций чтения и записи с объектами модели данных.

В HTTP-запросе в заголовке указывается один из двух вариантов схемы данных:

Для выполнения запросов в примерах ниже используется утилита curl.

Пример запроса на добавление данных в схеме default:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --data '{"query":"mutation{  Country(insert: {  title: \"Poland\", phone_code:\"+48\"}) {title phone_code}}"}'

Пример запроса в схеме admin:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'schema: admin' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation{  token{  add(name:\"App01\", role:\"user\") {  name, token, created_at role }  }  }  "}'

В запросе внешнее приложение авторизуется, используя свой заранее созданный токен, и выпускает (генерирует) новый токен App01. Подробнее о генерации токена приложений через GraphQL API рассказывается в разделе Добавление токена Руководства администратора.

Авторизация коннекторов с использованием токена приложений

Приложения, использующие для доступа к данным в TDG коннекторы для языков программирования, авторизуются по токенам приложений. Подробнее о настройке таких коннекторов, запросах к данным и вызове сервисов рассказано в главе Использование бинарного протокола iproto.

Чтобы авторизовать коннектор, нужно указать токен приложения непосредственно в вызываемой функции в дополнительном аргументе credentials. Например, запрос на вставку объекта через интерфейс репозитория будет выглядеть следующим образом:

repository.put(type_name, obj, options, context, credentials)

где:

Пример авторизации с использованием токена приложений на языке Python:

from tarantool.connection import Connection
conn = Connection(server.host, server.binary_port, user='tdg_service_user', password='')
admin_token = {'token': '2fc136cf-8cae-4655-a431-7c318967263d'}
obj = {'id': '12567', 'name': 'John'}
conn.call('repository.put', 'Users', obj, {}, {}, admin_token)

Запрос из примера добавит новый объект Users с первичным ключом id, равным 12567, если такой ещё не существует.

Data access requests

Глава посвящена запросам данных в TDG. В ней описаны логика и синтаксис запросов, а также представлено несколько сценариев использования.

You will use the already deployed TDG cluster as the environment to run requests.

Preparing a data model

Чтобы загрузить данные в TDG, а затем получать к ним доступ через запросы GraphQL, нужно сначала определить модель данных. В этом руководстве используется модель из раздела по настройке модели данных:

  1. Определение модели данных.

  2. Загрузка модели данных.

Модель данных загружена. Теперь можно добавлять, выбирать и удалять данные.

Uploading data

Загрузить данные в TDG можно с помощью мутации GraphQL:

  1. On the left menu, click the GraphQL tab.

  2. Select default for the desired scheme and clear the request field.

    Вкладка GraphQL

  3. Paste the following request into the left field:

mutation all {
    russia:Country(insert: {
        title: "Russia",
        phone_code: "+7"}) {
    title
    phone_code
    }
    germany:Country(insert: {
        title: "Germany",
        phone_code: "+49"}) {
    title
    }
    moscow:City(insert: {
        title: "Moscow",
        country: "Russia",
        population: 12655050,
        capital: true,
        postcodes: [101000, 119021, 115035, 109028, 109004]}) {
    title
    country
    population
    capital
    postcodes
    }
    spb:City(insert: {
        title: "Saint Petersburg",
        country: "Russia",
        population: 5384342,
        capital: false,
        postcodes: [191193, 191040, 195275, 983002, 983015]}) {
    title
    country
    population
    capital
    postcodes
    }
    tver:City(insert: {
        title: "Tver",
        country: "Russia",
        population: 424969,
        capital: false,
        postcodes: [170006, 170100, 170037, 170028]}) {
    title
    country
    population
    capital
    postcodes
    }
    berlin:City(insert: {
        title: "Berlin",
        country: "Germany",
        population: 3520031,
        capital: true,
        postcodes: [10115, 110117, 10245, 10367]}) {
    title
    country
    population
    capital
    postcodes
    }
    munich:City(insert: {
        title: "Munich",
        country: "Germany",
        population: 1450381,
        capital: false,
        postcodes: [80339, 80336, 80639, 80798]}) {
    title
    country
    population
    capital
    postcodes
    }
    dresden:City(insert: {
        title: "Dresden",
        country: "Germany",
        population: 547172,
        capital: false,
        postcodes: [40210, 40212, 40595, 40627]}) {
    title
    country
    population
    capital
    postcodes
    }
}

  1. Execute the mutation by clicking the Execute Query button:

    Uploading data

The data has been uploaded, as you can see by the system response in the right field.

Data access requests

Here are the common use cases for data access requests:

Примеры запросов GraphQL, приведенные ниже, проще всего запустить через встроенный клиент GraphiQL в веб-интерфейсе TDG. Отправляя запросы на доступ к данным, используйте схему по умолчанию (default):

  1. On the left menu, click the GraphQL tab.

  2. Select default for the desired scheme, clear the request field, and paste the example request code.

General object type query

To select objects of a particular type, specify the type’s name and the object fields to return. You don’t have to indicate all the object fields that are defined in the data model. Specify any number of fields you need. For example:

query {
  Country {
    title
  }
}

Ответ – объект JSON, содержащий массив со всеми записями типа Country. Для каждой записи ответ включает только указанные в запросе поля.

{
  "data": {
    "Country": [
      {
        "title": "Russia"
      },
      {
        "title": "Germany"
      }
    ]
  }
}

Requests by primary index

A specific object can be selected by primary index:

query {
  Country(title: "Germany") {
    title
    phone_code
  }
}

Requests by secondary index

Requests by secondary index have the same syntax:

query {
  City(country: "Russia") {
    title
    country
    population
  }
}

Requests by compound index

To perform a request by compound index, specify an array of field values:

query {
  City(primary: ["Saint Petersburg", "Russia"]) {
    title
    country
    population
  }
}

Запросы по мультиключевому индексу

Мультиключевой индекс (multikey index) – это индекс по полю, которое содержит массив. Если под условие запроса по мультиключевому индексу подходят несколько элементов массива, будет несколько ключей, указывающих на один и тот же объект. Такой объект вернется несколько раз, и это нужно учитывать при составлении запросов и при обработке полученных результатов.

Кроме того, есть ряд ограничений при работе с мультиключевыми индексами:

Note

  • Мультиключевой индекс не может быть первичным.

  • Мультиключевой индекс не может быть составным.

  • Мультиключевой индекс невозможно построить по полю, содержащему сложные типы, например, DateTime, Date, Time и Decimal.

For example:

{
  City(postcodes_gt: 983000) {
    title
    postcodes
  }
}

Запрос вернет объект дважды:

{
  "data": {
    "City": [
      {
        "title": "Saint Petersburg",
        "postcodes": [
          191193,
          191040,
          195275,
          983002,
          983015
        ]
      },
      {
        "title": "Saint Petersburg",
        "postcodes": [
          191193,
          191040,
          195275,
          983002,
          983015
        ]
      }
    ]
  }
}

Comparison operators

Comparison operators are represented by index name suffixes.

Supported operators:

  • _gt (Greater Than)

  • _ge (Greater Than or Equal)

  • _lt (Less Than)

  • _le (Less Than or Equal)

For example:

query {
  City(population_ge: 1000000) {
    title
    country
    population
  }
}

При поиске по строковому индексу поддерживаются операторы:

  • _like – выборка по шаблону;

  • _ilike – выборка по шаблону без учета регистра.

В шаблонах можно использовать подстановочный символ %.

query {
  City(title_like: "M%") {
    title
    country
  }
}

Multiple conditions

В одном запросе можно сочетать несколько условий. Тогда TDG будет искать объекты, удовлетворяющие всем условиям одновременно (логическое И). Указывайте в условиях только индексированные поля.

query {
  City(country: "Russia", population_lt: 1000000) {
    title
    country
    population
  }
}

Requests by relations

Чтобы выбрать объекты по отношениям, используйте тот же синтаксис, что и в общем запросе объектов по типу.

В примере модели между объектами Country и City есть связь один ко многим. Поэтому вы можете одним запросом получить данные как о стране, так и о городах.

query {
    Country(title: "Russia") {
        title
        city {
            title
            population
    }
    }
}

Response example:

{
  "data": {
    "Country": [
      {
        "title": "Russia",
        "city": [
          {
            "title": "Moscow",
            "population": 12655050
          },
          {
            "title": "Saint Petersburg",
            "population": 5384342
          },
          {
            "title": "Tver",
            "population": 424969
          }
        ]
      }
    ]
  }
}

Pagination

В TDG применяется пагинация на основе курсора. Похожий механизм описан в документации GraphQL.

In general, the request with pagination has the following syntax:

query {
    object_name(first:N, after:$cursor)
    }

where

  • first определяет максимальное количество возвращаемых элементов (по умолчанию 10).

  • after передает непрозрачный курсор – строку, определяющую элемент, с которого система TDG должна продолжить выполнение запроса.

Here is the first request with pagination:

query {
    City(first: 2) {
        title
        country
        cursor
    }
}

The response is the following:

{
  "data": {
    "City": [
      {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin"
      },
      {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden"
      }
    ]
  }
}

To get the next data batch, take the cursor field’s value of the last object received and pass it as the after argument to the next request:

query {
    City(first: 2, after: "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk") {
        title
        country
        cursor
    }
}

Then run this logic in a cycle until you get an empty page:

{
  "data": {
    "City": []
  }
}

Pagination for requests with relations works in a similar way:

query {
  Country(title: "Russia") {
    title
    city(first: 2) {
        title
        population
        cursor
    }
  }
}

Страницы результатов можно выводить и в обратном порядке. В этом случае TDG будет возвращать объекты, предшествующие отмеченному курсором элементу. Чтобы страницы выводились в обратном порядке, укажите для аргумента first отрицательное значение:

query {
    City(first: -2) {
        title
        country
        cursor
    }
}

Requests by version

В TDG реализовано версионирование объектов, поэтому в условие запроса можно включать версии. Подробности вы найдете на этой странице: Версионирование.

Выбор экземпляров для выполнения запросов

В TDG можно определить, на каких узлах будет выполняться запрос.

Поддерживаются следующие параметры:

  • mode – установка целевого экземпляра для выполнения запроса. Тип: string. Значения:

    • write – целевым узлом будет мастер;

    • read – значение по умолчанию.

  • prefer_replica – установка реплики в качестве целевого экземпляра для выполнения запроса. Тип: boolean. Значения:

    • true – предпочитаемой целью будет одна из реплик. Если доступной реплики нет, то запрос будет выполнен на мастере.

    • false (по умолчанию) – запрос будет выполнен на мастер-узле.

    Параметр полезен для ресурсозатратных функций, чтобы избежать снижения скорости работы мастер-узлов;

  • balance – управление балансировкой нагрузки. Тип: boolean. Значения:

    • true (по умолчанию) – запросы будут распределяться по всем экземплярам набора реплик по кругу. При этом, если prefer_replica = true, предпочтение отдается репликам.

    • false – балансировка отключена.

Чтобы установить эти параметры, используйте в запросе GraphQL-директиву @options:

query {
    City @options(mode: read, balance: true) {
        title
        country
        population
    }
}

Эти параметры также можно определить в некоторых функциях программного интерфейса репозитория. Подробности вы найдете на странице Repository API.

Запросы к данным через REST API

В этом разделе описано взаимодействие с хранилищем TDG через REST API. Здесь вы найдёте примеры HTTP-запросов для распространённых сценариев работы с данными. Полное описание REST API TDG приведено в справочнике по REST API.

Подготовка данных

В этом руководстве используется модель из раздела по настройке модели данных:

  1. Определение модели данных.

  2. Загрузка модели данных.

HTTP-адреса REST API

Для работы с данными через REST API TDG предоставляет HTTP-адреса (endpoints) вида /data/<TypeName> для типов, объявленных в модели данных. Например, http://localhost:8081/data/City.

Авторизация

Для авторизации по REST API используется процедура авторизации HTTP-запроса по токену приложений. Для подробностей обратитесь к разделу Авторизация и отправка HTTP-запросов.

Запросы данных

Для получения данных определённого типа через REST API используются GET-запросы.

Через REST API можно выбирать данные по индексам со условиями поиска:

Условия выбора объектов по индексам передаются в HTTP параметрах запроса вида:

Полный список доступных параметров приведён в справочнике по REST API.

Рассмотрим реализацию некоторых популярных сценариев доступа к данным через REST API.

Точечный запрос объекта

Точечные запросы предполагают получение одного объекта по уникальному индексу. Для выполнения точечного запроса по полному совпадению достаточно выполнить один GET-запрос с параметром <index_name>=<value>, например, title_index=Berlin:

curl http://localhost:8081/data/City?title_index=Berlin

Note

Использование имён индексов, отличных от имён полей, позволяет точно знать, по какому индексу выполняется запрос и оптимизировать работу с данными за счёт этого.

Пакетная обработка

В случае выполнения запросов с неизвестным количеством результатов необходимо учитывать пагинацию – постраничную разбивку возвращаемых объектов. По умолчанию размер одной страницы равен 10. Это значит, что ответ на один запрос с условиями будет содержать максимум 10 записей, даже если подходящих объектов больше.

Если вы заранее знаете, сколько объектов хотите получить, вы можете изменить объём страницы с помощью параметра first. Например, получить 25 объектов, подходящих под условие выбора:

curl http://localhost:8081/data/City?population_ge=100000&first=25

Если количество результатов заранее неизвестно, нужно реализовать пакетную обработку (batching) с использованием курсоров. Курсоры позволяют задать начальный объект страницы.

Например, для получения всех объектов типа необходимо выполнять запросы в цикле с указанием параметра after - курсора последнего элемента, полученного в предыдущем запросе. Скрипт для выполнения такого цикла может выглядеть следующим образом:

while true; do
    url="http://127.0.0.1:8181/data/City?first=25"
    if [[ -n "$cursor" ]]; then
        url=$url"&after=$cursor"
    fi
    res=$(curl -s --url $url)
    if [[ $res == "[]" ]]; then break; fi
    len=$(echo $res | jq length)
    echo $len
    cursor=$(echo $res | jq ".[$len - 1].cursor")
done

Порядок возврата результатов

Порядок возврата результатов определяется индексом, используемым для выбора объектов, и условием выбора:

  • “меньше” и “меньше или равно” – по убыванию индекса

  • “больше” и “больше или равно” – по возрастанию индекса

Если индекс не указан (в запросе нет условий выбора), используется первичный индекс.

Объекты можно запросить в порядке возрастания любого из доступных индексов. Для этого используется параметр indexed_by=<index_name>:

curl http://localhost:8081/data/City?indexed_by=population&first=25

Note

Параметр indexed_by работает только при отсутствии условий выбора объектов. Если в запросе используется другой индекс для выбора объектов, условие indexed_by игнорируется.

Использование составных индексов

Если необходима фильтрация объектов по одному полю и сортировка по другому, рекомендуется использовать составной индекс, содержащий оба этих поля.

Пример: есть тип данных с полями типа string и datetime. Например, “событие”: у него есть дата и время (datetime) и идентификатор объекта, с которым произошло событие (string).

Допустим, нужно получить все события, произошедшие с выбранным объектом, по убыванию даты.

Для этого нужен составной индекс, включающий оба поля (object_datetime_index). Использовать этот индекс для поиска по полному совпадению не получится, поскольку изначально известен только идентификатор объекта, но не дата. Поэтому нужно выполнять поиск по условию “меньше или равно” с указанием только идентификатора объекта:

curl http://localhost:8081/data/Events?object_datetime_index_le="object_id"

Note

При необходимости используйте параметры first, after и пакетную обработку для получения нужного количества объектов.

В этом случае объекты будут фильтроваться только по идентификатору, без условий выбора даты. Но оператор сравнения “меньше или равно” применяется и к дате, поэтому результаты будут упорядочены по её убыванию.

При этом результат будет содержать лишние объекты с идентификаторами меньше указанного. Такие объекты нужно отсеять, отфильтровав массив полученных результатов в коде приложения.

Вставка данных

Для вставки данных определённого типа через REST API используются POST-запросы.

Тело POST-запроса должно содержать добавляемый объект в формате JSON.

Пример вызова curl для вставки объекта:

curl --request POST \
--url 'http://localhost:8081/data/City' \
--data '{"title": "Stuttgart","population": 623738,"country":"Germany","capital":false}'

В результате такого запроса возвращается вставленный объект в формате JSON. Для ускорения работы можно добавить параметр skip_result=true: в этом случае тело ответа будет пустым.

curl --request POST \
--url 'http://localhost:8081/data/City?skip_result=true' \
--data '{"title": "Stuttgart","population": 623738,"country":"Germany","capital":false}'

Изменение данных

Для модификации данных определённого типа через REST API используются PUT-запросы.

В запросах на модификацию данных используются те же параметры для поиска объектов по индексу, что и в запросах на чтение: <index_name>, <index_name>_ge, <index_name>_lt и так далее.

Для изменения объекта выполните PUT-запрос с параметром <index_name>=<value>, однозначно идентифицирущим объект. Например, title=Berlin:

В теле запроса должны содержаться новые значения изменяемых полей объектов в формате JSON.

curl --request PUT \
--url 'http://localhost:8081/data/City?title=Berlin' \
--data '{"population": 3520032}'

Параметр skip_result (пустой ответ) также может применяться в запросах на изменение данных:

curl --request PUT \
--url 'http://localhost:8081/data/City?title=Berlin&skip_result=true' \
--data '{"population": 3520032}'

Удаление данных

Для удаления данных определённого типа через REST API используются DELETE-запросы.

В запросах на модификацию данных используются те же параметры для поиска объектов по индексу, что и в запросах на чтение: <index_name>, <index_name>_ge, <index_name>_lt и так далее.

Для удаления объекта выполните DELETE-запрос с параметром <index_name>=<value>, однозначно идентифицирущим объект. Например, title=Berlin:

curl --request DELETE \
--url 'http://localhost:8081/data/City?title=Berlin'

Массовое удаление

Для массового удаления объектов можно использовать точечные DELETE-запросы с прохождением по списку объектов, например, полученному с помощью GET-запроса.

Однако, лучшим решением будет реализация массового удаления с помощью сервис-функций. Этот способ позволяет реализовать удаление с учётом особенностей схемы данных и в общем случае имеет лучшую производительность.

Разработка бизнес-логики

В этой главе описывается реализация бизнес-логики в TDG.

Бизнес-логика реализуется в TDG с помощью пользовательского кода на Lua – скриптовом языке, который нативно поддерживается в Tarantool. Единица бизнес-логики – исполняемая Lua-функция, загруженная в TDG – является аналогом хранимой процедуры в СУБД.

TDG расширяет возможности Tarantool по работе с пользовательским кодом, упрощая разработку бизнес-логики. В частности, доступны следующие возможности:

Lua-код, реализующий бизнес-логику решения TDG, можно разделить на следующие виды:

Подробнее о возможностях реализации бизнес-логики рассказывается на страницах этого раздела.

Сервис-функции

Сервис-функции (services) – это хранимые процедуры, реализующие бизнес-логику решения и доступные для вызова извне. В TDG такие процедуры представляют собой функции на языке Lua.

Чтобы добавить в TDG вызываемый сервис, нужно:

  1. Задать конфигурацию сервиса в формате YAML: его имя, аргументы вызова, возвращаемое значение.

  2. Реализовать необходимую логику на языке Lua с использованием Lua API TDG.

  3. Загрузить файлы с исходным кодом и конфигурацией сервиса в TDG.

После этого TDG автоматически сгенерирует API для вызова сервиса через GraphQL, REST API и iproto (бинарный протокол Tarantool).

В этом руководстве рассмотрим пример создания нового сервиса в TDG и способы его вызова.

Для выполнения примера требуются:

Пример сервиса будет возвращать список всех городов страны, загруженных в хранилище, по её имени.

Руководство включает в себя следующие шаги:

Подготовка конфигурации сервиса

Чтобы добавить в TDG сервис, необходимо добавить соответствующую секцию в конфигурацию TDG. Сервисы можно описывать либо в общем конфигурационном файле (секция services в файле config.yml), либо в отдельном файле services.yml.

Конфигурация сервиса включает такие параметры, как его уникальное имя, вызываемая функция, аргументы вызова, тип возвращаемого значения и другие. Полная информация о параметрах конфигурации сервисов приведена в справочнике по конфигурации бизнес-логики.

Пример минимальной конфигурации сервиса без аргументов:

# config.yml

services:
  hello_world:
    doc: "Hello World script"
    function: hello.hello
    return_type: string

Создадим конфигурацию сервиса для получения всех городов по названию страны:

# config.yml

services:
  get_cities:
    doc: "Get cities by country name"
    function: cities.get_cities
    return_type: {"type":"array", "items":"City"}
    args:
      country: string

types:
   __file: model.avsc

Эта конфигурация задаёт следующее поведение:

Реализация логики на Lua

Как указано в конфигурации сервиса, его код должен храниться в файле cities.lua в функции get_cities. Этот файл может выглядеть следующим образом:

-- cities.lua

local repository = require('repository')
local log = require('log')
local json = require('json')

function get_cities(arg)
  log.info('Getting cities of: %s', json.encode(arg))
  local result = repository.find("City", {{'country', '==', arg["country"]}})
  return result
end

return {
    get_cities = get_cities
}

Использование аргументов сервиса

Все аргументы сервиса передаются в первый аргумент функции в виде Lua-таблицы. Ключами в этой таблице являются имена аргументов, объявленные в конфигурации сервиса. Таким образом, для обращения к конкретному аргументу необходимо получить элемент таблицы по имени из конфигурации сервиса, например, arg["country"].

Использование модулей

TDG предоставляет набор Lua-модулей для реализации бизнес-логики. Набор включает как модули для работы с хранилищем Tarantool и подсистемами TDG, так и модули для работы с распространёнными технологиями, такими как различные СУБД или JSON.

В этом примере используются модули:

  • repository – интерфейс репозитория TDG. Содержит функции для работы с данными в хранилище Tarantool. В примере используется repository.find для поиска подходящих объектов типа City.

  • log – запись в журнал TDG. В примере используется log.info для записи в журнал информации о вызовах сервиса.

  • json – работа с JSON. В примере используется json.encode для формирования строкового JSON представления переданного аргумента.

Загрузка сервиса

Чтобы выполнить пример, нужно загрузить архив с моделью данных, файлом конфигурации и функцией сервиса в TDG:

  1. Поместите Lua-файл с кодом сервиса в папку src.

  2. Упакуйте в zip-архив:

    • папку src, внутри которой лежит файл с кодом сервиса;

    • модель данных model.avsc;

    • файл конфигурации config.yml.

  3. Загрузите архив в TDG согласно инструкции.

Вызов сервиса

GraphQL

Чтобы вызвать сервис через GraphQL, укажите в запросе имя сервиса и аргументы в формате name:value:

query {
  get_cities(country: "Germany")
}

Как и в случае запросов к данным, GraphQL позволяет получать отдельные поля возвращаемых объектов:

query {
  get_cities(country: "Germany") {
    title,
    capital
  }
}

Ответ:

{
  "data": {
    "get_cities": [
      {
        "title": "Berlin",
        "capital": true
      },
      {
        "title": "Dresden",
        "capital": false
      },
      {
        "title": "Munich",
        "capital": false
      }
    ]
  }
}

REST API

Сервисы доступны для вызова через REST API на HTTP-адресах (endpoint) вида /service/<service_name>. Для вызова сервисов используются POST-запросы.

Для вызова сервиса без аргументов отправьте POST-запрос на соответствующий адрес, например:

curl -X POST http://localhost:8081/service/hello_world

Если у сервиса есть аргументы, передайте их одним из двух способов:

  • в параметрах запроса с соответствующими именами:

    curl -X POST http://localhost:8081/service/get_cities?country=Russia

  • в теле запроса в формате JSON:

    curl -d '{"country":"Russia"}' -H "Content-Type: application/json" \
-X POST http://localhost:8081/service/get_cities

Ответ:

{
  "result": [
    {
      "cursor": "gaRzY2FukqZSdXNzaWGmTW9zY293",
      "country": "Russia",
      "title": "Moscow",
      "population": 12655050,
      "postcodes": [
        101000,
        119021,
        115035,
        109028,
        109004
      ],
      "capital": true
    },
    {
      "cursor": "gaRzY2FukqZSdXNzaWGwU2FpbnQgUGV0ZXJzYnVyZw",
      "country": "Russia",
      "title": "Saint Petersburg",
      "population": 5384342,
      "postcodes": [
        191193,
        191040,
        195275,
        983002,
        983015
      ],
      "capital": false
    },
    {
      "cursor": "gaRzY2FukqZSdXNzaWGkVHZlcg",
      "country": "Russia",
      "title": "Tver",
      "population": 424969,
      "postcodes": [
        170006,
        170100,
        170037,
        170028
      ],
      "capital": false
    }
  ]
}

Полная информация о REST API сервисов TDG приведена в справочнике по REST API.

Процессоры входящих и исходящих данных

Процессор (processor) – это подсистема, которая задает в TDG логику обработки объектов и автоматически выполняет пользовательский код при поступлении нового объекта или при его отправке через заданный коннектор. Для исполнения пользовательского кода используются обработчики.

Обработчик (handler) – это пользовательская функция, которая вызывается процессором и обрабатывает входящие или исходящие данные. В TDG такие функции представляют собой функции на языке Lua.

Существует два вида процессоров, оба они выполняются на экземплярах TDG с ролью runner:

В этом руководстве рассмотрим пример создания input-процессора и обработчика в TDG. В примере на HTTP-коннектор придет новый объект в формате JSON, который после преобразования в Lua-объект будет обработан input-процессором, а затем сохранен в хранилище – на экземплярах с ролью storage.

Для выполнения примера требуются:

Руководство включает в себя следующие шаги:

Конфигурация коннектора

Указать конфигурацию входящего коннектора можно:

Задайте конфигурацию входящего HTTP-коннектора:

# config.yml

connector:
  input:
    - name: http
      type: http
      routing_key: input_key

При получении нового объекта в формате JSON через HTTP-коннектор:

  1. JSON-объект преобразовывается в Lua-таблицу (объект Lua).

  2. Для объекта генерируется UUID, по которому можно проследить дальнейший путь объекта (например, найти его в ремонтной очереди).

  3. Объектам, пришедшим на коннектор, присваивается определенный ключ маршрутизации (секция routing_key в конфигурации коннектора).

Ключ маршрутизации – это строковый ключ, который задается объекту и определяет для него процесс дальнейшей обработки. На коннекторе такой ключ определяет, в какой обработчик на input-процессоре будет передан объект. Если ключ маршрутизации не задан, объект обрабатывается функцией по умолчанию, которая превращает объект вида { "obj_type": { "field_1": 1 } } в объект вида { "field_1": 1 } и задает значение ключа маршрутизации как routing_key = obj_type. После получения ключа маршрутизации объект передается на input-процессор.

Выше в конфигурации определены имя коннектора http, его тип http и ключ маршрутизации input_key, с которым объект отправится в обработчик, заданный в файле конфигурации в секции input_processor.

Подробная информация о параметрах конфигурации коннектора приведена в справочнике по конфигурации бизнес-логики.

Конфигурация input-процессора

Чтобы задать процессор для входящих данных в TDG, необходимо добавить соответствующую секцию в конфигурацию TDG. Input-процессор можно описывать:

Конфигурация input-процессора включает такие параметры, как вызываемый обработчик, ключ маршрутизации и система, куда следует направить объект. Полная информация о параметрах конфигурации input-процессора приведена в справочнике по конфигурации бизнес-логики.

Задайте конфигурацию процессора для входящих данных:

# config.yml

input_processor:
  handlers:
    - key: input_key
      function: handle_band.newband
  storage:
    - key: band
      type: MusicBand

Здесь в секции handlers задан ключ маршрутизации input_key. Объекты с таким ключом, пришедшие из HTTP-коннектора на input-процессор, передаются в функцию newband из модуля handle_band.

Кроме того, в секции storage в параметре key задается еще один ключ маршрутизации band. После настройки такого ключа маршрутизации:

  1. TDG определяет по ключу нужный тип объекта из модели данных.

  2. Объект, пришедший на input-процессор, валидируется в соответствии с моделью данных.

  3. Объект преобразовывается в тип из модели данных.

  4. Преобразованный объект сохраняется в хранилище.

Объекты, которым в обработчике handle_band.newband был присвоен ключ band, будут провалидированы по этому ключу в соответствии с моделью данных, преобразованы в тип MusicBand и сохранены на экземплярах с ролью storage.

Note

Если при обработке объекта input-процессором возникает ошибка, объект отправляется в ремонтную очередь. Информация об объектах в ремонтной очереди с описанием ошибок доступна администратору в веб-интерфейсе TDG на вкладке Repair Queues.

После задания всех необходимых настроек общий файл конфигурации будет выглядеть следующим образом:

# config.yml

types:
  __file: model.avsc

connector:
  input:
    - name: http
      type: http
      routing_key: input_key

input_processor:
  handlers:
    - key: input_key
      function: handle_band.newband
  storage:
    - key: band
      type: MusicBand

Реализация обработчика

Как указано в конфигурации процессора, код обработчика должен храниться в файле handle_band.lua. Создайте обработчик с функцией newband(obj), которая принимает на вход новый Lua-объект с музыкальной группой:

-- handle_band.lua

local log = require('log')
local json = require('json')

log.info('Starting handle_band.lua')
function newband(obj)
    log.info('Received new object from the HTTP connector: %s', json.encode(obj))
    obj.routing_key = "band"
    log.info('The routing key is set to "%s" value', obj.routing_key)
    return obj
end

return {
    newband = newband
}

Здесь функция newband(obj) выводит информацию об объекте obj, пришедшем из HTTP-коннектора, в логах TDG в формате JSON. После этого функция присваивает объекту новый ключ маршрутизации band, а затем возвращает этот объект.

Загрузка конфигурации

Чтобы выполнить пример, нужно загрузить архив с файлом конфигурации, моделью данных и функциями обработчиков в TDG. Для этого:

  1. Поместите Lua-файл с кодом обработчика в папку src.

  2. Упакуйте в zip-архив:

    • папку src, внутри которой лежит файл с кодом обработчика handle_band.lua;

    • модель данных model.avsc;

    • файл конфигурации config.yml.

  3. Загрузите архив в TDG согласно инструкции.

Добавление объекта через input-процессор

Чтобы проверить добавленную конфигурацию, добавьте новую музыкальную группу в TDG через HTTP-коннектор. Для этого переключитесь на вкладку Test и выберите для запроса формат JSON.

Введите в поле запрос в формате JSON и затем нажмите Submit:

{
  "name":"Beatles",
  "genre":["Rock-n-roll"],
  "wasformed": 1965
}

При успешном добавлении объекта в поле Response вернется ответ “OK”.

Проверить добавленные данные можно на вкладке Graphql. Убедитесь, что выбрана схема default, и напишите запрос на выборку всех музыкальных групп:

query {
  MusicBand {
    name
    wasformed
    genre
  }
}

Так как добавлена всего одна группа, ответ будет выглядеть следующим образом:

{
  "data": {
    "MusicBand": [
      {
        "genre": [
          "Rock-n-roll"
        ],
        "name": "Beatles",
        "wasformed": 1965
      }
    ]
  }
}

Также информацию о добавленном объекте можно проверить в логах TDG. В логах TDG видно, что сначала HTTP-коннектор получил на вход новый объект, а затем был запущен обработчик handle_band.lua.

Задачи

Задачи (tasks) – это загруженные в TDG пользовательские функции, которые исполняются автоматически (в том числе по расписанию) или вызываются вручную изнутри TDG.

Задачи используются для реализации внутренней бизнес-логики решения. Примеры: построение регулярных отчётов или инвалидация кэшей. Для реализации логики, доступной для вызова извне, используется механизм сервис-функций.

Технически, задачи реализуются в виде функций на языке Lua. Возвращаемое значение функции является результатом выполнения соответствующей задачи.

Существует три вида задач:

В этом руководстве рассмотрим пример создания задач в TDG и инструменты управления задачами.

Для выполнения примера требуется настроенный кластер TDG.

Руководство включает в себя следующие шаги:

Конфигурация задач

Чтобы добавить в TDG задачу, необходимо добавить соответствующую секцию в конфигурацию TDG. Задачи можно описывать либо в общем конфигурационном файле (секция tasks в файле config.yml), либо в отдельном файле tasks.yml.

Конфигурация задачи включает такие параметры, как её уникальное имя, вызываемая функция, вид задачи и другие. Полная информация о параметрах конфигурации задач приведена в справочнике по конфигурации бизнес-логики.

Пример конфигурации трёх задач разных видов:

# config.yml

tasks:
  report_now:
    kind: single_shot
    function: tasks.build_report
  update_caches:
    kind: continuous
    function: tasks.update_caches
    pause_sec: 3600
  weekly_report:
    kind: periodical
    function: tasks.build_report
    schedule: "0 0 19 * * 5"

Здесь:

Если вызываемая функция имеет аргументы, их значения можно передать в параметре args:

# config.yml

tasks:
  task_with_args:
    kind: single_shot
    function: tasks.function_with_args
    args: [1, "hello"]

Если в TDG включен режим обязательной аутентификации, необходимо добавить параметр run_as для указания пользователя, от имени которого будут выполняться задачи по расписанию и периодические задачи:

# config.yml

  update_caches:
    kind: continuous
    function: tasks.update_caches
    pause_sec: 3600
    run_as:
      user: username
  weekly_report:
    kind: periodical
    function: tasks.build_report
    schedule: "0 0 19 * * 5"
    run_as:
      user: username

Реализация задач на Lua

Как указано в конфигурации задач, соответствующие им функции должны храниться в файле tasks.lua.

Для упрощения демонстрации реализуем функции-заглушки:

-- tasks.lua

local function build_report()
    return 'Report is ready'
end

local function update_caches()
    return 'Caches updated'
end

return {
    build_report = build_report
    update_caches = update_caches
}

Загрузка задач

Чтобы выполнить пример, нужно загрузить архив с файлом конфигурации и функциями задач в TDG. Для этого:

  1. Поместите Lua-файл с кодом задач в папку src.

  2. Упакуйте в zip-архив:

    • папку src, внутри которой лежит файл с кодом задач;

    • файл конфигурации config.yml.

  3. Загрузите архив в TDG согласно инструкции.

Управление задачами

Инструменты для управления задачами и отслеживания их выполнения расположены на вкладке Tasks веб-интерфейса TDG. Полная информация об управлении задачами через веб-интерфейс приведена в разделе Задачи руководства администратора.

Взаимодействие с Kafka

Протокол Kafka – один из доступных форматов для запросов к данным в TDG. Формат позволяет как читать данные с сервера (брокера), а затем обрабатывать их, так и отправлять данные во внешние системы. В терминологии Kafka TDG при работе с запросами можно настроить как в качестве consumer (получение объектов), так и в качестве producer (отправка объектов). Для взаимодействия с шиной данных Apache Kafka в TDG используется коннектор типа Kafka.

Документация охватывает следующие темы, связанные с Kafka:

Запросы к данным через Kafka-коннектор

В руководстве пошагово демонстрируется пример работы TDG c Kafka – от настройки коннектора до выполнения обмена данными. Пример реализует следующую логику:

Для выполнения примера требуются:

Руководство включает в себя следующие шаги:

Настройка коннектора

Коннектор в TDG можно настроить двумя способами:

Зададим настройки первым способом, в файле .yml.

Создайте файл конфигурации config.yml со следующими настройками:

types:
  __file: model.avsc

connector:
  input:
    - name: from_kafka
      type: kafka
      brokers:
        - localhost:9092
      topics:
        - cities
      group_id: kafka
      routing_key: add_kafka

  output:
    - name: to_kafka
      type: kafka
      brokers:
        - localhost:9092
      topic: cities

input_processor:
  handlers:
    - key: add_kafka
      function: kafka_input_handler.call
  storage:
     - key: input_key
       type: City

output_processor:
  input_key:
    handlers:
      - function: kafka_output_handler.call
        outputs:
          - to_kafka

В файле указываются:

Чтобы ознакомиться со всеми доступными параметрами конфигурации для коннектора Kafka, обратитесь к справочнику по настройке коннектора.

Реализация обработчиков

Обработка входящих данных

Данные в формате JSON, приходящие из Kafka, попадают в обработчики (handlers), заданные в файле конфигурации в секции input_processor.

В функции обработчика можно модифицировать поступившую информации, а также обернуть данные в JSON с ключом routing_key для дальнейшей обработки.

В файле kafka_input_handler.lua укажите функцию, которая будет запускаться в input-процессоре. Функция увеличит значение population и задаст ключу routing_key значение input_key:

#!/usr/bin/env tarantool

return {
    call = function(params)
        params.obj.population = params.obj.population + 1
        params.routing_key = "input_key"
        return params
    end
}

Обработка исходящих данных

В разделе output указывается, как объект будет изменен в обработчике перед отправкой во внешние системы. Обработка выполняется после успешного сохранения объектов на экземплярах с ролью storage.

Чтобы обработать объект в output_processor, в файле конфигурации укажите название хранилища (input_key), в котором был сохранен объект, а затем определите обработчик для него (секция handlers).

Создайте файл kafka_output_handler.lua. В нем будет записана функция, вызываемая output-обработчиком. Функция вернет объект City:

#!/usr/bin/env tarantool

return {
    call = function(params)
        return {obj = params.obj}
    end
}

Загрузка конфигурации

Чтобы выполнить пример, нужно загрузить архив с моделью данных, файлом конфигурации и функциями обработчиков (handlers) в TDG:

  1. Поместите файлы со скриптами обработчиков (kafka_input_handler.lua и kafka_output_handler.lua) в папку src.

  2. Упакуйте в zip-архив:

    • папку src, внутри которой лежат файлы со скриптами обработчиков;

    • модель данных model.avsc;

    • файл конфигурации config.yml.

  3. Загрузите архив в TDG согласно инструкции.

Запуск и настройка Kafka

На сервере (брокере) Kafka создайте новый топик с именем cities. Для демонстрации работы примера и просмотра переданных в топик сообщений напишем простой скрипт на языке Python. Скрипт сыграет роль consumer Kafka, который получает сообщения из топика cities на брокере localhost:9092.

Чтобы работать с Kafka средствами Python, установите модуль kafka-python:

pip install kafka-python

Для запуска чтения сообщений, приходящих из топика cities, подготовьте следующий скрипт на языке Python:

from kafka import KafkaConsumer
consumer = KafkaConsumer('cities')
for message in consumer:
    print (message)

Чтобы выполнить скрипт, используйте интерактивный режим интерпретатора или сохраните функцию в файл consumer.py, а затем запустите ее командой python consumer.py.

Оставьте работать запущенный consumer.py, а затем переключитесь на новую вкладку консоли.

Запуск обработки объектов

Чтобы запустить отправку сообщений, отправьте в Kafka JSON-объект типа City с полем population. Для этого подготовьте следующий скрипт на языке Python:

from kafka import KafkaProducer
producer = KafkaProducer(bootstrap_servers='localhost:9092')
headers = [("Header Key", b"Header Value")]
producer.send('cities', value='{"title": "Moscow", "population": 12655050}'.encode('ascii'), headers=headers)
producer.flush()

Скрипт содержит подключение к Kafka в качестве producer и отправку простого JSON-объекта: {"title": "Moscow", "population": 12655050}.

Чтобы выполнить скрипт, используйте интерактивный режим интерпретатора или сохраните функцию в файл producer.py, а затем запустите ее командой python producer.py.

В результате TDG получит объект City из топика cities, обработает его (увеличится значение поля population) и сохранит, а затем отправит объект в тот же топик Kafka. Это вызовет повторное получение, обработку и отправку. Пока пример запущен, во вкладке терминала consumer будут появляться все новые сообщения с постоянно возрастающим значением поля population.

Чтобы остановить обработку объектов, выполните одно из действий ниже:

Решение проблем при работе с Kafka

При использовании Kafka проблемы могут возникнуть как на этапе подключения к брокеру, так и во время работы с данными. В статье рассматриваются распространенные ошибки и приводятся способы их устранения.

Чтобы облегчить решение возникших проблем

Обратитесь к разделу Инструменты для проверки ошибок, чтобы узнать больше.

Статья включает в себя следующие ошибки:

Проблема

Пример сообщения об ошибке

Неверно указан брокер

Failed to resolve 'kafka-broker:9091': Name or service not known

Неизвестный топик или раздел

kafka_error: consumer "kafka": Broker: Unknown topic or partition

Неверно заданы SSL-сертификаты

ip:port/bootstrap: Disconnected while requesting ApiVersion: might be caused by incorrect security.protocol configuration (connecting to a SSL listener?) or broker version is < 0.10 (see api.version.request)

Инструменты для проверки ошибок

Offset Explorer

Перед началом работы установите приложение Kafka Offset Explorer. В приложении можно просматривать данные кластеров – топики, брокеры, объекты и сообщения в топиках. Offset Explorer позволяет проверить соединение с кластером Apache Kafka, так что при подозрении на ошибку попробуйте подключиться к Kafka с его помощью. Если подключиться не удается, убедитесь, что конфигурация Kafka корректна.

Установив приложение, следуйте инструкции по подключению к Kafka. При добавлении кластера в Offset Explorer не забудьте заполнить поле Bootstrap servers во вкладке Advanced. Подключиться без этой настройки будет невозможно. В поле Bootstrap servers укажите номер порта, который используется для соединения. Данные для подключения должны соответствовать подключению в сервисе.

Логи TDG

При проверке конфигурации Kafka также могут быть полезны логи TDG. При подключении к Kafka в логах TDG выводятся:

В логах указаны значения для всех опций библиотеки librdkafka, в том числе выставленные по умолчанию. Отключить вывод логов нельзя.

Пример вывода для consumer:

tdg2                | 2023-03-02 16:17:19.810 [1] main/304/main I> [dcb31ae4-ca99-4b1c-995f-a0dd05194fa9] Kafka consumer for "kafka" input configuration: ---
tdg2                | ssl.engine.id: dynamic
tdg2                | socket.blocking.max.ms: '1000'
tdg2                | message.max.bytes: '1000000'
tdg2                | connections.max.idle.ms: '0'
tdg2                | enable_sasl_queue: 'false'
tdg2                | batch.size: '1000000'
...

Воспроизведение ошибок

Если вы хотите воспроизвести в тестовом режиме ошибки из статьи, обратитесь к репозиторию с примером настройки подключения к Kafka. В примере с помощью Docker Compose развернуты три контейнера, которые нужны для минимальной настройки:

  • TDG;

  • Zookeeper;

  • брокер (сервер) Kafka.

Чтобы развернуть контейнеры и воспроизвести ошибки, скачайте пример и после распаковки архива следуйте инструкции из файла 6_Quickstart_guide_TDG.md.

Возможные ошибки

Неверно указан брокер

Пример вывода

Failed to resolve 'kafka-broker:9091': Name or service not known

Возможные причины

В файле конфигурации config.yml неверно указаны номер порта для брокера Kafka или название Docker-контейнера.

Решение

Проверьте адрес брокера (параметр brokers) в секции connector в файле конфигурации config.yml. Сравните это значение с параметрами брокера Kafka. Например, если брокер Kafka запущен с помощью Docker Compose, проверьте параметры брокера ports и container_name в файле конфигурации Docker-контейнеров (docker-compose.yml).

Неизвестный топик или раздел

Пример вывода

kafka_error: consumer "kafka": Broker: Unknown topic or partition

Возможные причины

Запрос на запись был отправлен в несуществующий топик или раздел. Ошибка возникает, если на момент отправки данных на брокер указанный топик еще не был создан, и в Kafka отключено автоматическое создание топиков.

Решение

  • Убедитесь, что указанный топик существует. Если топика еще не существует, попробуйте создать его в Offset Explorer. Если при создании топика возникли проблемы, обратитесь к администратору Kafka.

  • Проверьте, что в настройках Kafka разрешено автоматическое создание топиков при отправке данных – по умолчанию такое поведение отключено. Если создание топиков разрешено, в Offset Explorer новый топик появится после обновления в папке Topics. При этом данные о новой записи не будут потеряны – запись будет добавлена в топик. При последующей отправке данных в этот топик ошибка возникать не будет.

Неверно заданы SSL-сертификаты

Пример вывода

ip:port/bootstrap: Disconnected while requesting ApiVersion: might be caused by incorrect security.protocol configuration (connecting to a SSL listener?) or broker version is < 0.10 (see api.version.request) (after 2ms in state APIVERSION_QUERY, 3 identical error(s) suppressed)

Возможные причины

  • Сертификат SSL настроен некорректно.

  • Версия брокера Kafka ниже 0.10.

Решение

  • Если соединение недоступно, запустите приложение Offset Explorer и попытайтесь подключиться к Kafka. Если подключиться с помощью Offset Explorer не удалось, проверьте, что параметры брокера Kafka настроены корректно.

  • Проверьте значение параметра security.protocol в секции коннектора input (раздел options) в файле конфигурации config.yml.

Использование бинарного протокола iproto

TDG поддерживает работу с хранилищем данных и пользовательскими сервисами через бинарный протокол Tarantool (iproto). В частности, бинарный протокол используется коннекторами к Tarantool из разных языков программирования, таких как Python, Java, Go и другие. Полный список доступных коннекторов и примеры их использования приведены в документации Tarantool.

Бинарный протокол Tarantool обеспечивает лучшее быстродействие по сравнению с HTTP и таким образом позволяет наиболее эффективно создавать промежуточные слои бизнес-логики перед TDG. При этом выбор языка для реализации этой логики предоставляется разработчику.

В этом руководстве демонстрируется работа с данными и сервисами TDG через бинарный протокол Tarantool. Руководство включает следующие шаги:

В примерах используется:

Для вызовов используется язык Python и коннектор tarantool-python. Чтобы узнать, как делать аналогичные вызовы из других языков, обратитесь к документации соответствующего коннектора.

Настройка коннектора

Для возможности подключения к TDG через бинарный протокол используется коннектор типа tarantool_protocol. Настроить коннектор можно двумя способами:

Пример YAML-конфигурации входящего коннектора iproto:

input:
- routing_key: null
  type: tarantool_protocol
  is_async: true
  name: iproto

Подробнее о параметрах коннектора рассказывается в справочнике по настройке коннекторов.

Подключение

Клиенты, которые подключаются к TDG через бинарный протокол, используют подключение напрямую к экземпляру Tarantool, имеющему кластерную роль connector. В связи с этим для подключения используется учетная запись пользователя Tarantool.

Important

Здесь используются пользователи, созданные в самом Tarantool, а не пользователи TDG. Подробнее об управлении пользователями Tarantool рассказывается в документации по контролю доступа в Tarantool.

Пример подключения через Python-коннектор:

from tarantool.connection import Connection

conn = Connection(server.host, server.binary_port, user='tdg_service_user', password='')

По умолчанию для подключения доступны пользователи:

При необходимости вы можете добавить других пользователей Tarantool c нужными привилегиями. Инструкции по управлению пользователями в Tarantool приведены в документации по контролю доступа в Tarantool.

После того, как подключение установлено, TDG проверяет права клиента на выполнение каждого входящего вызова с помощью токенов приложений. Токен передается непосредственно в вызовах функций через iproto-соединение в аргументе credentials. Пример:

conn.call('repository.put', 'Users', obj, {}, {}, {'token': token})

Подробнее об использовании токенов приложений рассказывается в главе Авторизация.

Запросы GraphQL

Для отправки запросов GraphQL через бинарный протокол используется функция execute_graphql. Её основные аргументы:

Пример отправки GraphQL-запроса через бинарный протокол без переменных:

resp, _ = conn.call('execute_graphql', {
    "query": '''
           query {
               Country {
                   title
               }
           }
       ''',
    "schema": "default",
})

Пример отправки GraphQL-запроса через бинарный протокол с переменными:

resp, _ = conn.call('execute_graphql', {
    "query": '''
        query ($title: String!)  {
            Country(title: $title) {
                title,
                phone_code
            }
        }
    ''',
    "variables": {
        "title": "Russia"
    },
    "schema": "default",
})

Пример GraphQL-вызова сервиса через бинарный протокол:

resp, _ = conn.call('execute_graphql', {
    "query": '''
        query {
            hello_world
        }
    ''',
    "schema": "default",
})

Пример GraphQL-вызова сервиса ` с аргументами через бинарный протокол:

resp, _ = conn.call('execute_graphql', {
    "query": '''
        query ($title: String!)  {
            Country(title: $title) {
                title,
                phone_code
            }
        }
    ''',
    "variables": {
        "title": "Russia"
    },
    "schema": "default",
})

Note

Вызов сервисов через бинарный протокол напрямую описан в разделе Вызов сервисов.

Подробнее о доступе к данным в TDG через GraphQL рассказываeтся в главе Запросы данных.

Использование интерфейса репозитория

Функции Repository API доступны для вызова через бинарный протокол напрямую. Для вызова необходимо указать вызываемую функцию (например, repository.get) и передать её аргументы.

Пример запроса объекта по ключу через интерфейс репозитория:

resp, _ = conn.call('repository.get', ( 'Country', ['Russia']))

Пример вставки объекта через интерфейс репозитория:

resp, _ = conn.call('repository.put', ( 'Country', {'title': 'China', 'phone_code': '+86'}))

Вызов сервисов

Для вызова сервисов через бинарный протокол используется функция call_service. Её основной аргумент - имя вызываемого сервиса. Если у него есть аргументы, они передаются в виде таблицы в следующем аргументе.

Пример вызова сервиса без аргументов через бинарный протокол:

resp, _ = conn.call('call_service', 'hello_world')

Пример вызова сервиса с аргументами через бинарный протокол:

resp, _ = conn.call('call_service', 'get_cities', {'country': 'Russia'})

Загрузка данных из файлов

В этой главе описывается загрузка данных в TDG из файлов.

TDG предоставляет возможность загрузки данных в хранилища из файлов с помощью файловых коннекторов. Поддерживается загрузка из двух форматов: comma-separated values (csv) и JSON Lines (jsonl).

В момент своего создания файловый коннектор обрабатывает все входящие данные из указанного в конфигурации файла и затем удаляет его. После этого коннектор периодически проверяет существование файла и при его наличии загружает содержимое. Таким образом, для загрузки новых данных нужно помещать их в файл с тем же именем.

В этом руководстве рассмотрим пример загрузки данных из CSV-файла в TDG с помощью файлового коннектора.

Для выполнения примера требуются:

Руководство включает в себя следующие шаги:

Создание и загрузка файла с данными

CSV-файл с данными для загрузки в TDG должен содержать в каждой строке поля одного объекта данных. Файл может содержать данные только одного модельного типа. Первая строка должна описывать формат строк с данными: в ней указывается порядок полей объекта.

CSV-файл countries.csv для загрузки нескольких объектов типа Country может выглядеть следующим образом:

"title","phone_code"
"Argentina","+54"
"Australia","+61"
"Austria","+43"

Note

Значения обнуляемых полей могут быть пропущены. В этом случае они получат значение null.

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

Для выполнения примера загрузите файл на сервер, на котором работает узел кластера с ролью connector, в директорию /tmp/csv/.

Настройка коннектора

Файловый коннектор в TDG можно настроить в файле конфигурации .yml.

Создайте файл конфигурации config.yml со следующими настройками:

types:
  __file: model.avsc

connector:
  input:
    - name: csv_importer
      type: file
      format: csv
      workdir: /tmp/csv/
      filename: countries.csv
      routing_key: input_key

input_processor:
  handlers:
    - key: input_key
      function: classifier.call
  storage:
    - key: country
      type: Country

В файле указываются:

Чтобы ознакомиться со всеми доступными параметрами конфигурации файлового коннектора, обратитесь к справочнику по настройке коннектора.

Реализация обработчика

Данные из файла попадают через коннектор в обработчики (handlers), заданные в файле конфигурации в секции input_processor.

В функции обработчика можно модифицировать поступившую информации, а также определить ключ routing_key для дальнейшей обработки. В данном случае следующим этапом будет сохранение в хранилище объектов Country.

В файле classifier.lua укажите функцию, которая будет запускаться в input-обработчике. Функция задаст ключу routing_key значение country:

return {
    call = function(param)
        param.routing_key = 'country'
        return param
    end
}

Загрузка конфигурации

Чтобы выполнить пример, нужно загрузить архив с моделью данных, файлом конфигурации и функцией обработчика в TDG:

  1. Поместите файл с функцией обработчика classifier.lua в папку src.

  2. Упакуйте в zip-архив:

    • папку src, внутри которой лежит файл classifier.lua;

    • модель данных model.avsc;

    • файл конфигурации config.yml.

  3. Загрузите архив в TDG согласно инструкции.

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

Warning

В результате срабатывания файлового коннектора файл, из которого выполнялась загрузка, будет удалён.

В случае ошибки при работе файлового коннектора в директории workdir будет создан файл с расширением .error с информацией об ошибке.

Проверка загрузки данных

В результате работы файлового коннектора:

Для проверки добавления новых объектов отправьте GraphQL-запрос на чтение объектов типа Country (например, на вкладке GraphQL веб-интерфейса TDG):

{
  Country {
    phone_code
    title
  }
}

В результате вы получите список объектов, которые были описаны в CSV-файле:

{
  "data": {
    "Country": [
      {
        "title": "Argentina",
        "phone_code": "+54"
      },
      {
        "title": "Australia",
        "phone_code": "+61"
      },
      {
        "title": "Austria",
        "phone_code": "+43"
      }
    ]
  }
}

Версионирование

Этот раздел объясняет, как управлять данными в Tarantool Data Grid (TDG).

Управление версиями данных в TDG

Управление версиями данных (версионирование) – это возможность сохранять, извлекать и восстанавливать разные версии объектов, а также отслеживать когда и какие изменения в них были внесены.

В TDG для управления версиями используется параметр versioning, который задается в файле конфигурации config.yml.

Когда параметр включен, в определенные моменты времени для всех созданных или модифицированных объектов сохраняются новые версии.

Например, у нас есть модель данных и тип объекта Country, для которого включено версионирование. Спейс, где хранятся объекты данного типа, имеет первичный ключ. Если выполняется операция по сохранению в спейс нового объекта с таким же значением первичного ключа, то новый объект не заменит предыдущий, а будет сохранен как новый кортеж, но с уникальным значением timestamp, которое фиксируется каждый раз при сохранении объекта. Это время является идентификатором версии объекта и также сохраняется в кортеже, в котором хранится информация об объекте.

Сочетание первичного ключа и уникального времени сохранения объекта позволяет иметь несколько версий одного и того же объекта. Это может быть полезно, если необходимо хранить историю изменения параметров объекта.

По умолчанию на хранение версий установлено ограничение – не более пяти версий для одного объекта, но вы можете выставить другое значение в config.yml.

Note

Старайтесь ограничивать количество хранимых версий, чтобы сохранять высокую производительность TDG.

Почему версионирование важно?

Версионирование может быть полезно во многих случаях. Например:

Таким образом, версионирование помогает свести к минимуму стоимость ошибок и отследить изменение данных с течением времени. Это также способ увеличить скорость разработки.

Настройка параметров версионирования

Версионирование выключено по умолчанию, чтобы улучшить производительность TDG.

Вы можете включить версионирование в конфигурации системы – в файле config.yml. Для этого укажите параметр versioning.

Пример. Воспользуйтесь типом объекта Country из примера модели данных и настройте для него версионирование. Для этого откройте файл config.yml и в блоке versioning укажите следующее:

versioning:
  - type: Country
    enabled: true

После этого версионирование для Country будет включено.

Note

При включении версионирования старая история версий будет удалена.

Вы также можете настроить следующие параметры, относящиеся к версионированию:

Подробную информацию об этих параметрах вы можете найти в файле config.yml.

Пример. Задайте параметры версионирования для типов объектов Country и City из примера модели данных.

Country: хранить 7 версий, ограничить время жизни 4 часами, запускать проверку через 1 секунду, использовать холодное хранение.

City: хранить 3 версии, ограничить время жизни 2 днями, запускать проверку через 1 секунду, архивировать версии в файл.

versioning:
  - type: Country
    enabled: true
    keep_version_count: 7
    lifetime_hours: 4
    delay_sec: 1
    strategy: cold_storage
    schedule: "0 0 0 */1"
  - type: City
    enabled: true
    keep_version_count: 3
    lifetime_days: 2
    delay_sec: 1
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 100001

Note

Если параметр strategy задан на вывод в файл или холодное хранение, необходимо указать schedule – расписание запуска задачи на архивацию в формате cron с поддержкой секунд. При выводе в файл также необходимо указать максимальный размер файла, используя file_size_threshold.

Включить версионирование и задать эти параметры также можно в разделе Data types в веб-интерфейсе. При указании значения параметра lifetime_hours больше 24 часов система автоматически пересчитает значение в соответствующее количество дней, месяцев или лет.

Запросы к данным по версии

Запросы к данным по версии выполняются путем указания поля version в теле HTTP-запроса или запроса GraphQL.

В TDG есть две категории таких запросов:

Исторические данные

Запросы на чтение исторических данных полезны, например, когда часть информации была удалена в последней версии объекта.

Вспомним пример модели данных и рассмотрим запрос на чтение исторических данных Country.

Пример. У нас есть тип объекта Country с информацией о телефонном коде страны. Но в последней версии Country правильная информация о телефонном коде была изменена.

Чтобы получить правильную информацию о телефонном коде, нужно посмотреть предыдущую версию Country.

Сделать это можно в два этапа:

  1. Узнайте последнюю версию Country

  2. Сделайте запрос на чтение данных предыдущий версии Country

Чтобы проверить последнюю версию, добавьте поле version в параметры запроса GraphQL:

{
  Country(title: "Russia") {
    title
    phone_code
    version
  }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "version": "1515",
        "title": "Russia",
        "phone_code": "+8"
      }
    ]
  }
}

Note

Ответ возвращает указанную или более раннюю версию, если запрошенная версия не существует. Если поле version не было указано, ответ вернет последнюю версию объекта.

Скопируйте из ответа значение version, вычтите из него единицу и выполните запрос GraphQL на предыдущую версию:

{
  Country(title: "Russia", version: "1514") {
    title
    phone_code
    version
  }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "version": "1514",
        "title": "Russia",
        "phone_code": "+7"
      }
    ]
  }
}

Вы можете перебирать предыдущие версии, пока не обнаружите версию с нужной информацией.

Note

Если запрошенная версия меньше существующего минимального значения, ответ вернет пустой объект.

Вы также можете запросить все версии объекта, используя поле all_versions, и ограничить результат ответа при помощи пагинации:

{
  Country(title: "Russia", all_versions: true, first: 5) {
    title
    phone_code
  }
}

Исторические модификации

Запросы на исторические модификации данных полезны, например, когда нужно изменить или удалить данные в конкретной версии объекта.

TDG поддерживает следующие запросы на изменение данных (mutations):

Для осуществления запросов на изменение данных вы можете использовать HTTP-запросы или запросы GraphQL.

Note

Выполнение HTTP-запросов потребует токен приложений. В примерах используется уже сгенерированный токен Authorization: Test f0d4d72b-2232-42ff-a1ee-1127a93df0d3. Вам необходимо сгенерировать свой токен с правами на запись и чтение в кластере TDG, к которому будет осуществляться доступ, иначе авторизация не пройдет.

Ниже приведены примеры обоих вариантов запросов.

Вставка объекта

Когда вы добавляете объект, поле version определяет, какая версия объекта добавляется или заменяется.

Пример. Добавьте объект типа Country с title: "Poland" и phone_code: "+48".

Пример запроса GraphQL:

mutation {
  Country(
    insert: {
      version: "1515"
      title: "Poland"
      phone_code: "+48"})
  {
    version
    title
    phone_code
  }
}

Пример HTTP-запроса с использованием утилиты curl:

curl --request POST \
   --url 'http://172.19.0.2:8080/graphql?=' \
   --header 'Authorization: Test f0d4d72b-2232-42ff-a1ee-1127a93df0d3' \
   --data '{"query":"mutation {Country(insert: {version: "1515", title: \"Poland\", phone_code:\"+48\"}) {version title phone_code}}"}'

Ответ в обоих случаях будет одинаковым:

{
  "data": {
    "Country": [
      {
        "version": "1515",
        "title": "Poland",
        "phone_code": "+48"
      }
    ]
  }
}

Note

Если указанного параметра version нет, то вставка данных будет выполнена в ближайшую предыдущую версию этого объекта. Если необходимо вставить данные во все версии объекта, используйте поле all_versions.

Обновление объекта

При обновлении данных в поле version указывается версия объекта, подлежащая изменению.

Пример. Вернемся к типу объекта Country. В запросе укажем версию 1515 и обновим поле phone_code на значение +7.

Пример запроса GraphQL:

mutation {
  Country(title: "Russia", version: "1515" update:[["set", "phone_code", "+7"]]) {
    version
    title
    phone_code
  }
}

Пример HTTP-запроса с использованием утилиты curl:

curl --request POST \
   --url 'http://172.19.0.2:8080/graphql?=' \
   --header 'Authorization: Test f0d4d72b-2232-42ff-a1ee-1127a93df0d3' \
   --data '{"query":"mutation {Country(update: {title: "Russia", version: "1515" [[\"set\", \"phone_code\", \"+7\"]]) {title version phone_code}}"}'

Ответ в обоих случаях будет одинаковым:

{
  "data": {
    "Country": [
      {
        "version": "1515"
        "title": "Russia"
        "phone_code": "+7"
      }
    ]
  }
}

Note

Если указанного параметра version нет, то обновление данных объекта будет выполнено в ближайшую предыдущую версию этого объекта.

Удаление объекта

При удалении данных в поле version указывается версия объекта, подлежащая удалению.

Note

Чтобы все версии объекта были полностью удалены, установите значение true параметру all_versions.

Пример. Удалите объект Country с версией 1514.

Пример запроса GraphQL:

mutation {
  Country(delete: true, title: "Russia", version: "1514") {
    title
    version
    phone_code
  }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "version": "1514"
        "phone_code": "+7",
        "title": "Russia"
      }
    ]
  }
}

Note

Если параметр version не задан, то будет удалена последняя версия объекта.

Ограничения запросов

Использование дополнительных параметров блока hard-limits в config.yml помогает контролировать нагрузку на сервер. Вы можете задать следующие параметры:

Пример заполнения параметров:

hard-limits:
  scanned: 1500
  returned: 200

Практический пример использования

Воспользуемся примером аналитики, чтобы получить более четкое представление о пользе версионирования в различных сферах.

Основной процесс аналитики заключается в создании метрик, содержащих логику для оценки бизнеса и поведения пользователей.

Вспомним пример модели данных и добавим новый тип объекта Tourists:

[
    {
        "name": "Country",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            { "name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country" }
        ]
    },
    {
        "name": "City",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ]
    },
    {
        "name": "Tourists",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "name", "type": "string"},
            {"name": "number_of_visits", "type": "int"}
        ],
        "indexes": ["title"],
        "relations": [
            { "name": "city", "to": "City", "count": "many", "from_fields": "title", "to_fields": "сity" }
        ]
    },
]

Tourists уже имеет 12 версий, и сегодня нам нужно сделать очередную выборку о количестве посещений туристами определенного города.

Для этого всегда использовался запрос на чтение Tourists:

{
  Tourists(title: "Moscow") {
    title
    country
    number_of_visits
  }
}

Но сегодня запрос, который отлично работал день назад, вызывает ошибки из-за измененных данных. Самый эффективный способ выяснить, что вызывает проблему – выполнить тот же запрос к предыдущей версии, в которой не было ошибки. В нашем случае – это версия 11:

{
  Tourists(title: "Moscow", version: "11") {
    title
    country
    number_of_visits
  }
}

Note

Если же версия объекта нам неизвестна, сначала потребуется выполнить запрос на чтение исторических данных.

Но ответ снова возвращает ошибку. В этом случае необходимо сделать новый запрос к 10 версии объекта и продолжать делать запросы к предыдущим версиям, пока не будет найдена та, в которой нет ошибки.

Обнаружив такую версию, вы можете передать эти данные команде разработке. Сведения о том, с какой версии появилась ошибка, позволит им решить проблему гораздо быстрее. Вы же сможете временно использовать рабочую версию объекта, если она содержит необходимые данные для решения вашей задачи.

Таким образом, если вы используете версионирование, это упрощает отладку и приводит к быстрому исправлению ошибок данных.

Рекомендации

Каким должен быть срок хранения старых версий?

Вы должны определить точный период хранения версий, исходя из потребностей компании.

Рекомендованный период хранения – не менее 30 дней. Но не более одного года, так как это может повлиять на производительность TDG.

Reference

This document describes Tarantool Data Grid (TDG) API functions and configuration parameters.

Конфигурация Tarantool Data Grid

В этой главе описывается конфигурация Tarantool Data Grid. С ее помощью можно настроить логику обработки входящих запросов, кластерные роли и другие системные параметры TDG.

Местоположение

Конфигурация TDG может храниться в едином файле config.yml или быть семантически разбитой на несколько файлов: schema.yml, topology.yml и т. д. – подобно тому, как это делается в Tarantool Cartridge.

По умолчанию конфигурация каждого экземпляра хранится по адресу /var/lib/tarantool/<имя_экземпляра>/config.yml или в папке /var/lib/tarantool/<имя_экземпляра>/config/.

Загрузка

Если конфигурация собрана в одном файле config.yml, в веб-интерфейсе перейдите на вкладку Configuration files, нажмите на кнопку Upload a new config и загрузите файл.

Если конфигурация разнесена по разным файлам, соберите их в архив. Затем в веб-интерфейсе перейдите на вкладку Configuration files, нажмите на кнопку Upload a new config и загрузите архив. Файлы будут распакованы и применены.

Пример файла config.yml

---
types:
  __file: model.avsc

connector:
  input:
    - name: http
      type: http
      routing_key: input_processor

routing:
  - key: smtp_key
    output: to_smtp

output:
  - name: to_smtp
    type: smtp
    url: localhost:2525
    from: tdg@example.com
    timeout: 5
  - name: dummy
    type: dummy

input_processor:
  handlers:
    - key: input_processor
      function: handler.call

storage:
  - key: country_key
    type: Country
  - key: city_key
    type: City
  - key: tourists_key
    type: Tourists

output_processor:
  estate_key:
    handlers:
      - function: output.country_output.call
        outputs:
          - dummy

services:
  calc_district_stat:
    doc: "calculate statistic for selected district"
    function: districts_stat.calc_statistics.call
    return_type: string
    args:
      district: string
  calc_all_districts_stat:
    doc: "calculate statistic for all district"
    function: districts_stat.calc_statistics.call
    return_type: string

tasks:
  update_all_districts_stat:
    kind: periodical
    function: districts_stat.calc_statistics.call
    # синтаксис в стиле cron с точностью до секунд
    # формат: секунда минута час день месяц день_недели
    schedule: "0 */5 * * * *"

logger:
  enabled: true

versioning:
  - type: Country
    enabled: true
  - type: City
    enabled: true

Конфигурация кластера

В конфигурацию кластера можно добавить параметры топологии и авторизации, а также настройку времени ожидания сетевых вызовов при шардировании.

Параметры топологии

Топология кластера настраивается при помощи секций topology и vshard_groups.

Note

Рекомендуется создать и настроить эти секции в отдельных файлах: topology.yml и vshard_groups.yml, поместив эти файлы в папку config в корне проекта.

Секция topology

Секция topology содержит три главных подраздела:

replicasets

Этот подраздел содержит информацию о том, как экземпляры организованы в наборы реплик.

Каждый набор реплик идентифицируется по своему номеру UUID. Для каждого приводятся следующие параметры:

  • weight – вес набора реплик. По умолчанию: 0 (подключен, но пока не принимает данные). При указанном весе 0 попытки шардирования будут приводить к ошибке на роутере (vshard-router).

  • master – UUID экземпляра-мастера в этом наборе реплик.

  • alias – человекопонятное имя набора реплик.

  • vshard_group – группа шардирования, к которой относится набор реплик. По умолчанию: default.

  • roles – список кластерных ролей, включенных (true) или выключенных (false) для набора реплик.

  • all_rw – являются ли все узлы в наборе реплик мастерами. По умолчанию: false.

Пример для одного набора реплик:

replicasets:
  5e47bf8e-57f5-4166-96ba-e16f964fb82b: # UUID набора реплик
    weight: 1
    master:
    - dee26aab-0190-461d-9121-56b96b881a59
    alias: unnamed
    vshard_group: default
    roles:
      tracing: true
      ddl-manager: true
      maintenance: true
      watchdog: true
      account_provider: true
      metrics: true
      common: true
      core: true
      failover-coordinator: true
      storage: true
      runner: true
      vshard-router: true
      connector: true
      vshard-storage: true
    all_rw: false

servers

В этом подразделе приведен список всех экземпляров Tarantool. Каждый из них идентифицируется по своему номеру UUID. Для каждого указаны следующие параметры:

  • uri – внутренний URI-адрес экземпляра.

  • disabled – выключен ли экземпляр. По умолчанию: false.

  • replicaset_uuid – UUID набора реплик, в котором состоит экземпляр.

Пример для одного экземпляра:

servers:
  dee26aab-0190-461d-9121-56b96b881a59:
    uri: localhost:3301
    disabled: false
    replicaset_uuid: 5e47bf8e-57f5-4166-96ba-e16f964fb82b

failover

В этом подразделе указываются настройки восстановления после сбоев, аналогичные соответствующим настройкам Cartridge.

Пример:

failover:
  fencing_enabled: true
  failover_timeout: 20
  fencing_pause: 2
  mode: eventual
  fencing_timeout: 10

По умолчанию подраздел отключен:

failover: false

Секция vshard_groups

В этой секции указываются группы шардирования, или vshard-группы, к каждой из которых может принадлежать один или несколько наборов реплик. Внутри такой группы данные шардируются между входящими в нее наборами реплик.

В vshard-группе могут состоять только наборы реплик с ролью storage. Один набор реплик не может состоять в двух разных vshard-группах.

Параметры групп шардирования указываются так же, как при работе с Tarantool.

Значения по умолчанию:

default:
  rebalancer_max_receiving: 100
  bootstrapped: true
  collect_lua_garbage: false
  sync_timeout: 1
  rebalancer_max_sending: 1
  sched_ref_quota: 300
  rebalancer_disbalance_threshold: 1
  bucket_count: 30000
  sched_move_quota: 1

См. также настройку времени ожидания сетевых вызовов при шардировании.

Параметры авторизации

Авторизация настраивается при помощи секций auth/auth_external, ldap.

Секция auth позволяет настроить существующую систему авторизации аналогично тому, как это делается в Tarantool Cartridge. Вместо этого можно в секции auth_external указать путь к файлу с Lua-кодом, где задана нестандартная логика для авторизации входящих запросов.

Кроме того, ниже рассматривается секция pepper, где можно задать переменную, с помощью которой будут хешироваться пароли.

Секция auth_external

В этой секции можно указать путь к файлу с Lua-кодом, где пользователь может самостоятельно задать логику для авторизации входящих запросов. Код должен вернуть таблицу с параметром auth, в котором лежит функция для проверки входящих запросов в формате HTTP. Функция вернет либо nil, если доступ запрещен, либо объект, содержащий аутентификационную информацию.

Пример. Укажем путь к файлу auth.lua с логикой для авторизации входящих запросов:

auth_external: {__file: auth.lua}

Содержание auth.lua определяется пользователем самостоятельно. Например, в файле может быть указана такая логика обработки:

-- Функция авторизует пользователя по HTTP-заголовку

local function auth(request)
local header = request.headers['custom_token']
if header == nil then
    return nil, "no header"
end

if header == 'error-injection' then
    error('error-injection')
end

if header == 'invalid-answer' then
    return 'invalid-answer'
end

if header == 'invalid-decision' then
    return {
        decision = 'invalid-decision',
    }
end

if header == 'invalid-token' then
    return {
        decision = 'reject',
        reason = 'invalid token',
    }
end

if header == 'fallback-token' then
    return {
        decision = 'fallback',
    }
end

if header == 'custom-response' then
    return {
        decision = 'reject',
        status_code = 418,
        reason = 'Hello, world!',
        headers = {
            ['custom'] = 'header',
        }
    }
end

return {
    decision = 'accept',
    account = {
        is_user = true,
        email = 'example@tarantool.org',
        role_id = 1,
    },
}
end

return {
    auth = auth,
}

Секция ldap

В этой секции указываются параметры авторизации внешних пользователей и систем через LDAP:

  • domain – доменное имя, которое используется в доменном логине пользователя (user@domain).

  • organizational_units – названия организационных подразделений или групп пользователей. Параметр опциональный и будет пропущен, если для него не задано значение.

  • hosts – адрес подключения к серверу LDAP.

  • use_active_directory – параметр, определяющий использование Active Directory (служба каталогов Microsoft). Значение по умолчанию: false.

    Если установлено значение true, используйте адрес электронной почты для входа в систему и атрибут Active Directory userprincipalname=email в качестве фильтра, где email – адрес электронной почты пользователя. Часть с именем пользователя в email будет распознана одинаково независимо от регистра (aBc@mail.ru и AbC@mail.ru – это один и тот же пользователь).

  • use_tls – параметр, определяющий использование TLS. Значение по умолчанию: false.

  • search_timeout – время ожидания ответа от сервера LDAP в секундах. Значение по умолчанию: 2.

  • options – настройки LDAP. Параметр опционален. Доступные настройки:

    • LDAP_OPT_DEBUG_LEVEL – уровень отладки клиентской библиотеки.

    • LDAP_OPT_PROTOCOL_VERSION – версия протокола LDAP.

    • LDAP_OPT_X_TLS_CACERTDIR– путь к директории с корневыми сертификатами.

    • LDAP_OPT_X_TLS_CACERTFILE – полный путь к файлу корневого сертификата.

    • LDAP_OPT_X_TLS_NEWCTX – создание нового контекста библиотеки TLS.

    • LDAP_OPT_X_TLS_REQUIRE_CERT – стратегия проверки сертификатов. Принимает целое значение от 0 до 4, где:

      • 0 – LDAP_OPT_X_TLS_NEVER,

      • 1 – LDAP_OPT_X_TLS_HARD,

      • 2 – LDAP_OPT_X_TLS_DEMAND,

      • 3 – LDAP_OPT_X_TLS_ALLOW,

      • 4 – LDAP_OPT_X_TLS_TRY.

    Подробное описание этих настроек LDAP приведено на странице ldap_get_option().

  • roles – описание ролей, которые будут назначаться пользователю в зависимости от групп LDAP, в которых он состоит. Вложенные параметры:

    • role – роль, назначенная пользователю или внешнему приложению для авторизованного доступа и действий в системе (читать подробнее про роли).

    • domain_groups – LDAP-группы, которые соответствуют указанной выше роли. В параметрах групп указываются:

      • cn (common name) – общее имя.

      • ou (organization unit name) – организационное подразделение или группа пользователей.

      • dc (domain component) – компонент домена.

    Если пользователь состоит сразу в нескольких LDAP-группах, он получает разрешения на действия из всех ролей, назначенных для этих групп.

Пример

В примере заданы настройки для:

  • LDAP-группы tarantool с ролью admin;

  • LDAP-группы svcaccts с ролью supervisor.

Для них указаны основные параметры авторизации, отключен Active Directory и отключен TLS:

ldap:
  - domain: 'my.domain.ru'
    organizational_units: ['tarantool']
    hosts:
      - server.my.domain.ru:389
    use_tls: false
    use_active_directory: false
    search_timeout: 2
    options:
      - LDAP_OPT_DEBUG_LEVEL: 3
    roles:
      - domain_groups:
          - 'cn=tarantool,ou=groups,dc=my,dc=domain,dc=ru'
        role: 'admin'

  - domain: 'my.domain.ru'
    organizational_units: ['svcaccts']
    hosts:
      - server.my.domain.ru:389
    use_tls: false
    use_active_directory: false
    search_timeout: 2
    roles:
      - domain_groups:
          - 'cn=svcaccts,ou=groups,dc=my,dc=domain,dc=ru'
        role: 'supervisor'

Секция pepper

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

Пример:

pepper: 2d60ec7f-e9f0-4018-b354-c54907b9423d

Настройка времени ожидания сетевых вызовов при шардировании

vshard-timeout – отдельная секция, где указывается время, в течение которого модуль vshard ожидает сетевые запросы. Это время в секундах передается в функциях vshard.router.callro() и vshard.router.callrw().

Значение по умолчанию – 2 секунды:

vshard-timeout: 2

Конфигурация бизнес-логики

В конфигурацию бизнес-логики можно добавить параметры модели данных, мониторинга, сервисов GraphQL, подсистем и коннекторов.

Note

Для простоты эксплуатации рекомендуется хранить различные параметры конфигурации в разных YAML-файлах.

Параметры модели данных

Настроить модель данных можно, используя следующие секции:

Секция types

В этой секции настраивается модель данных – указываются типы объектов, которые будут сохраняться в TDG. В качестве языка описания модели данных TDG используется Apache Avro Schema.

По умолчанию указывается путь к файлу, где определена модель данных:

types: {__file: model.avsc}

Содержание model.avcs определяется пользователем самостоятельно. Например, в файле может быть указана такая модель данных:

[
    {
        "name": "Country",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
        { "name": "city", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country" }
        ]
    },
    {
        "name": "City",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population"
        ]
    }
]

Секция versioning

В этой секции настраивается версионирование – сохранение разных версий объектов для последующего извлечения, просмотра и восстановления объектов.

По умолчанию версионирование отключено. Чтобы его включить, укажите enabled: true для нужного типа объекта.

Пример. Включим версионирование для объекта типа Tourists.

versioning:
  - type: Tourists
    enabled: true

Вы также можете настроить следующие параметры:

  • keep_version_count – количество хранимых версий. По умолчанию: 5. Минимальное значение: 1. Если вы не хотите ограничивать количество хранимых версий, удалите этот параметр. Если параметр задан, старые версии будут удаляться. Только новые версии, количество которых меньше или равно заданному значению параметра, будут сохранены. Каждый раз, когда добавляется новая версия, система проводит проверку и удаляет старые версии при необходимости.

  • delay_sec – интервал в секундах, через который запускается новая проверка устаревших объектов. Найденные устаревшие объекты удаляются. Минимальное значение: 1.

  • lifetime_hours – время жизни версии в часах, также может быть задано в днях (lifetime_days) или годах (lifetime_years). По умолчанию не задано, поэтому версии хранятся неограниченное время. Минимальное значение: 1. Если параметр задан, версии, существующие дольше заданного значения параметра, будут удалены.

  • strategy – стратегия удаления предыдущих версий из хранилища (архивирование). Варианты стратегии:

    • постоянное удаление версий (permanent);

    • хранение на диске с расчетом на то, что данные будут запрашиваться редко (cold_storage).

    По умолчанию: permanent.

  • schedule – расписание в формате cron, по которому проверяется наличие изменений в объектах.

  • dir – директория, где в JSON-файлах хранятся прежние версии объектов.

  • file_size_threshold – предельный размер JSON-файла, в котором хранятся прежние версии объектов. Когда предельное значение достигнуто, версии начинают сохраняться в новый файл.

Пример

Укажем параметры версионирования для типов объектов Country и City.

Country: хранить 7 версий, ограничить время жизни 4 часами, запускать проверку через 1 секунду, использовать холодное хранение (хранить на диске).

City: хранить 3 версии, ограничить время жизни 2 днями, запускать проверку через 1 секунду, архивировать версии в файл.

versioning:
  - type: Country
    enabled: true
    keep_version_count: 7
    lifetime_hours: 4
    delay_sec: 1
    strategy: cold_storage
    schedule: "0 0 0 */1"
  - type: City
    enabled: true
    keep_version_count: 3
    lifetime_days: 2
    delay_sec: 1
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 100001

Секция archivation

В этой секции настраивается архивация – выгрузка объектов из TDG и сохранение их отдельно на жестком диске в файлах формата .jsonl (формат имени – YYYY-MM-DDTHH:MM:SS.jsonl). Объекты записываются в файл построчно: один объект – одна строка вида {"TypeName": {... data ...}}, где TypeName – тип сохраняемого объекта.

Определенные типы объектов могут поступать в TDG в большом количестве, но при этом иметь короткое время активного использования, после чего потребность в обращении к ним возникает редко. Именно для таких объектов полезно настраивать архивацию.

По умолчанию архивация не настроена. Чтобы ее настроить, задайте в секции archivation следующие параметры:

  • type – тип объекта.

  • lifetime_days – время жизни объекта в TDG, указывается в днях. Объекты старше этой величины архивируется.

  • schedule – расписание запуска задачи на архивацию в формате cron с поддержкой секунд.

  • dir – директория для хранения файлов с архивными данными.

  • file_size_threshold – максимальный размер файла с архивными данными, указывается в байтах. При достижении этого размера запись архивируемых данных начинается в новый файл. По умолчанию: 104857600 (100 Мб).

Пример

Укажем настройки архивации для типа объекта Quotation, чтобы повысить производительность TDG за счёт архивирования редко используемых цитат.

archivation:
  - type: Quotation
    lifetime_days: 7
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 104857600

Секция welcome-message

В этой секции настраивается текст приветственного сообщения, которое будет появляться при входе в систему. Ограничения на количество символов в сообщении нет.

Полезно изменять секцию welcome-message, например, если вы хотите облегчить работу с TDG новым сотрудникам, дописав им полезные подсказки, или решили оставить важную информацию для опытных коллег.

Пример

Изменим текст приветственного сообщения, чтобы сообщить коллегам о планируемом обновлении сервиса.

welcome-message: |
  Коллеги, сервис может быть недоступен в четверг с 12.00 до 14.00 в связи с плановым обновлением.

Секция tdg-version

В этой секции настраивается проверка версии TDG на совместимость при применении конфигурации. Для параметра указывается условие проверки, и с ним сравнивается текущая версия TDG. Если условие не выполняется, применение конфигурации останавливается.

Примеры

Проверим версию 1.6.0 на совместимость.

tdg-version: "== 1.6.0"

В примере:

  • ==, <=, <, >, >= – оператор.

  • 1.7.0 – версия major.minor.patch (семантическое версионирование) или scm-<число>.

Note

Чтобы избежать возможных ошибок при чтении, всегда заключайте выражение из оператора и версии в кавычки. Обязательного помещения в кавычки не требует только выражение с ==.

Синтаксис YAML позволяет указывать многостроковые значения с помощью операторов >, <, >=, >= в первой строке. Чтобы задать версию больше, чем выбранное значение, нужно поместить оператор > и версию в кавычки.

Пример неправильного заполнения, когда версия будет прочитана как 1.6.0:

tdg-version: > 1.6.0

Пример правильного заполнения, когда версия будет прочитана как больше чем 1.6.0:

tdg-version: "> 1.6.0"

Параметры мониторинга

Настроить параметры мониторинга и изменить логику обработки объектов, при необходимости передавая функциональную нагрузку на резервный компонент, можно при помощи секций jobs, tracing, repair_queue, maintenance и metrics.

Секция jobs

В этой секции при помощи параметра max_jobs_in_parallel настраивается максимальное количество отложенных задач (jobs), которые могут выполняться одновременно. Если вы используете отложенные задачи, рекомендуется настроить данную секцию и ограничить количество отложенных задач, чтобы сохранить высокую производительность TDG.

При достижении установленного ограничения отложенные задачи сверх лимита будут поставлены в очередь и будут выполняться последовательно.

Значение по умолчанию – 50:

jobs:
  max_jobs_in_parallel: 50

Секция tracing

В этой секции настраиваются параметры для взаимодействия с системой трассировки, которая позволяет анализировать производительность выполнения кода TDG:

  • lbase_url – адрес API-ресурса (endpoint), куда отсылаются собранные для анализа участки кода (spans).

  • lapi_method – тип HTTP-запроса для обращения к base_url. Для систем трассировки, поддерживающих протокол OpenZipkin, используется POST.

  • lreport_interval – интервал в секундах, через который в систему трассировки отсылаются накопленные участки кода.

  • lspans_limit – максимальное количество участков кода, которое может накапливаться в буфере перед отправкой в систему трассировки.

Пример

Укажем локальный адрес для отправки участков кода с максимальным размером буфера = 100.

tracing:
  base_url: localhost:8080/api/v2/spans
  api_method: POST
  report_interval: 0
  spans_limit: 100

Секция repair_queue

При стандартном поведении TDG, когда объект поступает в систему на обработку, он сразу помещается в ремонтную очередь. Если объект удалось обработать и сохранить, он удаляется из ремонтной очереди. В случае ошибки объекты остаются в ремонтной очереди, и администратор имеет возможность просматривать их, а после устранения источника проблемы – отправлять на повторную обработку.

В этой секции можно изменить порядок обработки объектов, которые попали в ремонтную очередь.

Пример. Настроим репликацию во внешнюю систему для всех объектов ремонтной очереди, которые получили специальное значение ключа __unclassified__, используемое для определения неклассифицированных объектов. При попадании такого объекта в ремонтную очередь, согласно настройкам postprocess_with_routing_key: unclassified, объекту присваивается другой ключ маршрутизации unclassified, и с этим ключом он направляется в подсистему output_processor. Дальнейшая обработка объекта будет выполняться в соответствии с параметрами секции output_processor.

repair_queue:
  on_object_added:
    __unclassified__:
        postprocess_with_routing_key: unclassified

Секция maintenance

В этой секции устанавливаются следующие параметры, сигнализирующие об ошибках системы:

  • clock_delta_threshold_sec – порог рассинхронизации истинного времени (CLOCK_REALTIME) на разных экземплярах Tarantool. Значение указывается в секундах.

  • fragmentation_threshold_critical – порог, при превышении которого система покажет критическое сообщение о фрагментации данных. Принимает относительные значения от 0 до 1.

  • fragmentation_threshold_warning – порог, при превышении которого система покажет предупреждение о фрагментации данных. Принимает относительные значения от 0 до 1.

Если тот или иной параметр в секции maintenance выходит за указанные рамки, об этом появляется сообщение в веб-интерфейсе TDG на вкладке Cluster.

Значения по умолчанию:

maintenance:
  clock_delta_threshold_sec: 5
  fragmentation_threshold_critical: 0.9
  fragmentation_threshold_warning: 0.6

Секция metrics

В этой секции настраиваются параметры, задающие формат и возможность просмотра метрик по нескольким адресам ресурсов (endpoints) для мониторинга работы TDG. Эти параметры указываются внутри подраздела export:

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/path_for_prometheus_metrics'
      format: 'prometheus'
    - path: '/health'
      format: 'health'

Параметры:

  • path – путь, по которому будут доступны метрики.

  • format – формат, в котором будут доступны метрики. Может принимать следующие значения:

    • 'json'

    • 'prometheus'

    • 'health' – информация о текущем состоянии экземпляра. Если состояние экземпляра удовлетворительное (healthy), ответом на запрос будет HTTP-код 200, если нет – HTTP-код 500.

При необходимости можно добавить несколько адресов ресурсов одного формата по разным путям. Это полезно, когда есть несколько систем хранения метрик.

По умолчанию значения метрик в формате Prometheus доступны по адресу http://<IP_адрес_экземпляра>/metrics.

После заполнения секции metrics в файле конфигурации метрики по умолчанию в формате Prometheus по адресу http://<IP_адрес_экземпляра>/metrics перестанут быть доступными. Чтобы сделать их доступными, также укажите path: '/metrics' и format: 'prometheus' в секции metrics.

Параметры сервисов GraphQL

Настроить сервисы GraphQL можно, используя следующие секции:

Секция services

В этой секции настраивается конфигурация сервисов.

Для примера настроим сервис получения цены со следующими параметрами:

  • get_price – имя сервиса. Оно всегда должно начинаться с латинской буквы и может содержать латинские буквы, цифры и символ подчеркивания (_).

  • type – тип запроса GraphQL для вызова сервиса: query или mutation. Если тип – query, параметр можно не указывать.

  • doc – произвольное описание сервиса.

  • function – ссылка на Lua-файл с сервис-функцией.

  • return_type – тип данных, который возвращается в результате выполнения сервиса.

  • args – описание аргументов, передаваемых на вход при выполнении сервиса, в формате имя_аргумента: тип_данных.

services:
  get_price:
    doc: "Get the item price by ID"
    function: {__file: get_price_by_id.lua}
    return_type: ItemPrice
    args:
      item_id: string

Секция hard-limits

В этой секции устанавливаются ограничения для запросов GraphQL. Такие настройки для планировщика запросов позволяют контролировать нагрузку на кластер и предотвращают полное сканирование спейса в TDG. Также данные ограничения учитываются при работе функций Repository API и Sandbox API.

Параметры:

  • scanned – максимальное количество кортежей, которое TDG будет сканировать при выполнении запроса. Значение по умолчанию: 2000.

    Note

    Начиная с версии 2.7.0, вместо ограничения scanned для hard-limits TDG использует механизм fiber.slice.

  • returned – максимальное количество кортежей, которое может вернуть одно хранилище. Значение по умолчанию: 100. Например, returned = 100, а в настройках пагинации параметр first равен 5. Тогда запрос вернет 5 кортежей, а остальной массив данных можно обойти с помощью параметра after.

Настройка данных параметров возможна при конфигурации системы или с помощью специальных запросов и мутаций GraphQL. Пример настроек подраздела hard-limits в файле конфигурации:

hard-limits:
  scanned: 2000
  returned: 100

Во встроенном клиенте GraphiQL в веб-интерфейсе TDG для установки данных ограничений используется схема admin. Пример запроса:

mutation {
  config {
    hard_limits(scanned:5000 returned:400) {
      scanned
      returned
    }
  }
}

Данные настройки превентивно требуют качественного написания запросов. Если одно из ограничений превышается, выполнение запроса прекращается и возвращается ошибка. Всего существует два вида ошибок – для параметров scanned и returned соответственно.

Кроме того, ошибка возникает, если:

  • для параметра returned верно first > returned;

  • для параметра scanned верно, что количество записей больше значения scanned, при этом first > scanned.

Пример ошибки: Hard limit for scan rows reached 2000 for space \"storage_MusicBand\"

Такая ошибка при сканировании означает, что при поиске по индексу в спейсе MusicBand было просмотрено более 2000 записей. Для устранения ошибки необходимо добавить индекс, который сократит выборку для данного запроса.

Note

Появление данной ошибки сканирования также возможно, когда используются функции repository.find(), repository.update() и repository.delete() из раздела Repository API.

Ошибка может возникнуть

  • независимо от значения параметра first, если не используется индекс.

    Например, есть запрос repository.find("ModelName", {{'key', '==', 'a'}}. Значение параметра scanned = 5000. Первые 5000 записей при этом не подходят по запросу. Такой запрос вызовет ошибку.

    Решение: добавить индекс – "indexes": [..., "key"];

  • если в запросе используются два или больше фильтров.

    Например, есть запрос с несколькими фильтрами, где scanned = 5000. Под первый фильтр подходит 10000 записей. При этом первые 5000 записей не подходят под второй фильтр. Такой запрос вызовет ошибку.

Секция force_yield_limits

В этой секции устанавливается ограничение на количество сканирований записей в спейсе. При достижении порога управление потоком переходит от текущего файбера к другому (выполняется yield).

Актуально при выполнении map_reduce, чтобы избежать зависаний на экземплярах с ролью storage. Также учитывается при работе функций Repository API.

Значение по умолчанию – 1000:

force_yield_limits: 1000

Секция graphql_query_cache_size

В этой секции устанавливается размер кэша для уникальных GraphQL-запросов.

Значение по умолчанию – 3000:

graphql_query_cache_size: 3000

Секция test-soap-data

В этой секции можно задать текст, который будет по умолчанию отображаться на вкладке Test в веб-интерфейсе TDG. Это может также быть путь к файлу, содержащему структуру тестового объекта в формате XML или JSON для имитации входящего запроса.

Пример. Укажем путь к файлу.

test-soap-data: {__file: test_object.json}

Параметры подсистем

Каждая подсистема – это набор определенных функциональных возможностей, входящих в ту или иную кластерную роль.

Ниже рассматриваются параметры, связанные со следующими подсистемами:

input_processor

В этой секции настраиваются параметры процессора ввода данных:

  • handlers – определение обработчиков входящего запроса.

    Если обработчик не задан, объект обрабатывается в соответствии со значением, указанным в секции input_processor: routing.

    Вложенные параметры:

    • key: ключ маршрутизации, по которому определяется, как следует обработать объект.

    • function: функция, которую следует применить к объекту.

  • routing – маршрутизация объекта в определенный пайплайн обработки.

    Вложенные параметры:

    • key: ключ маршрутизации.

    • output: система, куда следует направить объект.

  • storage – настройки сохранения объекта на экземплярах роли storage.

    Вложенные параметры:

    • key: ключ маршрутизации.

    • type (необязательно): тип бизнес-объекта (агрегата), куда следует направить объект.

Пример:

input_processor:
  handlers:
    - key: input_processor
      function: handler.call
  routing:
    - key: input_processor
      output: to_input_processor
  storage:
    - key: estate_key

output_processor

В этой секции задается логика обработки объектов, которые будут реплицироваться во внешние системы. Выполняется после успешного сохранения объектов на экземплярах с ролью storage.

Для каждого ключа маршрутизации, присвоенного объекту, определяются следующие подразделы:

  • handlers – обработчики входящих запросов:

    • function: имя функции, которую следует применить к объекту.

    • outputs: параметры, с которым объект будет отправлен во внешнюю систему.

Пример:

output_processor:
  estate_key:
    handlers:
      - function: output.estate_output.call
        outputs:
          - dummy

account_manager

В этой секции настраивается подсистема account_manager, которая обеспечивает работу ролевой модели доступа и связанные с ней функций безопасности.

Параметры:

  • only_one_time_passwords – флаг (true/false). По умолчанию: false. Если указано значение true, нет возможности вручную задавать пароль при создании или импорте профиля пользователя. Вместо этого TDG автоматически генерирует одноразовый пароль и высылает его на адрес электронной почты пользователя. Для отсылки пароля также необходимо иметь работающий сервер SMTP, описание его конфигурации в секции connector (output: type: smtp) и указание на этот output в секции account_manager. Опционально можно указать заголовок письма, в котором высылается одноразовый пароль (options: subject:). Если указано значение only_one_time_passwords: false, то пароль будет генерироваться и отправляться пользователю, даже если поле Password при создании профиля пользователя оставлено пустым.

  • password_change_timeout_seconds – минимальное время, которое должно пройти до следующей смены пароля. Указывается в секундах. Действует только в отношении смены собственного пароля.

  • block_after_n_failed_attempts – количество неудачных попыток входа в систему, после которых пользователь будет заблокирован (получит статус blocked).

  • ban_inactive_more_seconds – максимальное время, в течение которого пользователь может быть неактивен в системе. Указывается в секундах. По истечении этого времени пользователь будет заблокирован. Максимально возможное значение параметра – 45 дней. Если значение превышает 45 дней или параметр не задан, устанавливается значение по умолчанию, равное 45 дням.

  • password_policy – настройки политики в отношении паролей. Эти настройки также можно задать через веб-интерфейс TDG.

  • min_length – минимально допустимая длина пароля. По умолчанию: 8.

  • include – флаги (true/false), определяющие, какие категории символов должны обязательно входить в пароль.

    Допустимые значения:

    • lower – латинские буквы в нижнем регистре. По умолчанию: true.

    • upper – латинские буквы в верхнем регистре. По умолчанию: true.

    • digits – цифры от 0 до 9 включительно. По умолчанию: true.

    • symbols– дополнительные символы !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~. По умолчанию: false.

Пример. Настроим возможность получать одноразовый пароль по электронной почте.

account_manager:
  only_one_time_passwords: true
  output:
    name: to_smtp
    options:
      subject: "Registration"
  password_change_timeout_seconds: 10
  block_after_n_failed_attempts: 5
  ban_inactive_more_seconds: 86400
  password_policy:
    min_length: 8
    include:
      lower: true
      upper: true
      digits: true
      symbols: false

notifier

В этой секции настраивается подсистема notifier для отправки уведомлений:

  • mail_server – секция настроек сервера SMTP, который используется для отправки уведомлений при попадании объекта в ремонтную очередь. Данные параметры также можно задать через веб-интерфейс TDG.

    Вложенные параметры:

    • url – URL сервера SMTP.

    • from – имя отправителя, которое будет показываться в поле «From» при получении уведомления.

    • username – имя пользователя сервера SMTP.

    • password – пароль пользователя сервера SMTP.

    • timeout – тайм-аут запроса к серверу SMTP. Указывается в секундах.

    • skip_verify_host – флаг (true/false): пропустить проверку хоста по протоколу TLS.

  • users – секция, где задаются данные подписчиков (subscribers), которые будут получать уведомления. Подписчиков также можно создать через веб-интерфейс TDG.

    Вложенные параметры:

    • id – идентификатор подписчика.

    • name – имя подписчика.

    • addr – e-mail подписчика.

Пример:

notifier:
  mail_server:
    url: 127.0.0.1:2525
    from: TDG_repair_queue
    username: user
    password: passpass
    timeout: 5
    skip_verify_host: true
  users:
    - id: 1
      name: Petrov
      addr: petrov@mailserver.com

gc

В этой секции настраивается подсистема garbage_collector, которая принудительно запускает сборку мусора в Lua. Подсистема включается неявно на всех экземплярах:

  • forced – включение (true) или отключение (false) принудительной сборки мусора. По умолчанию: false.

  • period_sec – интервал, через который происходит запуск нового цикла сборки мусора. Указывается в секундах.

  • steps – размер шага сборщика мусора.

Пример. Настроим принудительную сборку мусора так, чтобы она происходила каждые три секунды.

gc:
  forced: true
  period_sec: 3
  steps: 20

sequence_generator

В этой секции указываются настройки, используемые при генерации последовательностей уникальных чисел:

  • starts_with – число, с которого начинается последовательность. По умолчанию: 1.

  • range_width – диапазон последовательности. По умолчанию: 100.

Пример. Зададим генерацию последовательности уникальных чисел с 5 при диапазоне 15.

sequence_generator:
  starts_with: 5
  range_width: 15

logger

В этой секции определяются параметры подсистемы логирования logger. Все параметры обязательные:

  • rotate_log – флаг (true/false), осуществлять ли ротацию лога.

  • max_msg_in_log – максимальное количество сообщений, сохраняемых в логе.

  • max_log_size – максимальный размер файла лога, в байтах.

  • delete_by_n_msg – количество одновременно удаляемых сообщений при ротации лога. При превышении значений параметров max_msg_in_log или max_msg_log_size наиболее старые n сообщений в логе удаляются за раз, что повышает производительность по сравнению с режимом, когда старые сообщения удаляются по одному.

logger:
  rotate_log: true
  max_msg_in_log: 500000
  max_log_size: 10485760
  delete_by_n_msg: 1000

tasks

В этом разделе определяется, какие задачи и в какое время будут запускаться в системе.

Пример:

tasks:
  task_1:
    kind: single_shot
    function: single_task
    keep: 5
  task_2:
    kind: continuous
    function: long_task
    pause_sec: 10
    run_as:
      user: username
  task_3:
    kind: periodical
    function: long_task
    schedule: "0 */5 * * * *"
    run_as:
      user: username

В этом примере:

  • task_N – имя задачи.

  • kind – вид задачи: single_shot (однократная), continuous (постоянная) или periodical (периодическая).

  • function – функция, определяющая, что именно делается в рамках задачи.

  • keep – количество завершенных экземпляров задачи, которые сохраняются в истории. По умолчанию: 10.

  • pause_sec – пауза в выполнении задачи вида continuous. Указывается в секундах.

  • schedule – расписание выполнения для задач вида periodical. Задается в формате cron c расширенным синтаксисом, в котором минимальной величиной является секунда:

    * * * * * *
| | | | | |
| | | | | ----- День недели (0-6) (Воскресенье = 0)
| | | | ------- Месяц (1-12)
| | | --------- День (1-31)
| | ----------- Час (0-23)
| ------------- Минута (0-59)
--------------- Секунда (0-59)

    Например, schedule: "0 */5 * * * *" означает, что задача будет запускаться периодически каждые 5 минут.

  • run_as – пользователь, от имени которого выполняется задача. Применяется только для задач видов continuous или periodical. Указанный пользователь должен иметь достаточно прав для выполнения действий задачи. Если режим обязательной аутентификации выключен, параметр run_as не обязателен. Внутри блока run_as передается параметр:

    • user – имя пользователя.

task_runner

В этой секции настраивается running_count_threshold – порог количества функций, выполняемых в рамках задач (tasks) и отложенных задач (jobs).

Значение по умолчанию:

task_runner:
  running_count_threshold: 100

audit_log

В этой секции задаются параметры журнала аудита. Все параметры опциональные:

  • enabled – включить (true) или выключить (false) запись событий в журнал аудита. По умолчанию: false.

  • severity – уровень важности событий, которые будут записываться в журнал аудита. Возможные значения по возрастанию важности: VERBOSE, INFO, WARNING, ALARM. По умолчанию: INFO.

    При указании определенного уровня в журнал аудита будут записываться события этого уровня и выше. Например, если задано INFO, будут записываться события, соответствующие уровням INFO, WARNING и ALARM.

  • remove_older_than_n_hours – максимальное время хранения записей в журнале аудита. Указывается в часах. Записи старше указанного времени удаляются.

Пример. Включим запись событий уровня INFO и более высоких.

audit_log:
  enabled: true
  severity: INFO
  remove_older_than_n_hours: 5

По умолчанию журнал аудита выключен:

audit_log:
  enabled: false

Параметры коннекторов

В этой секции настраиваются параметры коннекторов TDG:

Настройка input

input – параметры коннекторов для получения и первоначальной обработки (парсинга) входящих запросов. У всех типов коннекторов есть общие параметры:

  • name – имя коннектора (произвольное).

  • type – тип коннектора. Поддерживаемые типы:

    • http – для запросов в формате JSON по HTTP;

    • soap – для запросов в формате XML (SOAP) по HTTP;

    • kafka – для интеграции с шиной данных Apache Kafka;

    • tarantool_protocol – для запросов через iproto;

    • file – для загрузки данных из файлов.

  • is_async – режим работы TDG в качестве producer:

    • true (по умолчанию) – асинхронный режим: подтверждение о доставке сообщения отправляется сразу после того, как сообщение добавлено в очередь на отправку.

    • false – синхронный режим: подтверждение о доставке сообщения отправляется только после того, как сообщение было доставлено.

Помимо этих параметров, у некоторых типов коннекторов есть параметры, специфические только для них.

Особые параметры коннектора типа soap

  • wsdl – схема WSDL, описывающая структуру входящего XML.

  • success_response_body – шаблон ответа в случае успешной обработки запроса.

  • error_response_body – шаблон ответа в случае ошибки.

  • handlers – обработчики входящего запроса.

Note

Шаблоны ответа (параметры success_response_body и error_response_body) опциональны. Пользователь может задать шаблоны в нужном ему формате, соответствующем системе, в которую отправляется ответ. TDG ограничений на формат не накладывает. В шаблоне error_response_body возможно использовать один спецификатор форматирования %s, чтобы передать в тело ответа текст ошибки.

Пример. Укажем коннектор типа soap.

connector:
  input:
    - name: soap
      type: soap
      wsdl: {__file: Connect.wsdl}
      success_response_body: {__file: success_response_body.xml}
      error_response_body: {__file: error_response_body.xml}
      handlers:
          function: connect_input_handle

Особые параметры коннектора типа kafka

  • brokers – URL-адреса брокеров сообщений.

  • topics – топики (topics) в терминологии Kafka.

  • group_id – идентификатор группы подписчиков.

  • token_name – имя токена приложения. Необходимо сначала сгенерировать токен приложения в системе, а затем указать имя токена (name) в качестве значения параметра. Токен будет использоваться для авторизации при обработке входящих сообщений, которые коннектор забирает из Apache Kafka. Поскольку формат сообщений Kafka не дает возможности передать токен в самом сообщении, токен указывается в конфигурации коннектора.

  • enable_debug – режим отладки для Kafka:

    • true – режим отладки включен. Значение true добавляет параметр debug: "all" в настройки соединения для Kafka. Если в логах не требуются все атрибуты, установите необходимое значение параметра debug в секции options.

    • false (по умолчанию) – опция отключена.

  • options – опции библиотеки librdkafka:

    • enable.auto.offset.store – значение true задает автоматическое обновление параметра смещения (autocommit). Значение по умолчанию: false.

    • enable.partition.eof – значение true не выводит ошибку RD_KAFKA_RESP_ERR__PARTITION_EOF, если consumer доходит до конца сегмента. Значение по умолчанию: false.

    • auto.offset.reset – смещение, используемое при отсутствии другого значения в памяти. Значение по умолчанию: earliest.

    • statistics.interval.ms (integer) – интервал обновления метрик в миллисекундах. Значение по умолчанию: 15000. Диапазон доступных значений: 0–86400000. Значение 0 отключает сбор статистики.

    • security.protocol – протокол для связи с брокерами. Возможные значения: plaintext, ssl, sasl_plaintext, sasl_ssl. Значение по умолчанию: plaintext.

    • debug – выбор режима отладки. Возможные значения: generic, metadata, topic, cgrp, fetch, consumer, all. Значение по умолчанию: all.

  • workers_count – количество читателей сообщений (workers), которые будут работать на коннекторе. Значение по умолчанию: 10. Параметр может быть полезен для случая, когда нужно гарантированно сохранить порядок чтения входящих сообщений. Если читателей сообщений несколько, то будет идти параллельная обработка нескольких сообщений сразу, и их порядок может быть нарушен. Чтобы гарантировать сохранение порядка, необходимо в кластере оставить один connector и один input_processor и задать значение workers_count: 1.

  • logger – выбор режима для журнала событий:

    • stderr (по умолчанию) – в логи TDG выводятся только сообщения об ошибках.

    • tdg – в TDG отправляются все логи Kafka, включая сообщения об ошибках.

Для коннектора типа kafka в конфигурации можно задать более одного входящего коннектора.

Note

При подключении к Kafka в логах TDG выводятся input-параметры, с которым был создан consumer Kafka. В логах указаны значения для всех опций библиотеки librdkafka, в том числе выставленные по умолчанию. Отключить вывод логов нельзя.

Пример вывода:

tdg2                | 2023-03-02 16:17:19.810 [1] main/304/main I> [dcb31ae4-ca99-4b1c-995f-a0dd05194fa9] Kafka consumer for "kafka" input configuration: ---
tdg2                | ssl.engine.id: dynamic
tdg2                | socket.blocking.max.ms: '1000'
tdg2                | message.max.bytes: '1000000'
tdg2                | connections.max.idle.ms: '0'
tdg2                | enable_sasl_queue: 'false'
tdg2                | batch.size: '1000000'
...

Пример. Укажем коннектор типа kafka.

connector:
  input:
  - name: kafka-1
    type: kafka
    brokers:
      - localhost:9092
    topics:
      - orders-1
      - items-1
    group_id: kafka
    token_name: kafka_token
    function: connect_input_handle
    workers_count: 1

  - name: kafka-2
    type: kafka
    brokers:
      - localhost:9092
    topics:
      - orders-2
      - items-2
    group_id: kafka
    token_name: kafka_token
    function: connect_input_handle
    workers_count: 1

Особые параметры коннектора типа file

  • format – формат файла для чтения данных: csv или jsonl.

  • filename – имя файла для чтения данных.

  • workdir – директория для поиска файла.

Пример. Укажем коннектор типа file.

connector:
  input:
    - name: json_importer
      type: file
      format: jsonl
      filename: data.json
      routing_key: input_key
      workdir: .

Настройка output

output – параметры коннекторов для отправки исходящих запросов. У всех типов коннекторов есть общие параметры:

  • name – имя коннектора (произвольное).

  • type – тип коннектора. Поддерживаемые типы:

    • input_processor – для отправки объекта в подсистему input_processor;

    • http – для отправки объекта в формате JSON во внешнюю систему по HTTP;

    • soap – для отправки объекта в формате XML (SOAP) во внешнюю систему по HTTP;

    • kafka – для интеграции с шиной данных Apache Kafka;

    • smtp – для отправки запросов через SMTP-сервер;

    • dummy – для игнорирования объектов: пришедший объект никуда не отправляется.

  • headers – заголовки HTTP, которые при необходимости может установить пользователь при отправке данных во внешнюю систему.

  • is_async – режим работы TDG в качестве producer:

    • true (по умолчанию) – асинхронный режим: подтверждение о доставке сообщения отправляется сразу после того, как сообщение добавлено в очередь на отправку.

    • false – синхронный режим: подтверждение о доставке сообщения отправляется только после того, как сообщение было доставлено.

Помимо этих параметров, у некоторых типов коннекторов есть параметры, специфические только для них.

Особые параметры коннектора типа http

  • url – URL внешней системы, куда отправляется объект.

  • format – формат, в котором отправляется объект. Для коннектора типа http формат – всегда JSON.

  • options – опции параметра opts из встроенного модуля Tarantool http).

Пример. Укажем коннектор типа http.

connector:
    output:
        - name: to_external_http_service
          type: http
          url: http://localhost:8021
          format: json
          options:
            timeout: 5
            keepalive_idle: 60
            keepalive_interval: 60
            verify_host: true
            verify_peer: true
          headers:
            hello: world

Особые параметры коннектора типа soap

  • url – URL внешней системы, куда отправляется объект.

Пример. Укажем коннектор типа soap.

connector:
  output:
    - name: to_external_soap_service
      type: soap
      url: http://localhost:8020/test_soap_endpoint
      headers:
        config_header: header_for_soap

Особые параметры коннектора типа kafka

  • brokers – адреса (URL) брокеров сообщений.

  • topic – топик (topic) в терминологии Kafka.

  • format – формат, в котором отправляется сообщение в Kafka. Возможные значения: json и plain. Значение plain может применяться для случая, когда необходимо отправить в Kafka сообщение в формате XML. Значение по умолчанию: json.

  • options – опции библиотеки librdkafka:

    • queue.buffering.max.ms (integer) – задержка в миллисекундах. Используется, чтобы дождаться, пока накопятся сообщения в очереди продюсера, прежде чем будут созданы пакеты сообщений для отправки брокерам. Значение по умолчанию: 5.

    • statistics.interval.ms (integer) – интервал обновления метрик в миллисекундах. Значение по умолчанию: 15000. Диапазон доступных значений: 0–86400000. Значение 0 отключает сбор статистики.

    • debug – выбор режима отладки. Возможные значения: generic, metadata, broker, topic, msg, all. Значение по умолчанию: all.

  • logger – выбор режима для журнала событий:

    • stderr (по умолчанию) – в логи TDG выводятся только сообщения об ошибках.

    • tdg – в TDG отправляются все логи Kafka, включая сообщения об ошибках.

  • set_key – генерация ключа UUID для отправляемого сообщения. Значение по умолчанию: true. При значении false ключ в исходящем сообщении будет пустым.

Note

При подключении к Kafka в логах TDG выводятся output-параметры, с которым был создан producer Kafka. В логах указаны значения для всех опций библиотеки librdkafka, в том числе выставленные по умолчанию. Отключить вывод логов нельзя.

Пример вывода:

tdg2                | 2023-03-02 16:17:19.821 [1] main/304/main I> [dcb31ae4-ca99-4b1c-995f-a0dd05194fa9] Kafka producer for "to_kafka" output configuration: ---
tdg2                | ssl.engine.id: dynamic
tdg2                | socket.blocking.max.ms: '1000'
tdg2                | message.max.bytes: '1000000'
tdg2                | connections.max.idle.ms: '0'
tdg2                | enable_sasl_queue: 'false'
tdg2                | batch.size: '1000000'
...

Пример. Укажем коннектор типа kafka.

connector:
  output:
    - name: to_kafka
      type: kafka
      brokers:
        - localhost:9092
      topic: objects
      options:
        debug: "all"
        queue.buffering.max.ms: 1
      is_async: true

Особые параметры коннектора типа smtp

  • url – URL сервера SMTP.

  • from – имя отправителя, которое будет показываться в поле From при получении сообщения.

  • subject – тема отправляемого сообщения.

  • timeout – тайм-аут запроса к серверу SMTP. Указывается в секундах.

  • ssl_cert – путь к SSL-сертификату.

  • ssl_key – путь к приватному ключу для SSL-сертификата.

Пример. Укажем коннектор типа smtp.

connector:
  output:
    - name: to_smtp
      type: smtp
      url: localhost:2525
      from: tdg@localhost
      subject: TDG_Objects
      timeout: 5
      ssl_cert: ssl.crt
      ssl_key: ssl.pem

Настройка routing

routing – маршрутизация объекта для отправки в систему, которая определяется в поле output в зависимости от ключа маршрутизации key. Ключ маршрутизации объект получает в результате обработки функцией, указанной в input. Если в input функция не указана, объект обрабатывается функцией по умолчанию, которая превращает объект вида { "obj_type": { "field_1": 1 } } в объект вида { "field_1": 1 } и задает значение ключа маршрутизации как routing_key = obj_type.

Пример конфигурации:

connector:
  routing:
    - key: input_processor
      output: to_input_processor

    - key: external_http_service
      output: to_external_http_service

    - key: external_soap_service
      output: to_external_soap_service

Пример настройки бизнес-логики

connector:
  input:
    - name: http
      type: http
      routing_key: input_key

  output:
    - name: http_output
      type: http
      url: http://localhost:{HTTP_PORT}
      format: json
      headers:
        hello: world

    - name: invalid_http_output
      type: http
      url: http://localhost:8085
      format: json

    - name: soap_output
      type: soap
      url: http://localhost:{HTTP_PORT}
      headers:
        config_header: header_for_soap

input_processor:
  handlers:
    - key: input_key
      function: classifier.call

  storage:
    - key: test_object_1
      type: TestObject

    - key: test_object_2
      type: TestObject

    - key: test_object_3
      type: TestObject

    - key: soap_object
      type: TestObject

    - key: updatable_object
      type: UpdatableObject

    - key: object_with_entity
      type: ObjectWithEntity

    - key: bad_object
      type: BadObject

repair_queue:
  on_object_added:
    bad_object:
      postprocess_with_routing_key: bad_object_failed

    __unclassified__:
      postprocess_with_routing_key: unclassified

output_processor:
  test_object_1:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  test_object_2:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - invalid_http_output

  test_object_3:
    handlers:
      - function: bad_output_processor_handler.call
        outputs:
          - invalid_http_output

  updatable_object:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  bad_object_failed:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  object_with_entity:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  soap_object:
    handlers:
      - function: soap_processor.call
        outputs:
          - soap_output

  unclassified:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

Permissions

В Tarantool Data Grid используется основанная на ролях модель доступа к системным функциям и данным, хранящимся в системе. В этой главе подробно описываются профили доступа, которые можно назначать для создаваемых ролей, и связанные с этими профилями действия.

Access provider

Работа с настройками доступа:

Audit Logs

Работа с журналом аудита:

Cartridge Actions

Работа с Cartridge:

Checks

Работа с различными проверками:

Configuration

Работа с конфигурацией:

Data Actions Management

Управление профилями доступа:

Data Type Management

Работа с типами данных:

Jobs List

Работа с отложенными задачами:

Logs

Работа с общим журналом событий:

Notifier

Управление уведомлениями:

Output Processor List

Управление обработчиком исходящих данных (output processor):

Pages Access

Управление доступом к интерфейсу:

Repair Queue

Работа с ремонтной очередью:

Roles

Управление ролями доступа:

Services

Работа с сервисами:

Storage

Работа с хранилищем:

Tasks

Работа с задачами:

Tokens

Работа с токенами:

Users

Работа с пользователями:

Sandbox API

В TDG пользовательский код выполняется в окружении sandbox, отдельно от собственного кода TDG. sandbox – изолированная среда (песочница) для исполнения кода, где используется JIT-компилятор LuaJIT. Sandbox API включает в себя:

Кроме того, к песочнице можно подключать новые функции. Чтобы узнать больше, обратитесь к разделу Расширения.

В sandbox недоступны некоторые функции или интерфейсы (например, библиотека ffi).

Все доступные модули и функции Sandbox API в этом справочнике разделены на группы по своей функциональности:

Repository API

Sandbox API включает в себя модуль repository – интерфейс репозитория TDG. Этот модуль предоставляет функции для работы с шардированным хранилищем. Функции позволяют выполнять следующие действия с данными:

Все запросы к данным в TDG от внешних информационных систем, включая GraphQL-запросы (а также запросы, выполняемые во вкладке GraphQL), реализованы на основе функций программного интерфейса репозитория.

Доступные функции:

Функции find(), update(), update-batch(), delete и count() поддерживают порядковую нумерацию страниц (пагинацию). Для этого используются параметры:

Все функции модуля, кроме call_on_storage() и push_job(), поддерживают версионирование – получение или обработку объектов, которые предшествуют или равны определённой версии.

Фильтрация объектов

Для выбора нужных объектов запросы применяют условия-предикаты, или фильтры. Предикаты указываются в параметре filter в формате булевых выражений.

Синтаксис предикатов

В запросах предикаты (filter) записываются в виде:

{{left, comparator, right}, ...}

где:

  • left – левая часть выражения. Содержит один из двух вариантов:

    • полный путь к полю объекта (Customer.first_name);

    • название индекса (id);

  • comparator – оператор сравнения: ">", ">=", "==", "<=", "<";

  • right – правая часть выражения. Содержит один из двух вариантов:

    • полный путь к полю объекта (Customer.first_name);

    • строковое значение, численное значение, булево значение или таблица.

Если в предикате несколько условий, по умолчанию они объединяются логической операцией and (конъюнкцией).

Примеры предикатов:

{{"id", ">", 10}}
{{"id", ">", 10}, {"id", "<", 100}}
{{"Customer.first_name", "==", "Ivan"}, {"birth_year", "==", 1990}}
{{"Customer.first_name", "==", "Ivan"}, {"reg_date", "==", {1990, 04, 23}}}

Как работают фильтры

Все условия-предикаты в параметре filter проверяются по очереди, чтобы определить основной фильтр для сканирования. Остальные фильтры используются как дополнительные условия при прохождении по индексу. При выборе основного фильтра соблюдается следующий порядок:

  • Если в списке условий есть фильтр по индексу, он используется в качестве основного и задает индекс для сканирования;

  • Если в запросе нет фильтра по индексу, проверяются фильтры по полю. Если при этом какое-то поле является первым в составном индексе, используется этот составной индекс.

  • Если нет ни одного подходящего индекса, идет полное сканирование спейса по первичному ключу.

    При этом в версиях до 2.7.0 TDG использует ограничение на полное сканирование спейса (параметр scanned в секции hard-limits конфигурации). По умолчанию при выполнении запроса сканируются 2000 кортежей.

    Начиная с версии 2.7.0, вместо ограничения scanned для hard-limits TDG использует механизм fiber.slice;

  • Если условие содержит операторы like или ilike, такое условие не может задавать индекс для сканирования.

Для примера определим модель данных с двумя типами объектов: Client и Passport:

[
    {
        "name": "Passport",
        "type": "record",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "passport_series", "type": "string"},
            {"name": "passport_number", "type": "string"},
            {"name": "expired_flag", "type": "boolean"}
        ],
        "indexes": [
            "id",
            {
                "name": "passport",
                "parts": ["passport_series", "passport_number"]
            }
        ]
    },
    {
        "name": "Client",
        "type": "record",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "first_name", "type": "string"},
            {"name": "last_name", "type": "string"},
            {"name": "passports", "type": {"type": "array", "items": "Passport"}}
        ],
        "indexes": ["id"]
    }
]

Пример 1

Запрос возвращает клиентов по имени Ivan с id больше 40:

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"},
  {"id", ">", 40}})

В запросе указаны:

  • фильтр по индексу id – первичный ключ, по которому ведется сканирование;

  • фильтр по полю first_name – дополнительное условие поиска.

Пример 2

Запрос возвращает клиентов по имени Ivan, у которых первый паспорт имеет указанную серию:

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"},
  {"passports.1.passport_series", "==", "012345"}})

В запросе указаны два фильтра по полю. При этом поле passport_series – часть составного индекса passport. Сканирование идет по индексу passport.

Пример 3

Запрос возвращает клиентов, у которых истек срок действия первого паспорта:

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"}
  {"last_name", "==", "Petrov"},
  {"passports.1.expired_flag", "==", "false"}})

Среди условий нет подходящего индекса (в том числе составного), так что начинается полное сканирование по первичному ключу.

Оптимистичные блокировки

Внесение параллельных изменений из разных обработчиков в один и тот же объект может вызвать конфликты. Чтобы избежать конфликта, задайте один из двух параметров в аргументе запроса options:

Note

Параметры only_if_version и if_not_exists взаимоисключающие. При использовании параметров вместе в одном запросе система выдаст ошибку.

Справочник по Repository API

repository.find(type_name, filter[, options])

Возвращает объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество возвращаемых элементов. Значение по умолчанию: 10;

    • after – курсор пагинации на первый элемент;

    • all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;

    • version – версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;

    • mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

    • prefer_replica – целевой экземпляр для выполнения запроса. Возможные значения: true и false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

    • balance – управление балансировкой нагрузки. Возможные значения: true и false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

таблица объектов, соответствующих заданным условиям

Return type

table

Пример

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"},
  {"last_name", "==", "Petrov"}})
repository.get(type_name, pkey[, options])

Получает объект по первичному ключу. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • pkey (any) – первичный ключ

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • version – версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;

    • mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

    • prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

    • balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

объект

Return type

table

Пример

repository.get("Client", 42)
repository.put(type_name, object[, options])

Вставляет новый или заменяет существующий объект. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.

Parameters

  • type_name (string) – тип объекта

  • object (table) – объект для вставки

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;

    • only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;

    • if_not_exists – проверка имеющегося объекта перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище;

    • skip_result – при значении true возвращает пустой массив, а не сами измененные объекты. По умолчанию: false.

Returns

измененный объект

Return type

table

Пример

Запрос добавляет объект с первичным ключом id:

repository.put("Client", {id = "42", first_name = "Ivan", last_name = "Petrov"})

Если версионирование отключено:

  • новый объект добавляется в хранилище;

  • объект c уже существующим id заменяет собой старый такой объект.

Если версионирование включено:

  • новый объект добавляется в хранилище, version равно последней версии;

  • для объекта c уже существующим id добавляется новая версия объекта.

repository.put_batch(type_name, array[, options])

Вставляет массив из новых объектов или заменяет существующие. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.

Parameters

  • type_name (string) – тип объекта

  • array (table) – массив объектов для вставки

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;

    • only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;

    • if_not_exists – проверка имеющегося массива объектов перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существуют ли уже такие объекты в хранилище. Новые объекты будет добавлены, если их еще нет в хранилище;

    • skip_result – при значении true возвращает пустой массив, а не сами измененные объекты. По умолчанию: false.

Returns

таблица с измененными объектами

Return type

table

Пример

Запрос вставляет массив объектов:

array = {}
batch_count = 1000
for i = 1, batch_count do
  array[i] = {id = tostring(i), old_field = tostring(i)}
end

repository.put_batch("Client", array)

Если версионирование отключено:

  • новые объекты добавляются в хранилище;

  • объекты c уже существующими id заменяют собой старые такие объекты.

Если версионирование включено:

  • новые объекты добавляются в хранилище, version равно последней версии;

  • для объектов c уже существующими id добавляются новые версии объектов.

repository.update(type_name, filter, updaters[, options])

Обновляет объекты, соответствующие заданным условиям. Запрос выполняется в две стадии:

  • исполнение запроса на каждом хранилище, которое может содержать объекты по условию в аргументе filter;

  • сбор результатов на роутере.

Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • updaters (table) –

    список обновлений для объекта, состоящий из списка мутаторов {{mutator, path, new_value}, ...}, где:

    • mutator – имя мутатора, например:

      • set – устанавливает значение;

      • add – увеличивает значение на указанное число;

      • sub – уменьшает значение на указанное число;

    • path – строковый путь до поля объекта с точкой-разделителем (.). Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех вложенных объектов;

    • new_value – новое значение;

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first_n_on_storage – количество возвращаемых элементов;

    • after – курсор пагинации на первый элемент;

    • version – версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;

    • only_if_version – проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;

    • skip_result – при значении true возвращает пустой массив, а не сами обновленные объекты. По умолчанию: false.

Returns

таблица с обновленными объектами

Return type

table

Примеры

Запрос обновляет имя клиента с id = 42:

repository.update(
  "Client",
  {{"id", "==", 42}},
  {{"set", "first_name", "Ivan"},
  {"set", "last_name", "Petrov"}})

Если у клиента истек срок действия первого паспорта и необходимо обновить соответствующее поле expired_flag, можно использовать следующий запрос:

repository.update(
  "Client",
  {{"id", "==", 42}},
  {{"set", "passports.1.expired_flag", "true"}})

где .1. – индекс массива, содержащего экземпляры сущности Passport объекта Client, то есть первый паспорт клиента.

repository.update_batch(type_name, updates_list[, options])

Обновляет объекты, соответствующие заданным условиям. Вызывает несколько обновлений в одном запросе. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

  • type_name (string) – тип объекта

  • updates_list (table) –

    список обновлений, которые необходимо применить. Для каждого обновления в списке задаются вложенные элементы:

    • таблица, содержащая список условий-предикатов для выбора (фильтрации) объектов указанного типа;

    • список мутаторов {{mutator, path, new_value}, ...} (список обновлений для объекта), где:

      • mutator – имя мутатора, например:

        • set – устанавливает значение;

        • add – увеличивает значение на указанное число;

        • sub – уменьшает значение на указанное число;

      • path – строковый путь до поля объекта с точкой-разделителем (.). Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех вложенных объектов;

      • new_value – новое значение;

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first_n_on_storage – количество возвращаемых элементов;

    • after – курсор пагинации на первый элемент;

    • version – версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;

    • only_if_version – проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;

    • skip_result – при значении true возвращает пустой массив, а не сами обновленные объекты. По умолчанию: false.

Returns

таблица с обновленными объектами

Return type

table

Пример

Запрос обновляет имена клиентов с id = 40 и id = 41:

repository.update_batch(
  "Client", { {
  {{"id", "==", 40}},
  {{"set", "first_name", "Maria"},
  {"set", "last_name", "Ivanova"}},
  }, {
  {{"id", "==", 41}},
  {{"set", "first_name", "Anna"},
  {"set", "last_name", "Ivanova"}}
  } })
repository.delete(type_name, filter[, options])

Удаляет объекты, соответствующие заданным условиям. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод удаляет указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first_n_on_storage – количество возвращаемых элементов;

    • after – курсор пагинации на первый элемент;

    • version – версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;

    • only_if_version – проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;

    • skip_result – при значении true возвращает пустой массив, а не сами удаленные объекты. По умолчанию: false.

Returns

таблица с удаленными объектами

Return type

table

Пример

Запрос удаляет клиентов с заданной фамилией:

repository.delete(
  "Client",
  {{"last_name", "==", "Petrov"}})

В результате запроса все объекты, удовлетворяющие условию, дополняются новой версией (используется значение по умолчанию).

repository.count(type_name, filter[, options])

Вычисляет количество объектов, соответствующих заданным условиям. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество элементов. Значение по умолчанию: 10;

    • after – курсор пагинации на первый элемент;

    • version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;

    • all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;

    • only_if_version – проверка имеющейся версии перед обработкой. Параметр применяется только при включенном версионировании. При указанном параметре объект обрабатывается, только если последняя версия объекта совпадает с указанной;

    • if_not_exists – проверка имеющегося объекта перед обработкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;

    • skip_result – при значении true возвращает пустой массив, а не сами обновленные объекты. По умолчанию: false.

Returns

количество объектов, соответствующих фильтру

Return type

number

repository.pairs(type_name, filter[, options])

Создает итератор. Используется для чтения большого объема данных. Сигнатура функции аналогична repository.find(), но в pairs() нет параметра first, пагинация применяется автоматически. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • after – курсор пагинации на первый элемент;

    • version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;

    • all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;

    • mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

    • prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

    • balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;

    • timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout.

Returns

итератор

Пример

В примере таблица заполняется результатами вызова repository.pairs() и затем печатается:

local res = {}
for _, object in repository.pairs("Client",{{"first_name", "==", "Ivan"}}) do
    table.insert(res, object)
end
print(res)
repository.call_on_storage(type_name, index_name, value, func_name[, func_args, options])

Вызывает функцию на экземпляре с ролью storage. Файл с функцией должен храниться в директории src в корневой директории TDG.

Parameters

  • type_name (string) – тип объекта

  • index_name (string) – имя индекса

  • value (any) – значение ключа поиска

  • func_name (string) – имя вызываемой функции

  • func_args (table) – аргументы, которые передаются в вызываемую функцию

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;

    • mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

    • prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

    • balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

результат выполнения функции

Return type

any

Пример

Запрос вызывает функцию on_storage.call для объекта с id = 42, в функцию переданы аргументы 2 и 4:

repository.call_on_storage('Data', 'id', '42', 'on_storage.call', {2, 4}, { timeout = 0.1 })
repository.call_on_storage_batch(type_name, arguments_list[, options])

Группирует и вызывает несколько функций на экземплярах с ролью storage. Файлы с функциями должны храниться в директории src в корневой директории TDG.

Parameters

  • type_name (string) – тип объекта

  • arguments_list (table) –

    список (map) c парами key-value, где key – ключ с идентификатором вызова, а value – таблица из следующих элементов:

    • имя индекса;

    • значение индекса;

    • имя вызываемой функции;

    • таблица с аргументами, которые передаются в вызываемую функцию.

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;

    • mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

    • prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

    • balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

результаты выполнения функций

Return type

table

Пример

Запрос вызывает функцию on_storage.call для объектов с id от 1 до 3, в функцию переданы аргументы fn_arg1 и fn_arg2:

repository.call_on_storage_batch(
  'Data', {
  {on_storage1 = {'id', '1', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}},
  {on_storage2 = {'id', '2', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}},
  {on_storage3 = {'id', '3', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}}
  })
repository.push_job(name, args)

Асинхронный запуск задач и функций.

Parameters
Returns

true при успешном запуске задачи

Return type

boolean

repository.map_reduce(type_name, filter, map_fn_name, combine_fn_name, reduce_fn_name, options)

Запрос на обработку всех данных кластером по модели MapReduce. Выполняется на всех экземплярах типа storage. Состоит из трех этапов:

  • Map – выполняется на экземплярах с ролью storage;

  • Combine – выполняется на экземплярах с ролью storage;

  • Reduce — выполняется на экземпляре, где была вызвана функция map_reduce.

Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • map_fn_name (string) – указатель на функцию для этапа Map

  • combine_fn_name (string) – указатель на функцию для этапа Combine

  • reduce_fn_name (string) – указатель на функцию для этапа Reduce

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • map_args – дополнительные аргументы для этапа Map;

    • combine_args – дополнительные аргументы для этапа Combine;

    • combine_initial_state – исходное состояние для этапа Combine;

    • reduce_args – дополнительные аргументы для этапа Reduce;

    • reduce_initial_state — исходное состояние для этапа Reduce;

    • version – версия объекта, которая будет обработана. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;

    • mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

    • prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

    • balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;

    • timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout.

Returns

результат выполнения reduce_fn_name

Return type

any

Этап Map

На каждом экземпляре c ролью storage вызывается функция map_fn_name. Функция вызывается столько раз, сколько на этом экземпляре будет найдено объектов, соответствующих типу type_name и условиям filter. Функция map_fn_name применяется к каждому найденному кортежу.

local map_res, err = map_fn(tuple, options.map_args)

Функция может вернуть любые данные или nil. Если возвращены данные, на следующем этапе они будут использованы для запуска функции combine_fn_name. combine_fn_name будет вызвана столько раз, сколько раз вызовы Map вернут данные.

Этап Combine (опционально)

Нужен для уменьшения количества данных, полученных на стадии Map, перед их передачей по сети и дальнейшей обработкой. Результат каждого вызова map_fn_name передаётся в combine_fn_name. Далее каждый вызов combine_fn_name осуществляется с передачей исходного состояния, равного результату предыдущего вызова combine_fn_name. Для первого вызова исходное состояние равно combine_initial_state, либо равно пустой таблице, если этот параметр не задан.

local combine_res = options.combine_initial_state or {}
local combine_res, err = combine_fn_name(combine_res, map_res, options.combine_args)

Функция combine_fn также выполняется на роли storage.

Результат выполнения combine_fn накапливается в переменной combine_res и передается на ту роль, откуда был вызван map_reduce – в функцию reduce_fn_name.

Этап Reduce

Этап предназначен для завершения обработки данных со всего кластера. Данные передаются по сети на экземпляр, на котором была вызвана функция map_reduce. Там вызывается функция reduce_fn_name. Функция будет вызвана столько раз, сколько экземпляров типа storage в кластере найдут подходящие объекты и, соответственно, вернут результат в combine_res. Результат reduce_fn_name возвращается как результат всего map_reduce.

local reduce_res, err = reduce_fn_name(combine_res, options.reduce_initial_state, options.reduce_args)

Доступ к данным

Основные функции для доступа к данным в TDG входят в программный интерфейс репозитория. Кроме этого, для работы доступны следующие модули:

model_accessor

Модуль model_accessor содержит функции для доступа к данным на экземпляре с ролью storage.

CRUD

Note

Все запросы ниже, за исключением put(), поддерживают параметр filter, позволяющий задать условия фильтрации объектов. Узнать больше об этом параметре можно в разделе Repository API.

model_accessor.count(type_name, filter[, options])

Вычисляет количество записей, соответствующих заданным условиям. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество элементов. Значение по умолчанию: 10;

    • after – курсор пагинации на первый элемент;

    • version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;

    • all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество записей, соответствующих фильтру

Return type

number

model_accessor.find(type_name, filter[, options])

Возвращает объекты, соответствующие заданным условиям. Пагинация осуществляется аналогично операциям интерфейса репозитория TDG. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество возвращаемых элементов. Значение по умолчанию: 10;

    • after – курсор пагинации на первый элемент;

    • all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;

    • version – версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной.

Returns

таблица объектов, соответствующих заданным условиям

Return type

table

model_accessor.get(type_name, filter[, options])

Получает объект по первичному ключу. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – первичный ключ

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество возвращаемых элементов. Значение по умолчанию: 10;

    • after – курсор пагинации на первый элемент;

    • version – версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;

    • all_versions – указатель для поиска по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false.

Returns

объект

Return type

table

model_accessor.delete(type_name, filter[, options])

Удаляет объекты, соответствующие заданным условиям. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод удаляет указанную версию объекта.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество возвращаемых элементов. Значение по умолчанию: 10;

    • version – версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;

    • only_if_version – проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество удаленных объектов

Return type

number

model_accessor.put(type_name, object[, options])

Вставляет новый или заменяет существующий объект. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.

Parameters

  • type_name (string) – тип объекта

  • object (table) – объект для вставки

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;

    • only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;

    • if_not_exists – проверка имеющегося объекта перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище.

Returns

количество измененных объектов

Return type

number

model_accessor.update(type_name, filter, updaters[, options])

Обновляет объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

  • type_name (string) – тип объекта

  • filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа

  • updaters (table) –

    список обновлений для объекта, состоящий из списка мутаторов {{mutator, path, new_value}, ...}, где:

    • mutator – имя мутатора, например:

      • set – устанавливает значение;

      • add – увеличивает значение на указанное число;

      • sub – уменьшает значение на указанное число;

    • path – строковый путь до поля объекта с точкой-разделителем (.). Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех вложенных объектов;

    • new_value – новое значение;

  • options (table) –

    параметры для управления запросом. Доступные параметры:

    • first – количество возвращаемых элементов. Значение по умолчанию: 10;

    • version – версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;

    • only_if_version – проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;

    • indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество обновленных объектов

Return type

number

Управление транзакциями

model_accessor.begin_transaction()

Начинает транзакцию. Аналог функции box.begin().

Returns

none

model_accessor.commit_transaction()

Завершает транзакцию и сохраняет все изменения. Аналог функции box.commit().

Returns

none

model_accessor.rollback_transaction()

Завершает транзакцию без сохранения изменений. Аналог функции box.rollback().

Returns

none

model_accessor.is_in_transaction()

Проверяет наличие активной транзакции. Аналог функции box.is_in_txn().

Returns

true при наличии активной транзакции, иначе – false

Return type

boolean

Утилиты

model_accessor.unflatten(type_name, tuple)

Преобразует плоский кортеж в Lua-таблицу.

Parameters

  • type_name (string) – тип объекта

  • tuple (table/tuple) – кортеж, который требуется преобразовать

Returns

Lua-таблица

Return type

table

model_accessor.is_read_only()

Возвращает значение параметра box.info.ro – true или false.

Returns

true, если экземпляр находится в режиме read-only или в статусе orphan, иначе false.

Return type

boolean

model_accessor.snapshot()

Создает снимок всех данных и сохраняет его. Аналог функции box.snapshot

Returns

результат выполнения операции – ok, если снимок создан успешно

Return type

string

blob_storage

Модуль blob_storage содержит функции для работы с key-value хранилищем на базе движка vinyl.

blob_storage.new(namespace)

Создает новое key-value хранилище.

Parameters

namespace (string) – имя хранилища

Returns

указатель на созданное хранилище

Return type

table

local_cache

Модуль local_cache содержит функции для доступа к локальному кэшу. Локальный кэш представляет собой Lua-таблицу, с которой можно работать (добавлять и получать данные) в рамках одного экземпляра.

local_cache.set(key, val)

Задает в таблице пару ключ–значение.

Parameters

  • key (string) – ключ

  • val (any) – значение

Returns

none

local_cache.get(key)

Получает значение из таблицы по переданному ключу.

Parameters

key (string) – ключ

Returns

значение для переданного ключа

Return type

any

shared_storage

Модуль shared_storage содержит функции для работы с распределенным кэшем. Распределенный кэш можно использовать для передачи объектов между функциями и экземплярами TDG.

shared_storage.new(namespace)

Создает новый распределенный кэш.

Parameters

namespace (string) – имя хранилища

Returns

указатель на созданное хранилище

Return type

table

Note

При создании распределенного кэша создаётся спейс, хранящийся на одном из наборов реплик с ролью storage. Персистентность данных в распределенном кэше не гарантируется: данные из него могут быть потеряны, например, при перезапуске кластера.

Пример

Чтобы подключить существующий распределенный кэш или создать новый, используйте следующую команду:

local shared_storage_object = shared_storage.new('some_namespace')

Данные в распределенный кэш помещаются в формате key, value, например:

shared_storage_object:set('abc', 123)

где 'abc' – это ключ (key), а 123 – значение (value).

Для получения данных из распределенного кэша выполните следующую команду:

shared_storage_object:get('abc')

connector

Модуль connector содержит функции для отправки данных из sandbox в коннектор.

connector.send(output_name, obj[, output_options])

Направляет объект в секцию output для отправки в смежную систему.

Parameters

  • output_name (string) – имя коннектора

  • obj (object) – объект для отправки

  • output_options (table) – опции для отправки во внешнюю систему

Returns

true в случае успешной отправки, false в случае возникновения ошибки

Return type

boolean

odbc

Модуль odbc содержит функции для работы с API ODBC.

odbc.execute(connection_name, statement, params)

Выполняет запрос через ODBC c заданными параметрами.

Parameters

  • connection_name (string) – название соединения

  • statement (string) – выполняемый запрос

  • params (table) – параметры запроса

Returns

объект запроса

Return type

object

odbc.prepare(connection_name, query)

Подготавливает запрос через ODBC.

Parameters

  • connection_name (string) – название соединения

  • query (string) – запрос

Returns

объект подготовленного запроса

Return type

object

Преобразование данных

Доступные модули:

Помимо модулей, для работы доступна константа box.NULL (нулевой указатель) из встроенного Tarantool-модуля box.

mapping_tools

Модуль mapping_tools содержит функции для работы со значениями внутри объектов.

mapping_tools.get_by_path(obj, path[, delimiter])

Получает значение из объекта по его пути с заданным разделителем.

Parameters

  • obj (table) – объект

  • path (string) – путь к объекту

  • delimiter (string) – разделитель (. по умолчанию).

Returns

объект

Return type

table

mapping_tools.set_by_path(obj, path, value[, delimiter])

Присваивает значение объекту по его пути с заданным разделителем.

Parameters

  • obj (table) – объект

  • path (string) – путь к объекту

  • value (table) – значение объекта

  • delimiter (string) – разделитель (. по умолчанию).

Returns

none

mapping_tools.just_get_and_set(source_object, source_path, target_object, target_path)

Получает значение из одного объекта и присваивает его другому объекту.

Parameters

  • source_object (table) – исходный объект, из которого получают значение

  • source_path (string) – путь к исходному объекту

  • target_object (table) – целевой объект, которому передается значение исходного объекта

  • target_path (string) – путь к целевому объекту

Returns

none

soap

Модуль soap содержит функции для преобразования SOAP-запроса в формате XML в объекты Lua и обратно.

soap.encode(data)

Преобразует Lua-таблицу в строку с XML-документом.

Parameters

data (table) – Lua-таблица

Returns

XML-документ

Return type

string

soap.decode(doc)

Преобразует строку с XML-документом в объекты Lua.

Parameters

doc (string) – XML-документ

Returns

объекты Lua, полученные в результате парсинга XML.

  • строка, содержащая указатель на пространство имен (namespace);

  • строка с именем метода, переданного в SOAP-запросе (method);

  • Lua-таблица, которая содержит значения, переданные в тегах SOAP-запроса (entries).

Return type

string or table

json

Функции из модуля json для преобразования строки в формате JSON в объект Lua и обратно.

json.encode(lua_value[, configuration])

Преобразует объект Lua в строку в формате JSON.

Parameters

  • lua_value (table/scalar) – объект Lua

  • configuration – дополнительные опции конфигурации (см. функцию json.cfg())

Returns

JSON-строка

Return type

string

json.decode(string[, configuration])

Преобразует JSON-строку в объект Lua.

Parameters

  • string (string) – строка в формате JSON

  • configuration – дополнительные опции конфигурации (см. функцию json.cfg())

Returns

Lua-таблица

Return type

table

yaml

Функция из модуля yaml для преобразования строки в формате YAML в объект Lua.

yaml.encode(lua_value)

Преобразует объект Lua в строку в формате YAML.

Parameters

lua_value (table/scalar) – объект Lua

Returns

YAML-строка

Return type

string

table

Модуль table содержит функции для работы с таблицами в Lua. Информация о модуле table и доступных функциях приведена в справочнике по встроенным модулям. Кроме того, модуль расширен двумя дополнительными функциями:

table.cmpdeeply(got, expected[, extra])

Сравнение двух таблиц с учетом вложенности.

Parameters

  • got (lua-value) – фактический результат

  • expected (lua-value) – ожидаемый результат

  • extra (table) – таблица, в которой сохраняется путь для различающихся элементов

Returns

результат сравнения, true или false

Return type

boolean

table.append_table(where, from)

Копирует один массив в конец другого массива. При этом используется неглубокое (shallow) копирование.

Parameters

  • where (table) – целевая таблица, в которую вставляют значения из первой таблицы

  • from (table) – таблица, значения которой добавляют в целевую таблицу

Returns

целевая таблица

Return type

table

Константа box.NULL

Константа box.NULL представляет собой нулевой указатель (NULL pointer). box.NULL позволяет хранить ключ без значения, в таблицах эта константа является местозаполнителем для значения nil. Имеет тип cdata. Чтобы узнать больше о box.NULL, обратитесь к соответствующему разделу справочника> в документации Tarantool.

Управление обработкой

Доступные модули и функции:

spawn

Модуль spawn содержит функции для запуска файберов.

spawn.spawn(func_name, args, options)

Запускает один или несколько файберов для выполнения функции func_name с заданными аргументами.

Parameters

  • func_name (string) – имя функции

  • args (table) – аргументы функции

  • options (table) – дополнительные параметры, в которых можно указать время ожидания. Пример: spawn('my_func', {1, 2, 3}, {timeout = 30}).

Return type

table

spawn.spawn_n(func_name, func_num, options)

Запускает func_num количество файберов для выполнения функции func_name без аргументов.

Parameters

  • func_name (string) – имя функции

  • func_num (number) – количество запускаемых файберов

  • options (table) – дополнительные параметры, в которых можно указать время ожидания. Пример: spawn_n('my_func', 2, {timeout = 30}).

Returns

функция spawn()

fiber

Функция из модуля fiber.

fiber.sleep(time)

Передает управление другому файберу и переходит в режим ожидания на указанное количество секунд. Перевести в режим ожидания можно только текущий файбер.

Parameters

time (number) – количество секунд в режиме ожидания

Returns

none

request_context

request_context.get()
Returns

контекст запроса

Return type

table

Мониторинг

Доступные модули:

log

Модуль log содержит функции для записи сообщений в журнал (по аналогии с модулем Tarantool log).

log.error(message)
log.warn(message)
log.info(message)
log.verbose(message)
log.debug(message)

Записывает сообщение в журнал с указанным уровнем детализации. Значение на выходе представляет собой строку в журнале, которая содержит:

  • текущую метку времени

  • название модуля

  • обозначения „E“, „W“, „I“, „V“ или „D“ – в зависимости от вызванной функции

  • содержимое аргумента message

Parameters

message (any) –

Сообщение в журнале. Аргумент message может содержать:

  • строку

  • спецификаторы формата %d or %s

  • таблицу

  • скалярный тип данных

Returns

nil

tracing

Модуль tracing содержит функцию трассировки.

tracing.start_span(name, ...)

Начинает span (основной блок трассировки в распределенных системах) и возвращает специальный объект. Для завершения трассировки выполнения функции используется метод finish возвращаемого объекта.

Parameters

name (string) – имя для span

Returns

object

metrics

Функции из модуля metrics. Узнать больше о метриках в TDG можно из раздела Мониторинг в руководстве администратора.

metrics.counter(name[, help, metainfo])

Регистрирует новый монотонно возрастающий счетчик.

Parameters

  • name (string) – имя счетчика

  • help (string) – описание счетчика

  • metainfo (table) – метаинформация счетчика

Returns

объект счетчика

Return type

counter_obj

metrics.gauge(name[, help, metainfo])

Регистрирует новую метрику для числовых значений. Такие значения могут как возрастать, так и убывать.

Parameters

  • name (string) – имя метрики типа gauge

  • help (string) – описание метрики типа gauge

  • metainfo (table) – метаинформация метрики типа gauge

Returns

объект gauge

Return type

gauge_obj

metrics.histogram(name[, help, metainfo])

Регистрирует новую гистограмму. Гистограмма – выборка из некоторого количества значений. Тип histogram подсчитывает полученные значения и объединяет их в настраиваемые бакеты (buckets).

Parameters

  • name (string) – имя гистограммы

  • help (string) – описание гистограммы

  • buckets (table) – бакеты гистограммы (массив сортированных неотрицательных чисел)

  • metainfo (table) – метаинформация гистограммы

Returns

объект гистограммы

Return type

histogram_obj

Работа с датами и временем

Доступные модули:

datetime

Модуль datetime содержит функции для работы с датой и временем. Помимо функций ниже, для работы также доступны функции из встроенного Tarantool-модуля datetime.

datetime.now()
Returns

текущее время по Гринвичу (GMT) в наносекундах

Return type

cdata

datetime.sec_to_iso_8601_date(sec)

Преобразует число секунд в строковое представление даты.

Parameters

sec (number) – число секунд

Returns

дата в формате ISO 8601 вида yyyy-MM-dd

Return type

string

datetime.nsec_to_iso_8601_date(nsec)

Преобразует число наносекунд в строковое представление даты.

Parameters

nsec (cdata) – число наносекунд

Returns

дата в формате ISO 8601 вида yyyy-MM-dd

Return type

string

datetime.nsec_to_iso_8601_datetime(nsec)

Преобразует число наносекунд в строковое представление даты и времени.

Parameters

nsec (cdata) – число наносекунд

Returns

дата и время в формате ISO 8601 вида yyyy-MM-ddTHH:mm:ss.SSSZ

Return type

string

datetime.nsec_to_iso_8601_time(nsec)

Преобразует заданную в наносекундах дату и время в строковое представление времени.

Parameters

nsec (cdata) – число наносекунд

Returns

время в формате ISO 8601 вида HH:mm:ss.SSS

Return type

string

datetime.nsec_to_day_of_week(nsec)

Возвращает день недели для заданной в наносекундах даты и времени.

Parameters

nsec (cdata) – число наносекунд

Returns

день недели в формате числа от 1 до 7, где 1 – воскресенье, а 7 – суббота

Return type

number

datetime.iso_8601_datetime_to_nsec(iso_8601_datetime)

Преобразует строковое представление даты и времени в наносекунды.

Parameters

iso_8601_datetime (string) –

дата и время в формате ISO 8601. Доступные форматы строки:

  • yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ

  • yyyy-MM-dd'T'HH:mm:ssZZZZZ

  • yyyy-MM-dd'T'HH:mm:ss

  • yyyy-MM-dd'T'HHmmss.SZZZZZ

  • yyyy-MM-dd'T'HHmmssZZZZZ

  • yyyy-MM-dd'T'HHmmss.SSS

  • yyyy-MM-dd'T'HHmmss

Returns

число наносекунд

Return type

cdata

datetime.iso_8601_date_to_nsec(iso_8601_date)

Преобразует строковое представление даты в наносекунды.

Parameters

iso_8601_date (string) – дата в формате ISO 8601 вида yyyy-MM-dd

Returns

число наносекунд

Return type

cdata

datetime.iso_8601_time_to_nsec(iso_8601_time)

Преобразует строковое представление времени в наносекунды.

Parameters

iso_8601_time (string) – время в формате ISO 8601. Доступные форматы: HH:mm:ss.SSS, HH:mm:ss.

Returns

число наносекунд

Return type

cdata

datetime.iso_8601_day_of_week_to_number(iso_8601_day_of_week)

Преобразует строковое представление дня недели в число от 1 до 7, где 1 – воскресенье, а 7 – суббота.

Parameters

iso_8601_day_of_week (string) – день недели в формате ISO 8601 (например, “Sunday”, “Sun”)

Returns

число от 1 до 7

Return type

number

datetime.custom_datetime_str_to_nsec(date_str, format_str)

Преобразует заданное шаблоном строковое представление даты или даты и времени в наносекунды.

Parameters

  • date_str (string) – дата или дата и времени

  • format_str (string) – шаблон строки

Returns

число наносекунд

Return type

cdata

datetime.millisec_to_formatted_datetime(datetime_millisec, datetime_format_str)

Преобразует миллисекунды в заданное шаблоном строковое представление даты и времени.

Parameters

  • datetime_millisec (number) – время в миллисекундах

  • datetime_format_str (string) – шаблон строки даты и времени

Returns

дата и время, заданные шаблоном

Return type

string

datetime.to_sec(nsec)

Преобразует наносекунды в секунды и приводит к типу number.

Parameters

nsec (cdata) – число наносекунд

Returns

число секунд

Return type

number

datetime.to_millisec(nsec)

Преобразует наносекунды в миллисекунды и приводит к типу number.

Parameters

nsec (cdata) – число наносекунд

Returns

число миллисекунд

Return type

number

datetime.seconds_since_midnight()
Returns

число секунд с начала суток по Гринвичу (GMT)

Return type

number

datetime.curr_date_nsec()

Метка времени (Unix timestamp) в наносекундах, соответствующая началу текущих суток UTC. Например, для времени и даты 01.01.2023 15:42 вернется метка, соответствующая 01.01.2023 00:00.

Returns

Unix timestamp в наносекундах

Return type

cdata

Набор констант, которые используются для работы со временем:

timezone

Модуль timezone содержит функции для работы с часовыми поясами.

timezone.now()
Returns

текущее время по Гринвичу (GMT) в наносекундах

Return type

cdata

timezone.seconds_since_midnight(timezone_id)
Parameters

timezone_id (string) – ID часового пояса

Returns

число секунд с начала текущих суток для указанного часового пояса

Return type

number

timezone.curr_date_nsec(timezone_id)

Метка времени (Unix timestamp) в наносекундах, соответствующая началу текущих местных суток для указанного часового пояса.

Parameters

timezone_id (string) – ID часового пояса

Returns

Unix timestamp в наносекундах

Return type

cdata

Работа с последовательностями

sequence – генератор уникальных возрастающих целых чисел. Уникальность чисел гарантируется в пределах отдельной последовательности с заданным именем даже при вызове из разных файберов или на разных экземплярах. Чтобы обеспечить уникальность при вызовах из разных экземпляров, используется роль core. Эта роль выделяет доступные диапазоны чисел. Новый диапазон чисел выделяется:

По умолчанию для экземпляров или файберов выделяются диапазоны по 10 номеров.

sequence

sequence.get(sequence_name)

Возвращает ссылку на объект заданной последовательности. Если последовательность с таким именем отсутствует, создаёт новую последовательность. Объект последовательности имеет единственный метод next, который возвращает следующий элемент последовательности.

Пример использования

На двух разных экземплярах один раз вызывается обработчик, заполняющий поле объекта уникальным номером с помощью метода next. Тогда на первом экземпляре номер объекта будет 1, а на втором – 11. Если после этого каждый обработчик вызывать еще 9 раз, то номера объектов будут 2–10 и 12–20 соответственно. При повторном запуске обработчика на первом экземпляре объекту будет присвоен номер 21.

Parameters

sequence_name – имя последовательности

Returns

ссылка на объект последовательности

Return type

table

Встроенные функции Lua

Помимо модулей, для работы доступны отдельные функции из библиотеки Lua:

assert(v[, message])

Вызывает исключение, если аргумент v содержит nil или false.

Parameters

  • v (boolean) – аргумент или условие, значение которого проверяется

  • message (string) – сообщение об ошибке. Значение по умолчанию: assertion failed!.

Returns

  • v, если аргумент содержит true;

  • сообщение об ошибке, если аргумент содержит false.

error(message[, level])

Завершает последнюю вызванную защищенную функцию и вызывает исключение. Обычно при этом в начало сообщения добавляется информация о месте возникновения ошибки.

Parameters

  • message (any) – сообщение об ошибке

  • level (number) –

    место возникновения (уровень) ошибки. Возможные уровни:

    • 0 – уровень ошибки не добавляется в сообщение;

    • 1 (по умолчанию) – уровень ошибки в месте вызова функции error();

    • 2 – уровень ошибки в месте вызова функции, которая вызвала функцию error().

Returns

none

next(t[, index])

Позволяет проходить по всем полям таблицы t. Функцию можно использовать, чтобы проверить, пустая ли таблица.

Parameters

  • t (table) – таблица

  • index (number) – индекс элемента в таблице. Если аргумент t – таблица, а index – индекс элемента в в таблице, то next() возвращает индекс следующего после него элемента и связанное с ним значение. Если аргумент пропущен, он интерпретируется как nil. Если в аргументе index передан nil, функция возвращает начальный индекс и значение для него. Если передан индекс последнего элемента таблицы или таблица пустая, возвращается nil.

Returns

индекс элемента таблицы + связанное с ним значение или nil

pairs(t)

Позволяет выполнять итерации по парам ключ-значение (key-value) таблицы t.

Parameters

t (table) – таблица, по которой производится итерация

Returns

  • функция next()

  • таблица t

  • nil

ipairs(t)

Позволяет выполнять итерации по парам ключ-значение (key-value) таблицы t. Использует числовые ключи, другие ключи игнорируются.

Parameters

t (table) – таблица, по которой производится итерация

Returns

  • функция итерации

  • таблица t

  • nil

pcall(function_name, arg1, ···)

Вызывает функцию в защищенном режиме с заданными аргументами. pcall обрабатывает функцию и возвращает код состояния – true или false (boolean).

Parameters

  • function_name (string) – имя вызываемой функции

  • arg1 (any) – аргумент функции

Returns

  • true, если вызов функции был успешным;

  • false, если возникла ошибка.

Если ошибок нет, помимо статуса возвращаются все результаты вызова. Если ошибки есть, помимо статуса возвращается результат выполнения err.

xpcall(function_name, err, arg1, ...)

Как и pcall(), вызывает функцию в защищенном режиме с заданными аргументами, но еще позволяет установить новый обработчик ошибок err. xpcall обрабатывает функцию и возвращает код состояния – true или false (boolean). В случае возникновения ошибки вызывается обработчик err с исходным объектом ошибки и возвращает код состояния (boolean).

Parameters

  • function_name (string) – имя вызываемой функции

  • err (string) – обработчик ошибок

  • arg1 (any) – аргумент функции

Returns

  • true, если вызов функции был успешным;

  • false, если возникла ошибка.

print(...)

Принимает любое количество аргументов и печатает их значения в stdout. Для конвертации значений аргументов в строки используется функция tostring().

Returns

none

select(index, ...)

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

Parameters

  • index (string/number) – индекс, который содержит число или строку #

  • arg (any) – аргумент, переданный в функцию

Returns

  • все аргументы после аргумента с заданным индексом, если index – число;

  • общее количество переданных аргументов, если index – строка #.

tonumber(value)

Конвертирует заданное значение в число.

Parameters

value (string/number) – строка или Lua-число

Returns

конвертированное значение

Return type

number

tonumber64(value)

Конвертирует заданное значение в 64-битное целое число. Подробнее о функции tonumber64() можно прочитать в справочнике по встроенным модулям.

Parameters

value (string/number) – строка или Lua-число. На вход принимаются числа в десятичной, двоичной и шестнадцатеричной системах счисления. Если передать число с дробной частью (например, tonumber64('2.2')) в виде строки, функция вернет null.

Returns

конвертированное значение

Return type

number

tostring(value)

Конвертирует заданное значение в строку.

Parameters

value (any) – строка или Lua-число

Returns

конвертированное значение

Return type

string

type(value)

Определяет тип данных у переданного аргумента.

Parameters

value (any) – аргумент, тип которого требуется определить

Returns

тип данных в формате строки

Return type

string

unpack(list[, i, j])

Возвращает элементы для переданной таблицы. Если индексы элементов i и j пропущены, возвращает все элементы таблицы list.

Parameters

  • list (table) – таблица

  • i (number) – индекс первого возвращаемого элемента. Значение по умолчанию: 1.

  • j (number) – индекс последнего возвращаемого элемента. По умолчанию, j – общее количество элементов таблицы list (длина списка).

Returns

элементы таблицы

Расширения

Вы можете загрузить подключаемые функции, или расширения, в TDG вместе с конфигурацией приложения. Для этого поместите расширения в корень проекта в директорию extensions.

При применении конфигурации в TDG:

Расширение global.lua

Модуль global.lua используется, чтобы задать в TDG глобальные изменения поведения, например, для настройки пользовательского HTTP-маршрута или функции IPROTO. Код из файла модуля запускается при обновлении конфигурации на всех экземплярах и выполняется вне окружения sandbox.

Чтобы добавить это расширение, выполните следующие действия:

  1. В корневой директории TDG создайте директорию extensions.

  2. Создайте файл модуля global.lua, напишите в нем необходимый код, а затем разместите файл в директории extensions. Модуль должен возвращать функцию init(), которая вызывается при применении конфигурации.

  3. Упакуйте в zip-архив:

    • папку extensions, внутри которой лежит файл модуля;

    • файл конфигурации config.yml.

  4. Загрузите архив в TDG согласно инструкции.

Подключение новых функций

Warning

Подключение новых функций в TDG может приводить к проблемам с безопасностью. Чтобы предупредить эти проблемы, рекомендуется:

Чтобы подключить новые функции (расширения) к Sandbox API, выполните следующие действия:

  1. В корневой директории TDG создайте директорию extensions/sandbox. На следующем шаге в нее будет добавлен модуль с подключаемыми функциями. Также нужно проследить, чтобы у пользователей были необходимые права для чтения данной директории.

  2. Разместите в директории sandbox файл Lua-модуля, который вы хотите подключить. Модуль при этом должен возвращать объект с определяемыми модулем функциями. Кроме того, в добавленном модуле все используемые встроенные библиотеки должны быть явно подключены с использованием require(). Пример файла с Lua-модулем:

    -- ./extensions/sandbox/csv.lua
-- По умолчанию в TDG не доступен модуль ``csv``

return require('csv')

  3. Упакуйте в zip-архив:

    • папку extensions/sandbox, внутри которой лежит файл модуля;

    • файл конфигурации config.yml.

  4. Загрузите архив в TDG согласно инструкции.

REST API

В этом справочнике содержатся сведения об адресах HTTP-ресурсов (endpoints) и параметрах запросов и ответов REST API TDG. Выполняя запросы к REST API, можно совершать операции с данными, вызывать сервисы и получать метрики для мониторинга.

Операции с данными

TDG предоставляет следующие возможности работы с данными через REST API:

Чтение данных

Для чтения данных из TDG используются GET-запросы на адреса вида data/<TypeName>. В параметрах запроса передаются условия выборки объектов.

Такие запросы эквивалентны вызовам repository.find() c аналогичными аргументами.

Запрос

GET /data/<TypeName>?<arguments>

Запрос может содержать следующие параметры (все они являются опциональными):

<index_name>

Выборка по индексу <index_name> по полному совпадению с указанным значением. Например: id=10.

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index=0,10,true,null.

<index_name_gt>

Выборка по индексу <index_name> с условием “больше указанного значения”. Например: population_gt=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_gt=0,10

<index_name_ge>

Выборка по индексу <index_name> с условием “больше или равно указанного значения”. Например: population_ge=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_ge=0,10

<index_name_lt>

Выборка по индексу <index_name> с условием “меньше указанного значения”. Например: population_lt=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_lt=0,10

<index_name_le>

Выборка по индексу <index_name> с условием “меньше или равно указанного значения”. Например: population_le=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_le=0,10

<index_name_like>

Выборка по строковому индексу <index_name> по шаблону. Например: name=Abc%

<index_name_ilike>

Выборка по строковому индексу <index_name> по шаблону без учёта регистра. Например: name=abc%

indexed_by

Имя индекса для упорядочивания объектов выборки. При передаче этого параметра объекты будут упорядочены по возрастанию значений указанного индекса.

Обратите внимание, что параметр indexed_by применяется на этапе выборки объектов. Таким образом, запросы, отличающиеся только значением indexed_by, могут возвращать разные наборы объектов. Например, запрос с indexed_by=price&first=5 вернёт 5 объектов с наименьшими значениями price, а запрос c indexed_by=name&first=5 – 5 объектов с первыми значениями name в лексикографическом порядке.

first

Количество возвращаемых объектов. Значение по умолчанию: 10.

after

Значение курсора первого возвращаемого объекта (поле cursor в возвращаемых объектах JSON). Значение по умолчанию: курсор первого добавленного объекта.

version

Запрашиваемая версия объектов для типов, поддерживающих версионирование. Значение по умолчанию: последняя хранимая версия.

Номер версии также можно передать в HTTP-заголовке version.

all_versions

Флаг получения всех доступных версий объектов для типов, поддерживающих версионирование. Значение по умолчанию: false.

Note

При получении объектов не по первичному ключу через REST API учитываются ограничения на максимальное число кортежей, сканируемых и возвращаемых в рамках одного запроса.

Тело запроса для получения данных должно быть пустым.

Ответ

Набор объектов, удовлетворяющих заданным условиям, в формате JSON.

Пример

Запрос:

GET http://localhost:8081/data/City?population_ge=300000&indexed_by=title&first=3

Ответ:

[
    {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin",
        "population": 3520031,
        "capital": true
    },
    {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden",
        "population": 547172,
        "capital": false
    },
    {
        "cursor": "gaRzY2FukqZNb3Njb3emUnVzc2lh",
        "country": "Russia",
        "title": "Moscow",
        "population": 12655050,
        "capital": true
    }
]

Вставка данных

Для вставки данных в TDG используются POST-запросы на адреса вида data/<TypeName>. Такие запросы эквивалентны вызовам repository.put c аналогичными аргументами.

Запрос

POST /data/<TypeName>?<arguments>

Запрос может содержать следующие параметры (все они являются опциональными):

version

Номер версии объекта для типов, поддерживающих версионирование. Значение по умолчанию: текущее значение временной метки Unix (Unix timestamp).

Номер версии также можно передать в HTTP-заголовке version.

only_if_version

Для типов, поддерживающих версионирование: выполнить вставку, только если в хранилище есть переданный объект и номер его актуальной версии равен указанному значению. Значение по умолчанию: последняя хранимая версия.

skip_result

Флаг выполнения запроса без возврата вставленного объекта. Значение по умолчанию: false.

Тело запроса для вставки объекта должно содержать описание этого объекта в формате JSON.

Если в хранилище уже существует объект с аналогичными значениями полей первичного индекса, в результате выполнения запроса он будет перезаписан.

Ответ

Пример

Запрос:

POST http://localhost:8081/data/City

{
    "population": 3520031,
    "title": "Berlin",
    "capital": true,
    "country":"Germany"
}

Ответ:

{
    "population": 3520031,
    "title": "Berlin",
    "capital": true,
    "country":"Germany"
}

Изменение данных

Для изменения данных в TDG используются PUT-запросы на адреса вида data/<TypeName>. В параметрах запроса передаются условия выборки объектов для изменения, а в теле – новые значения изменяемых полей.

Такие запросы эквивалентны вызовам repository.update c аналогичными аргументами.

Запрос

PUT /data/<TypeName>?<arguments>

Warning

Если в PUT-запросе нет ни одного условия выбора объектов (<index_name> или <index_name_*>), его результатом будет изменение всех объектов типа.

Запрос может содержать следующие параметры (все они являются опциональными):

<index_name>

Выборка по индексу <index_name> по полному совпадению с указанным значением. Например: id=10.

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index=0,10,true,null.

<index_name_gt>

Выборка по индексу <index_name> с условием “больше указанного значения”. Например: population_gt=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_gt=0,10

<index_name_ge>

Выборка по индексу <index_name> с условием “больше или равно указанного значения”. Например: population_ge=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_ge=0,10

<index_name_lt>

Выборка по индексу <index_name> с условием “меньше указанного значения”. Например: population_lt=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_lt=0,10

<index_name_le>

Выборка по индексу <index_name> с условием “меньше или равно указанного значения”. Например: population_le=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_le=0,10

<index_name_like>

Выборка по строковому индексу <index_name> по шаблону. Например: name=Abc%

<index_name_ilike>

Выборка по строковому индексу <index_name> по шаблону без учёта регистра. Например: name=abc%

indexed_by

Имя индекса для упорядочивания объектов выборки. При передаче этого параметра объекты будут упорядочены по возрастанию значений указанного индекса.

version

Номер версии объекта для типов, поддерживающих версионирование. Значение по умолчанию: текущее значение временной метки Unix (Unix timestamp).

Номер версии также можно передать в HTTP-заголовке version.

only_if_version

Для типов, поддерживающих версионирование: выполнить изменение, только если номер актуальной версии объекта равен указанному значению. Значение по умолчанию: последняя хранимая версия.

skip_result

Флаг выполнения запроса без возврата списка изменённых объектов. Значение по умолчанию: false.

Тело запроса для изменения данных должно содержать новые значения изменяемых полей в формате JSON.

Ответ

Пример

Запрос:

POST http://localhost:8081/data/City?population_le=500000

{
    "capital": false
}

Ответ:

[
    {
        "country": "Germany",
        "title": "Bonn",
        "population": 318809,
        "capital": false
    },
    {
        "country": "Germany",
        "title": "Karlsruhe",
        "population": 307755,
        "capital": false
    },
    {
        "country": "Russia",
        "title": "Tver",
        "population": 424969,
        "capital": false
    }
]

Удаление данных

Для удаления данных из TDG используются DELETE-запросы на адреса вида data/<TypeName>. В параметрах запроса передаются условия выборки объектов для удаления.

Такие запросы эквивалентны вызовам repository.delete c аналогичными аргументами.

Запрос

DELETE /data/<TypeName>?<arguments>

Warning

Если в DELETE-запросе нет ни одного условия выбора объектов (<index_name> или <index_name_*>), его результатом будет удаление всех объектов типа.

Запрос может содержать следующие параметры (все они являются опциональными):

<index_name>

Выборка по индексу <index_name> по полному совпадению с указанным значением. Например: id=10.

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index=0,10,true,null.

<index_name_gt>

Выборка по индексу <index_name> с условием “больше указанного значения”. Например: population_gt=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_gt=0,10

<index_name_ge>

Выборка по индексу <index_name> с условием “больше или равно указанного значения”. Например: population_ge=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_ge=0,10

<index_name_lt>

Выборка по индексу <index_name> с условием “меньше указанного значения”. Например: population_lt=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_lt=0,10

<index_name_le>

Выборка по индексу <index_name> с условием “меньше или равно указанного значения”. Например: population_le=100000

При использовании составных индексов указывайте значения полей через запятую. Например: multipart_index_le=0,10

<index_name_like>

Выборка по строковому индексу <index_name> по шаблону. Например: name=Abc%

<index_name_ilike>

Выборка по строковому индексу <index_name> по шаблону без учёта регистра. Например: name=abc%

indexed_by

Имя индекса для упорядочивания объектов выборки. При передаче этого параметра объекты будут упорядочены по возрастанию значений указанного индекса.

version

Удаляемая версия объектов для типов, поддерживающих версионирование. Значение по умолчанию: последняя хранимая версия.

all_versions

Флаг удаления всех доступных версий объектов для типов, поддерживающих версионирование. Значение по умолчанию: false.

skip_result

Флаг выполнения запроса без возврата списка удаляемых объектов. Значение по умолчанию: false.

Note

При удалении объектов не по первичному ключу через REST API учитываются ограничения на максимальное число кортежей, сканируемых и возвращаемых в рамках одного запроса.

Тело запроса для удаления данных должно быть пустым.

Ответ

Пример

Запрос:

DELETE http://localhost:8081/data/City?population_ge=300000

Ответ:

[
    {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin",
        "population": 3520031,
        "capital": true
    },
    {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden",
        "population": 547172,
        "capital": false
    },
    {
        "cursor": "gaRzY2FukqZNb3Njb3emUnVzc2lh",
        "country": "Russia",
        "title": "Moscow",
        "population": 12655050,
        "capital": true
    }
]

Вызов сервисов

TDG предоставляет REST API для вызова сервисов, развёрнутых в кластере. Для вызова сервисов используются POST-запросы на адреса вида /service/<service_name>. Аргументы для вызова передаются в параметрах запроса или в виде JSON в теле запроса.

Запрос

POST /service/<service_name>?<arguments>

Аргументы вызова сервиса можно передавать двумя способами:

Аргументы, переданные в параметрах запроса, имеют более высокий приоритет. Все аргументы должны быть переданы одним способом. Нельзя передать часть аргументов в параметрах запроса, а другую часть – в теле.

Если аргумент может принимать значение null, его можно не передавать.

Ответ

Возвращаемое значение сервиса в формате JSON.

Пример

Запрос:

POST http://localhost:8081/service/say_hello?name=world&times=2

Ответ:

{
    "result": "Hello, world! Hello, world!"
}

Получение метрик кластера

Для получения метрик кластера TDG используются GET-запросы на адрес metrics. TDG возвращает метрики в формате Prometheus. Это позволяет в дальнейшем использовать их, например, для визуализации в Grafana.

Запрос

GET /metrics

Тело запроса для получения метрик должно быть пустым.

Ответ

Текущие значения метрик кластера TDG в формате Prometheus.

Пример

Запрос:

GET http://localhost:8081/metrics

Фрагмент ответа:

# HELP tdg_kafka_broker_int_latency_min Kafka: Smallest value of internal producer queue latency in microseconds
# TYPE tdg_kafka_broker_int_latency_min gauge
# HELP lj_gc_freed Total amount of freed memory
# TYPE lj_gc_freed counter
lj_gc_freed{alias="app-01"} 96399741997
# HELP tdg_kafka_eos_producer_id Kafka: The currently assigned Producer ID (or -1)
# TYPE tdg_kafka_eos_producer_id gauge
# HELP tdg_kafka_simple_cnt Kafka: Internal tracking of legacy vs new consumer API state
# TYPE tdg_kafka_simple_cnt gauge
# HELP tnt_cpu_user_time CPU user time usage
# TYPE tnt_cpu_user_time gauge
tnt_cpu_user_time{alias="app-01"} 1868.676635
# HELP tnt_slab_quota_used_ratio Slab quota_used_ratio info
# TYPE tnt_slab_quota_used_ratio gauge
tnt_slab_quota_used_ratio{alias="app-01"} 12.5
# HELP tnt_cpu_number The number of processors
# TYPE tnt_cpu_number gauge
tnt_cpu_number{alias="app-01"} 1
...

Управление настройками через GraphQL API

Этот раздел посвящен различным запросам, позволяющим просматривать и изменять настройки TDG.

Все запросы на просмотр и изменение настроек TDG передаются по протоколу HTTP в формате GraphQL. При этом они должны иметь соответствующий заголовок для авторизации.

Note

Для выполнения GraphQL-запросов можно использовать встроенный веб-клиент GraphiQL (на вкладке Graphql веб-интерфейса) или любой сторонний GraphQL-клиент, либо иное средство для отправки HTTP-запросов. При этом специализированные GraphQL-клиенты, в отличие от средств отправки HTTP-запросов, могут использовать функции автодополнения и проверки синтаксиса запросов, а также автоматического формирования документации на GraphQL API. Данные стандартные возможности GraphQL позволяют определять состав функций API, а также состав аргументов функций, типы исходных данных и возвращаемых результатов.

GraphQL-запросы от клиентов (за исключением встроенного веб клиента GraphiQL) необходимо направлять на соответствующие адреса (endpoints):

Данные по аргументам вызова функций и возвращаемым результатам не приводятся, исходя из того, что GraphQL обладает встроенными механизмами обмена этой информацией с клиентским программным обеспечением, выполняющим запросы. Описания параметров и аргументов приведены в исключительном порядке для отдельных случаев, требующих пояснения.

Основные настройки TDG

Для выполнения запроса направьте его по протоколу HTTP на HTTP-порт экземпляра кластера с ролью connector с указанием адреса ресурса (endpoint) /graphql и заголовком admin, а также данными авторизации.

Пример выполнения запроса при помощи утилиты curl:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'schema: admin' \
  --data '{"query":"query{  user{  list{  username  }  }  }  "}'

Далее приведены все типы запросов на чтение или изменение основных настроек TDG. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

Запросы на получение информации по текущим настройкам и состоянию (query)

Пример запроса на получение названия роли по ее id (access_role.get):

query {
    access_role {
        get(id: 1) {
            name
        }
    }
}
query.jobs

Чтение ремонтной очереди неудавшихся отложенных работ (попытка выполнения которых закончилась неудачно, вкладка Failed jobs):

  • get_list – возвращает список объектов ремонтной очереди отложенных работ.

query.repair_list

Возвращает список объектов, находящихся в ремонтной очереди (вкладка Repair).

query.tasks

Чтение списка задач:

  • get_list – возвращает список задач и результатов их исполнения.

query.password_generator

Генерация и проверка валидности паролей, чтение настроек требований к сложности паролей:

  • generate – возвращает сгенерированный пароль.

  • validate – выполняет проверку переданного пароля на соответствие имеющимся требованиям к сложности пароля.

  • config – возвращает текущие настройки требований к сложности пароля.

query.output_processor

Чтение данных ремонтной очереди объектов на отправку (вкладка Output Processor):

  • get_list – возвращает список объектов в ремонтной очереди на отправку (объекты, отправка которых не удалась).

query.access_role

Чтение настроек ролевой модели:

  • actions_list – возвращает список всех возможных действий, доступ к которым настраивается при помощи ролевой модели.

  • get_access_role_actions – возвращает список действий, доступных для роли по ее id.

  • list – возвращает список ролей.

  • get – возвращает данные о роли по ее id.

query.cartridge

Чтение данных из конфигурации:

  • test_soap_data – возвращает текст подсказки по умолчанию на вкладке Test веб-интерфейса.

  • self – отображает информацию о текущем сервере (экземпляре TDG).

query.data_access_action

Чтение информации о шаблонах доступа к действиям над данными:

  • list – возвращает список настроенных шаблонов доступа.

  • get – возвращает информацию о шаблоне по его id.

query.user

Чтение информации о пользователях и настройке доступа анонимных пользователей:

  • is_anonymous_allowed – возвращает статус настройки, разрешающей доступ без авторизации.

  • self – возвращает информацию о текущем пользователе.

  • list – возвращает список пользователей.

query.notifier_get_users

Возвращает список подписчиков (вкладка Subscribers).

query.audit_log

Чтение данных о журнале событий безопасности:

  • get – возвращает журнал событий безопасности (аудит лог).

  • enabled – возвращает статус настройки, отвечающей за включение и отключение ведения журнала аудита.

query.maintenance

Чтение служебной информации:

  • clock_delta – данные по рассинхронизации времени на внутренних (системных) часах экземпляров. Может возвращать следующие значения:

    • value – возвращает максимальное текущее значение отклонения часов между экземплярами кластера.

    • is_threshold_exceeded – отвечает на вопрос, превышено ли предельное значение отклонения часов среди экземпляров кластера.

  • get_aggregates – возвращает список агрегатов модели данных.

  • current_tdg_version – проверяет версию TDG при применении конфигурации (только в схеме admin).

  • unlinked_space_list – возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

query.token

Чтение информации о токенах приложений:

  • list – выводит список всех токенов приложений.

  • get – выводит информацию о токене по его имени. В запрос передается единственный аргумент name – имя токена.

query.get_mail_server

Возвращает настройки почтового сервера для отправки оповещений.

query.config

Чтение настроек кластера:

  • vshard-timeout – возвращает таймаут выполнения удаленного вызова для операции модуля Tarantool vshard.

  • force_yield_limits – возвращает количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности.

  • hard_limits – возвращает текущие настройки ограничений при выполнении GraphQL-запросов. Может возвращать следующие значения:

    • scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса.

    • returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос.

  • graphql_query_cache_size – возвращает ограничение количества кэшируемых уникальных GraphQL-запросов. Кэшируется только текст запроса, но не переменные.

  • locked_sections_list – Список закрепленных секций. Если в список закрепленных секций добавить любую секцию, например, секцию metrics, а потом загрузить новый файл конфигурации, в котором секции metrics не будет, то эта секция не удалится – вместо нее будет использована последняя загруженная версия секции metrics. Прописать закрепленные секции в файле конфигурации явным образом нельзя.

query.account_provider

Управление доступом:

  • ldap – возвращает конфигурацию LDAP.

query.checks

Валидация различных настроек:

  • cron_syntax – проверяет корректность синтаксиса заданного cron-выражения.

  • storage_dir_writable – проверяет возможность записи в заданную директорию.

query.data_type

Доступ к текущей модели данных:

  • model – возвращает текущую модель данных.

  • expiration – возвращает настройки устаревания данных.

  • versioning – возвращает параметры версионирования модели данных.

query.logs

Доступ к общему журналу событий:

  • get – возвращает записи общего журнала событий (логи).

  • config – возвращает конфигурацию журнала событий.

query.metrics

Доступа к метрикам:

  • config – возвращает настройки метрик.

query.migration

Управление миграцией данных:

  • stats – возвращает ход выполнения миграции данных.

query.settings

Настройки учетной записи:

  • get – возвращает настройки учетной записи.

Запросы на внесение изменений в настройки (mutation)

Пример запроса на изменение настроек требований к сложности паролей пользователей (password_generator.config):

mutation {
    password_generator {
        config(lower: true, digits: true, symbols: false, min_length: 6)
    }
}
mutation.jobs

Работа с ремонтной очередью неудавшихся отложенных работ (попытка выполнения которых закончилась неудачно, вкладка Failed jobs):

  • delete_all_jobs – удалить все отложенные работы из ремонтной очереди отложенных работ.

  • try_again_all – выполнить повторную попытку обработки всех отложенных работ из ремонтной очереди отложенных работ.

  • try_again – выполнить повторную попытку обработки неудавшейся отложенной работы по ее id.

  • delete_job – удалить неудавшуюся отложенную работу по ее id.

mutation.token

Работа с токенами приложений:

  • remove – удалить токен приложения по его имени. В запрос передается единственный аргумент name – имя токена.

  • import – импортировать токен приложения. Возможные аргументы:

    • state_reason (опционально) – пояснение к присвоению текущего статуса.

    • expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.

    • uid – внутренний ID токена.

    • role – имя роли из ролевой модели доступа.

    • state – статус (active/blocked).

    • created_at – дата и время создания в формате Unix time.

    • name – имя токена.

    • last_login (опционально) – дата и время последнего входа в формате Unix time.

    • unblocked_at (опционально) – дата и время последней разблокировки в формате Unix time.

  • add – добавить новый токен приложения. Возможные аргументы:

    • expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.

    • name – имя токена.

    • role – имя роли из ролевой модели доступа.

  • update – отредактировать данные токена приложения (срок действия или роль). Возможные аргументы:

    • expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.

    • name – имя токена.

    • role – имя роли из ролевой модели доступа.

  • set_state – изменить статус токена приложения (заблокировать или разблокировать). Возможные аргументы:

    • state – статус (active/blocked/new).

    • reason (опционально) – пояснение к присвоению нового статуса.

    • name – имя токена.

mutation.notifier_upsert_user

Добавление нового или редактирование существующего адреса для оповещения (вкладка Subscribers). Возможные аргументы:

  • name – имя контакта для оповещения.

  • addr – адрес электронной почты.

  • id – внутренний идентификатор (строка).

mutation.clear_repair_queue

Очистить ремонтную очередь (вкладка Repair).

mutation.password_generator

Изменение настроек требований к сложности паролей пользователей.

mutation.output_processor

Работа с ремонтной очередью на отправку (вкладка Output processor):

  • clear_list – удалить все объекты на отправку из ремонтной очереди.

  • try_again_all – выполнить повторную попытку обработки всех объектов на отправку из ремонтной очереди.

  • try_again – выполнить повторную попытку обработки объекта на отправку из ремонтной очереди по его id.

  • delete_from_list – удалить объект на отправку из ремонтной очереди по его id.

mutation.access_role

Управление настройками ролевой модели:

  • delete – удаление роли пользователя по ее id.

  • create – создание новой роли пользователя. Возможные аргументы:

    • name – имя новой роли.

    • description (опционально) – описание новой роли.

  • update – изменение имени или описания роли пользователя.

  • update_access_role_actions – изменение прав доступа для роли. Возможные аргументы:

    • id – идентификатор роли.

    • actions – список изменяемых прав:

      • id – идентификатор права.

      • allowed – данные о наличии права для роли (Boolean).

mutation.set_mail_server

Изменение настроек почтового сервера для отправки оповещений (см. Подробнее про модуль SMTP). Возможные аргументы:

  • username – имя учетной записи, с которой будет проводиться рассылка.

  • password – пароль от учетной записи.

  • url – адрес почтового сервера.

  • from – адрес, указываемый в поле отправителя сообщения.

  • skip_verify_host – при установке true позволяет пропускать проверку валидности сертификата хоста.

  • timeout – таймаут отправки.

mutation.cartridge

Изменение конфигурации:

  • load_config_example – загружает тестовый пример конфигурации вместо имеющейся конфигурации.

mutation.data_access_action

Внесение изменений в шаблоны доступа к действиям над данным:

  • delete – удалить шаблон.

  • create – добавить новый шаблон.

  • update – отредактировать существующий шаблон.

mutation.user

Управление пользователями:

  • import – импорт пользователя.

  • add – добавление нового пользователя.

  • remove – удаление существующего пользователя по его uid.

  • modify – редактирование существующего пользователя по его uid.

  • self_modify – редактирование пароля или имени учетной записи для текущего пользователя (из-под которого выполняется GraphQL-запрос).

  • set_state – блокирование или разблокирование пользователя.

  • reset_password – сброс пароля пользователя по его uid.

mutation.tasks

Управление задачами:

  • start – запуск задачи по ее id.

  • stop – остановка задачи по ее id.

  • forget – удаляет один из результатов выполнения задачи по его id.

mutation.maintenance

Служебные функции:

  • drop_unlinked_spaces – удаление спейсов от агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

  • truncate_unlinked_spaces – удаление данных из спейсов агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

mutation.audit_log

Ведение журнала событий безопасности (аудит лог):

  • enabled – включение функции ведения журнала событий безопасности.

  • clear – очистка журнала событий безопасности.

  • severity – настройка уровня важности событий, которые будут записываться в журнал событий безопасности.

mutation.notifier_delete_user

Удаляет запись из списка подписчиков (вкладка Subscribers) по ее id.

mutation.repair_all

Выполняет повторную попытку обработки всех объектов из ремонтной очереди (вкладка Repair).

mutation.repair

Выполняет повторную попытку обработки объекта из ремонтной очереди (вкладка Repair) по его id.

mutation.delete_from_repair_queue

Выполняет удаление объекта из ремонтной очереди (вкладка Repair) по его id.

mutation.config

Изменение настроек кластера:

  • vshard-timeout – таймаут выполнения удаленного вызова для операции модуля Tarantool vshard.

  • force_yield_limits – количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности.

  • hard_limits – ограничения при выполнении GraphQL-запросов. Возможные аргументы:

    • scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса.

    • returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос.

  • graphql_query_cache_size – ограничение количества кэшируемых уникальных GraphQL-запросов.

mutation.account_provider

Управление доступом:

  • ldap – позволяет изменить конфигурацию LDAP.

mutation.backup

Управление резервным копированием конфигураций:

  • config_apply – применяет конфигурацию заданной версии.

  • config_delete – удаляет конфигурацию заданной версии.

  • config_save_current – создает резервную копию конфигурации с заданным комментарием.

  • settings – изменяет настройки резервного копирования конфигураций.

mutation.connector

Управление коннекторами:

  • http_request – отправляет заданный объект используя HTTP.

  • soap_request – отправляет заданный объект используя SOAP.

mutation.data_type

Доступ к текущей модели данных:

  • model – позволяет изменить текущую модель данных.

  • expiration – позволяет изменить настройки устаревания данных.

  • versioning – позволяет изменить версию модели данных.

mutation.expiration_cleanup

Очистка (сброс) настроек устаревания данных по имени агрегата.

mutation.logs

Управление общим журналом событий:

  • truncate – очищает журнал событий.

  • config – позволяет изменить конфигурацию журнала событий.

mutation.metrics

Управление метриками:

  • config – позволяет изменить настройки метрик.

mutation.migration

Управление миграцией данных:

  • apply – позволяет поменять настройки миграции данных.

  • dry_run – запускает миграцию данных.

mutation.settings

Управление настройками учетной записи:

  • put – добавляет заданные настройки учетной записи.

  • delete – удаляет заданные настройки учетной записи.

Настройки Tarantool Cartridge

Для выполнения запроса, его необходимо направить по протоколу HTTP на HTTP порт любого экземпляра кластера с указанием адреса ресурса (endpoint) /admin/api, а также данными авторизации.

Пример выполнения запроса при помощи утилиты curl:

curl --request POST \
  --url http://172.19.0.2:8080/admin/api \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'content-type: application/json' \
  --data '{"query":"query{\n  cluster{\n    known_roles{\n      name\n      dependencies\n    }\n  }\n}"}'

Далее приведены все типы запросов на чтение или изменение основных настроек Tarantool Cartridge. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

Запросы на получение информации по текущим настройкам и состоянию кластера (query)

Пример запроса на получение информации о пользователе по его имени (cluster.users):

query {
    cluster {
        users { username }
    }
}
query.cluster

Управление кластером:

  • self – позволяет получить информацию о текущем сервере (который выполняет запрос).

  • failover – возвращает текущий статус включения функции failover.

  • failover_params – возвращает текущие настройки функции failover. Может возвращать следующие значения:

    • tarantool_params – параметры подключения:

      • uri – адрес подключения.

      • password – пароль для подключения.

    • mode – режим работы (disabled, eventual или stateful).

    • state_provider – тип внешнего хранилища для режима работы stateful.

  • vshard_bucker_count – возвращает число виртуальных бакетов в кластере

  • issues – возвращает список проблем (issues), зарегистрированных в кластере.

  • auth_param – возвращает параметры авторизации. Эти параметры относятся к авторизации в Tarantool Cartridge, а не в TDG:

    • enabled – включена ли функция авторизации.

    • username – имя текущего пользователя.

    • cookie_max_age – максимальное время жизни пользовательской cookie (в секундах).

    • cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить.

    • implements_add_user – в кластере реализована функция добавления пользователей.

    • implements_remove_user – в кластере реализована функция удаления пользователей.

    • implements_edit_user – в кластере реализована функция редактирования пользователей.

    • implements_list_user – в кластере реализована функция вывода списка пользователей.

    • implements_get_user – в кластере реализована функция вывода информации о конкретном пользователе.

    • implements_check_password – в кластере реализована функция проверки аутентификатора пользователя.

  • known_roles – возвращает список всех известных ролей экземпляров и их зависимостей.

  • webui_blacklist – возвращает список страниц веб-интерфейса, которые должны быть скрыты (исключены из отображения). Обычно это те страницы, доступ к которым запрещен (запрет доступа осуществляется другими механизмами).

  • vshard_groups – информация об имеющихся группах модуля vshard, используемых для распределенного хранения данных.

  • can_bootstrap_vshard – имеется ли возможность вызвать функцию bootsrap_vshard.

  • config – возвращает текущую конфигурацию.

query.servers

Возвращает информацию по серверам кластера.

query.replicasets

Возвращает информацию по наборам реплик кластера.

Запросы на внесение изменений в настройки (mutation)

Пример запроса на изменение настроек автоматического восстановления (cluster.failover):

mutation {
    cluster {
        failover(enabled: false)
    }
}
mutation.cluster

Настройки кластера:

  • schema – применение новой модели данных.

  • failover – включение или отключение функции автоматического восстановления.

  • failover_params – настройка функции автоматического восстановления.

  • edit_topology – позволяет задавать топологию кластера (наборы реплик и их роли).

  • auth_params – настройка параметров авторизации. Эти параметры относятся к авторизации в Tarantool Cartridge, а не к TDG:

    • enabled – включена ли функция авторизации.

    • cookie_max_age – максимальное время жизни пользовательской cookie (в секундах).

    • cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить.

  • failover_promote – переключение мастера в наборе реплик с указанным id на экземпляр с указанным id. Работает только в stateful-режиме функции автоматического восстановления (failover).

  • edit_server – редактирование основных параметров сервера. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

  • probe_server – проверяет, доступен ли экземпляр по указанному адресу для подключения его к кластеру.

  • edit_replicaset – редактирование основных параметров набора реплик. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

  • join_server – подключение нового экземпляра к существующему набору реплик. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

  • bootstrap_vshard – при вызове происходит распределение данных по серверам (См. bootsrap_vshard).

  • expel_server – необратимое удаление сервера из кластера. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.