3.1.3. Запросы в формате GraphQL¶

3.1.3.1. Адаптация конфигурации из базового примера¶

Для выполнения примеров в данном разделе используйте кластер TDG, установка и настройка которого проводились ранее.

Для повторения примеров из данного раздела вам потребуется внести определённые исправления в конфигурацию системы, загруженную ранее.

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

{
  "name": "User",
  "type": "record",
  "logicalType": "Aggregate",
  "doc": "читатель",
  "fields": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "username",
      "type": "string"
    },
    {
      "name": "phones",
      "type": {
        "type": "array",
        "items": "string"
      }
    }
  ],
  "indexes": [
    "id",
    "phones"
  ],
  "relations": [
    {
      "name": "subscription",
      "to": "Subscription",
      "count": "many",
      "from_fields": "id",
      "to_fields": "user_id"
    }
  ]
}

Также внесите изменение в описание объекта Book так, чтобы оно стало следующим:

{
  "name": "Book",
  "type": "record",
  "logicalType": "Aggregate",
  "doc": "книга",
  "fields": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "book_name",
      "type": "string"
    },
    {
      "name": "author",
      "type": "string"
    },
    {
      "name": "year",
      "type": "int"
    }
  ],
  "indexes": [
    "id",
    "year"
  ],
  "relations": [
    {
      "name": "subscription",
      "to": "Subscription",
      "count": "many",
      "from_fields": "id",
      "to_fields": "book_id"
    }
  ]
}

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

3.1.3.2. Запрос на получение данных¶

Все агрегаты (объекты логического типа «Aggregate» — см. подробнее раздел о модели данных) доступны для запроса по имени типа. Общий вид GraphQL-запроса на получение данных следующий:

query {
  aggregate_name {
    fields
  }
}

где

• aggregate_name — имя агрегата;

• fields — список запрашиваемых полей.

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

{
  User {
    id
    username
  }
}

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer ee7fbd80-a9ac-4dcf-8e43-7c98a969c34c' \
  --data '{"query":"{User{id,username}}"}'

{
  "data": {
    "User": [
      {
        "id": 1,
        "username": "John Smith"
      },
      {
        "id": 2,
        "username": "Adam Sanders"
      }
    ]
  }
}

3.1.3.3. Выборка агрегатов¶

Отдельно взятый агрегат можно выбрать по индексу. Для этого индексированное поле нужно указать в качестве аргумента запроса. В примере ниже агрегат User выбирается по индексу id (см. описание модели). Проверка условия выполняется на полное совпадение.

{
  User(id: 1) {
    id
    username
  }
}

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

query {
  Subscription(user_id: 1, book_id: 3) {
    id
    user_id
    book_id
  }
}

Для запроса по составному (мультиколоночному) индексу используется массив значений. В нашем примере у агрегата типа Subscription есть составной индекс pkey, включающий в себя поля id и user_id. Пример запроса по этому индексу выглядит так:

{
  Subscription(pkey: [2, 1]) {
    id
    book_id
    user_id
  }
}

3.1.3.4. Мультиключевые индексы¶

Отдельно нужно отметить запросы по так называемому мультиключевому индексу (multikey index), т.е. индексу по полю, содержащему массив. Для иллюстрации возьмем за основу наш пример, в который test такое поле (phones) и соответствующий индекс к агрегату User. Поле phones будет содержать массив, в котором хранятся все телефонные номера читателя.

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

{
  "id": 1,
  "username": "John Smith",
  "phones": [
    "+74951234567",
    "+79997654321",
    "+19001234567"
  ]
}

{
  User(phones_like: "+7%") {
    id
    username
    phones
  }
}

{
  "data": {
    "User": [
      {
        "username": "John Smith",
        "phone": [
          "+74951234567",
          "+79997654321",
          "+19001234567"
        ],
        "id": 1
      },
      {
        "username": "John Smith",
        "phone": [
          "+74951234567",
          "+79997654321",
          "+19001234567"
        ],
        "id": 1
      }
    ]
  }
}

3.1.3.5. Выборка со сравнением¶

Выборки поддерживают операции сравнения в виде суффиксов в именах индексов.

Поддерживаются следующие операторы сравнения:

• _gt (Greater Than) — строго больше;

• _ge (Greater Than or Equal) — больше либо равно;

• _lt (Less Than) — строго меньше;

• _le (Less Than or Equal) — меньше либо равно.

Формат запросов:

{
  aggregate_name(index_gt: value) {
    fields
  }
}

где

• index_gt — наименование индекса, по которому производится выборка с индексом для сравнения;

• value — значение для сравнения.

{
  Book(year_gt: 2008) {
    book_name
    year
    author
  }
}

{
  Book(year_month_gt: [2008, 7]) {
    book_name
    year
    author
  }
}

{
  User(phones_like: "+7%") {
    id
    username
    phones
  }
}

3.1.3.6. Выборка агрегатов по связям¶

Для фильтрации связанных агрегатов используется тот же синтаксис, что и для выборки обычных агрегатов.

В используемом базовом примере агрегаты User и Subscription связаны отношением «один ко многим». Соответственно, в одном запросе можно получить одновременно и данные читателя, и информацию о его подписках (или об отдельно взятой подписке, как в примере ниже).

{
  User(id: 1) {
    id
    username
    phones
    subscription(pkey: [2, 1]) {
      id
      book_id
    }
  }
}

Данный вид запроса аналогичен SQL LEFT OUTER JOIN.

Как объясняется в разделе про отношения между объектами, отношения могут быть односторонними или полными (двусторонними). В нашем примере в модели данных заданы двусторонние отношения (например, поле relations определено и у User, и у Subscription), поэтому также возможен запрос «с другой стороны» — т.е. запрашивая данные по какому-то из абонементов/подписок, в этом же запросе можно получить и данные читателя. В качестве примера выполните следующий запрос.

{
  Subscription(pkey: [2, 1]) {
    id
    book_id
    user {
      id
      username
      phones
    }
  }
}

3.1.3.7. Пагинация¶

Для пагинации используется метод с непрозрачными курсорами, аналогичный описанному в документации по GraphQL (https://graphql.org/learn/pagination/#pagination-and-edges).

В общем виде запрос выглядит так:

{
  aggregate_name(first: 2, after: $cursor)
}

где:

• first указывает максимальное количество возвращаемых элементов (по умолчанию 10);

• after указывает, с какого элемента продолжить выполнение запроса.

В after как раз и передается «непрозрачный курсор». Непрозрачный курсор — это строка, о смысле которой пользователь не должен задумываться. Все, что нужно знать — это то, что, используя эту строку, сервер может продолжить выполнение запроса с нужного места.

Каждый агрегат имеет специальное синтетическое поле cursor, доступное через GraphQL. В дизайне пагинации TDG было решено перенести cursor на уровень агрегата, что позволяет не вводить промежуточных уровней запроса edges и node, как это предлагается делать в руководстве по GraphQL (https://graphql.org/learn/pagination/#pagination-and-edges).

{
  User(first: 2) {
    id
    username
    cursor
  }
}

{
  "data": {
    "User": [
      {
        "cursor": "gaRzY2Fuk6ABzxYAPuJNoseB",
        "username": "John Smith",
        "id": 1
      },
      {
        "cursor": "gaRzY2Fuk6ACzxYAEQtuI8e5",
        "username": "Adam Sanders",
        "id": 2
      }
    ]
  }
}

{
  User(first: 2, after: "gaRzY2Fuk6ACzxYAEQtuI8e5") {
    id
    username
    cursor
  }
}

{
  User(id: 1) {
    id
    username
    phones
    subscription(first: 2) {
      id
      book_id
    }
  }
}

3.1.3.8. Версионирование и запрос исторических данных¶

Основные принципы версионирования данных в TDG указаны тут.

Для передачи и запроса версии используется служебное поле version. Важно отметить, что если в запросе не указывается версия, то возвращается последняя (наибольшая) версия.

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

{
  User(id: 1) {
    id
    username
    phones
    version
  }
}

{
  "data": {
    "User": [
      {
        "version": "1585393144680150551",
        "username": "John Smith",
        "phones": [
          "+74951234567",
          "+79997654321"
        ],
        "id": 1
      }
    ]
  }
}

{
  User(id: 1, version: 1585393144680150550) {
    id
    username
    phones
    version
  }
}

{
  "data": {
    "User": [
      {
        "version": "1585392369718590708",
        "username": "John Smith",
        "phones": [
          "+74951234567",
          "+79997654321",
          "+19001234567"
        ],
        "id": 1
      }
    ]
  }
}

{
  User(id: 1, all_versions: true) {
    id
    username
    version
  }
}

{
  User(id: 1, all_versions: true, first: 3) {
    id
    username
    version
  }
}

3.1.3.9. Ограничения запросов¶

Для контроля нагрузки на сервер сделаны следующие ограничения запроса:

• запрос не должен проходить больше scanned строк;

• запрос не должен возвращать больше returned строк.

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

Настройка данных параметров возможна при конфигурации системы или с помощью специальных запросов и мутаций GraphQL.

3.1.3.10. Изменение данных¶

TDG поддерживает следующие запросы на изменение данных (мутации):

• вставка объекта (insert);

• обновление объекта (update);

• удаление объекта (delete).

mutation {
  aggregate_name(insert: {JSON_input_object}) {
    fields
  }
}

mutation {
  User(
    insert: {
      id: 1
      username: "John Smith"
      phones: ["+74951234567", "+79997654321"]
    }
  ) {
    id
    username
    phones
  }
}

curl --request POST \
   --url 'http://172.19.0.2:8080/graphql?=' \
   --header 'Authorization: Bearer ee7fbd80-a9ac-4dcf-8e43-7c98a969c34c' \
   --data '{"query":"   mutation {User(insert: {id: 1, username: \"John Smith\", phones:[\"+74951234567\", \"+79997654321\"]}) {id username phones}}"}'

{
  "data": {
    "User": [
      {
        "username": "John Smith",
        "phones": [
          "+74951234567",
          "+79997654321"
        ],
        "id": 1
      }
    ]
  }
}

mutation {
  User(
    insert: {
      id: 1
      username: "John Smith"
      phones: ["+74951234567", "+79997654321"]
    }
    only_if_version: 1585392369718590708
  ) {
    id
    username
    phones
  }
}

mutation {
  aggregate_name(update: filter [[mutator, path, new_value], ...]) {
    fields
  }
}

mutation {
  User(id:1 update:[["set", "username", "John D. Smith"]]) {
    id
    username
    phones
  }
}

curl --request POST \
  --url 'http://172.19.0.2:8080/graphql?=' \
  --header 'Authentication: Bearer ee7fbd80-a9ac-4dcf-8e43-7c98a969c34c' \
  --data '{"query":"mutation {User(update: id: 1 [[\"set\", \"username\", \"John D. Smith\"]]) {id username phones}}"}'

{
  "data": {
    "User": [
      {
        "username": "John D. Smith",
        "phones": [
          "+74951234567",
          "+79997654321"
        ],
        "id": 1
      }
    ]
  }
}

mutation {
  aggregate_name(delete: true) {
    fields
  }
}

mutation {
  User(delete: true) {
    id
    username
  }
}

{
  "data": {
    "User": [
      {
        "username": "John Smith",
        "id": 1
      },
      {
        "username": "Adam Sanders",
        "id": 2
      }
    ]
  }
}

mutation {
  User(delete: true, id: 1) {
    id
    username
  }
}

3.1.3.11. Выполнение сервисов¶

GraphQL-запросы дают возможность вызова сервисов в TDG.

Общий вида запроса на выполнение сервиса:

query {
  service_name(arg1: value1, arg2: value2, ...)
}

services:
  select_user_books:
    doc: "select_user_books"
    function: select_user_books
    return_type: string
    args:
      user_id: long

{
  select_user_books(user_id: 1)
}

{
  "data": {
    "select_user_books": "[1, 3]"
  }
}