Настройка#

Взаимодействие с серверной частью DataSpace осуществляется через точку доступа со следующим URL-адресом: {серверURL}/graphql.

Параметр, включающий endpoint GraphQL — dataspace.endpoint.graphql.enabled=true.

Параметр, включающий браузерный редактор GraphQL — dataspace.endpoint.graphiql.enabled=true.

Примечание

Для настройки работы endpoint /graphiql через Ingress необходимо также определить параметры:

graphiql.endpoint.graphql=/<path>/graphql
graphiql.basePath=/<path>
graphiql.endpoint.subscriptions=/<path>/subscriptions

В данных параметрах <path> — путь к сервису, согласно правилам на Ingress. Это важно для выполнения запросов с формы /graphiql.

Важно

Для доступа к эндпоинту graphiql необходимо дополнительно указывать ?path=/<path>/graphql&wsPath=/<path>/subscriptions.

Полный путь с предложенной конфигурацией будет выглядеть следующим образом: http://<ingress_route>/<path>/graphiq?path=/<path>/graphql&wsPath=/<path>/subscriptions

Для изменения endpoint можно задать параметр graphql.url=....

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

  • dataspace.endpoint.graphql.schema.settings.calc-expr-fields-placement — определяет расположение полей для вычислимых выражений. Тип — перечисление. Значения:

    • ON_EACH_TYPE — поля вида _get${наименование скалярного типа}(expression: String!): ${наименование скалярного типа} на каждом интерфейсе/типе, соответствующем классу модели.

    • ON_SEPARATE_TYPE (значение по умолчанию) — поле вида _calc: _Calculation на каждом интерфейсе/типе, соответствующем классу модели.

  • dataspace.endpoint.graphql.schema.settings.generate-elems-for-selection — определяет, генерировать ли поля (формата selectionBy${наименование класса модели}) и соответствующие типы (формата _SEC_${наименование класса модели}) для выборки свойств (например, distinct, group by). Тип — логическое значение. Значение по умолчанию — «false».

  • dataspace.endpoint.graphql.schema.settings.generate-str-expr-variable-definition-directive — определяет, генерировать ли директиву @strExpr для определений переменных. Тип — логическое значение. Значение по умолчанию — «».

  • dataspace.endpoint.graphql.schema.settings.generate-str-expr-field-directive — определяет, генерировать ли директиву @strExpr для полей. Тип — логическое значение. Значение по умолчанию — «true».

  • dataspace.endpoint.graphql.schema.settings.generate-str-expr-field — определяет, генерировать ли поле strExpr. Тип — логическое значение. Значение по умолчанию — «false».

Примечание

Настройка dataspace.endpoint.graphql.schema.settings.calc-expr-fields-placement добавлена в связи с введением новой стратегии генерации схемы в части вычислимых выражений (ON_SEPARATE_TYPE), позволяющей сократить общий размер GraphQL-схемы за счет определения полей для вычисления примитивных выражений разных типов в отдельный тип (_Calculation).

Настройка dataspace.endpoint.graphql.schema.settings.generate-elems-for-selection добавлена для того, чтобы позволить отключить генерацию полей и типов, необходимых для функциональности выборки набора свойств.

Следующие настройки появились в связи с тем, что не все инструменты поддерживают спецификацию GraphQL от октября 2021 года (например, директивы для определений переменных появились только в спецификации от октября 2021 года):

  • dataspace.endpoint.graphql.schema.settings.generate-str-expr-variable-definition-directive;

  • dataspace.endpoint.graphql.schema.settings.generate-str-expr-field-directive;

  • dataspace.endpoint.graphql.schema.settings.generate-str-expr-field.

Данные настройки позволяют отключить неподдерживаемые элементы и включить альтернативные.

Механизм выполнения запросов в режиме Dry-Run#

При выполнении GraphQL-запросов query и mutation поддерживается режим Dry Run, позволяющий предварительно проверить выполнение операций без внесения изменений в базу данных. Режим активируется наличием HTTP-заголовка X-Dry-Run.

Настройки режима Dry Run#

Режимы работы настраиваются отдельно для query и mutation. Возможные значения режимов:

Режим

Описание

ROLLBACK

Запрос выполняется, но изменения откатываются

SYNTAX_VALIDATION

Проверяется синтаксическая корректность GraphQL запроса

EXPLAIN_PLAN

Выполняется запрос к БД для получения плана результирующего SQL-запроса (explain plan). Применим только для query-запросов GraphQL.

Примечание

Опция EXPLAIN_PLAN поддерживается для PostgreSQL, Oracle и H2

Настройка осуществляется параметрами конфигурации:

dataspace.graphql.dryRun.query.action=ROLLBACK/SYNTAX_VALIDATION/EXPLAIN_PLAN
dataspace.graphql.dryRun.mutation.action=ROLLBACK/SYNTAX_VALIDATION

Структура ответа#

В теле ответа в разделе extensions добавляется поле "dry-run" с информацией о выполнении операции:

  • status: SUCCESS, FAILURE, ERROR

  • explain_plan (опционально): массив объектов {sql: string, plan: string}, содержащий планы выполнения SQL-запросов (при опции EXPLAIN_PLAN)

Пример структуры ответа:

{
  "data": null,
  "errors": [],
  "extensions": {
    "dry-run": {
      "status": "SUCCESS",
      "explain_plan": [
        {"sql": "...SQL...", "plan": "...PLAN..."}
      ]
    }
  }
}

Примечание

При Dry-Run выполнении:

  • поле data всегда null,

  • поле error содержит ошибки (при наличии)

Просмотр генерируемых SQL-запросов в PostgreSQL#

В процессе выполнения GraphQL-запросов через Web-интерфейс GraphiQL возможно посмотреть генерируемые SQL-операции.

img.png

Для добавления в ответ используемых SQL-операций необходимо добавить в запрос заголовок x-sql-trace (в UI раздел REQUEST HEADERS):

{
  "x-sql-trace": true
}

Внимание!

Для работы функциональности должен быть включен общий мониторинг, а также мониторинг БД: dataspace.monitoring.datasource.enabled=true.

По умолчанию все необходимые опции включены.

В ответе помимо данных будет получен раздел extensions, где:

  • sqlText — текст SQL-операции;

  • elapsedTimeMs — время исполнения SQL-операции в мс;

  • threadName — имя потока, в котором исполнялась SQL-операция;

  • plan — план исполнения SQL-операции в БД (доступен только на PostgreSQL).

Внимание!

По умолчанию построение плана запроса в БД выполняется с помощью команды explain (analyze), которая приводит к реальному исполнению операции. Поэтому (по умолчанию) построение плана запроса выполняется только для операций SELECT.

Настройка просмотра генерируемых SQL-запросов в PostgreSQL#

Значения настроек по умолчанию:

graphql.servlet.sql-tracing-enabled=true
graphql.servlet.sql-tracing.header-name=x-sql-trace
graphql.servlet.sql-tracing-explain-command="explain (analyze,buffers,verbose) "
graphql.servlet.sql-tracing-filtered-command=select,with

Где:

  • graphql.servlet.sql-tracing-enabled — включает всю функциональность просмотра генерируемых SQL-запросов;

  • graphql.servlet.sql-tracing.header-name — задает имя HTTP-заголовка;

  • graphql.servlet.sql-tracing-explain-command — команда для получения плана запроса в PostgreSQL (важен пробел в конце);

  • graphql.servlet.sql-tracing-filtered-command — слова, наличие которых в начале SQL-операции приведет к генерации плана запроса.

Внимание!

Получение плана SQL-запроса возможно только на БД PostgreSQL.

Если необходимо получить план других SQL-операций, то необходимо изменить настройки на:

graphql.servlet.sql-tracing-explain-command="explain "
graphql.servlet.sql-tracing-filtered-command=select,with,insert,update

Если необходимо отключить получение плана SQL-операций, необходимо применить настройку таким образом:

graphql.servlet.sql-tracing-filtered-command=

Настройка размера GraphQL-запроса#

Внимание!

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

Текст ошибки в случае обработки большого GraphQL-запроса:

Invalid Syntax : More than 1048576 characters have been presented. To prevent Denial Of Service attacks, parsing has been cancelled."

или

Invalid Syntax : More than 15000 grammar tokens have been presented. To prevent Denial Of Service attacks, parsing has been cancelled."

Для изменения лимитов необходимо добавить следующие опции:

  • dataspace.graphql.parser.maxTokens — максимальное количество токенов (по умолчанию — 15000);

  • dataspace.graphql.parser.maxCharacters — максимальное количество символов (по умолчанию — 1048576).

Пример:

dataspace.graphql.parser.maxTokens=100000
dataspace.graphql.parser.maxCharacters=24048576

Отключение ограничений бизнес-логики#

Имеется возможность отключить ограничения бизнес-логики для конкретного запроса. Для этого необходимо в GraphQL-запросе указать HTTP-заголовок X-DSPC-override-rules=true.

В перечень ограничений бизнес-логики входят:

  • контроль переходов статусов