Запросы данных¶

Общий запрос объектов по типу¶

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

query {
  Country {
    title
  }
}

Ответ – объект JSON, содержащий массив со всеми записями типа Country. Для каждой записи ответ включает только указанные в запросе поля.

{
  "data": {
    "Country": [
      {
        "title": "Russia"
      },
      {
        "title": "Germany"
      }
    ]
  }
}

Запросы по первичному индексу¶

С помощью первичного индекса можно выбрать отдельный объект:

query {
  Country(title: "Germany") {
    title
    phone_code
  }
}

Запросы по вторичному индексу¶

У запросов по вторичному индексу такой же синтаксис:

query {
  City(country: "Russia") {
    title
    country
    population
  }
}

Запросы по составному индексу¶

Чтобы выполнить запрос по составному индексу, укажите массив значений полей:

query {
  City(primary: ["Saint Petersburg", "Russia"]) {
    title
    country
    population
  }
}

Запросы по мультиключевому индексу¶

Мультиключевой индекс (multikey index) – это индекс по полю, которое содержит массив. Если под условие запроса по мультиключевому индексу подходят несколько элементов массива, будет несколько ключей, указывающих на один и тот же объект. Такой объект вернется несколько раз, и это нужно учитывать при составлении запросов и при обработке полученных результатов.

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

Пример:

{
  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
        ]
      }
    ]
  }
}

Операторы сравнения¶

Операторы сравнения представлены суффиксами, которые добавляются к именам индексов.

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

• _gt (больше)

• _ge (больше или равно)

• _lt (меньше)

• _le (меньше или равно)

Пример:

query {
  City(population_ge: 1000000) {
    title
    country
    population
  }
}

При поиске по индексам полей-строк поддерживается оператор _like, который позволяет получать строки, содержащие определенные шаблоны. В шаблонах можно использовать подстановочный символ %.

query {
  City(title_like: "M%") {
    title
    country
  }
}

Множественные условия¶

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

query {
  City(country: "Russia", population_lt: 1000000) {
    title
    country
    population
  }
}

Запросы по отношениям¶

Чтобы выбрать объекты по отношениям, используйте тот же синтаксис, что и в общем запросе объектов по типу.

В примере модели между объектами Country и City есть связь «один ко многим». Поэтому вы можете одним запросом получить данные как о стране, так и о городах.

query {
    Country(title: "Russia") {
        title
        city {
            title
            population
    }
    }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "title": "Russia",
        "city": [
          {
            "title": "Moscow",
            "population": 12655050
          },
          {
            "title": "Saint Petersburg",
            "population": 5384342
          },
          {
            "title": "Tver",
            "population": 424969
          }
        ]
      }
    ]
  }
}

Пагинация¶

В TDG применяется пагинация на основе курсора. Похожий механизм описан в документации GraphQL.

У запроса с пагинацией следующий синтаксис:

query {
    object_name(first:N, after:$cursor)
    }

Пояснение:

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

• after передает непрозрачный курсор – строку, определяющую элемент, с которого система TDG должна продолжить выполнение запроса.

Вот первый запрос с пагинацией:

query {
    City(first: 2) {
        title
        country
        cursor
    }
}

Ответ:

{
  "data": {
    "City": [
      {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin"
      },
      {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden"
      }
    ]
  }
}

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

query {
    City(first: 2, after: "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk") {
        title
        country
        cursor
    }
}

Повторяйте эту логику, пока не получите пустую страницу:

{
  "data": {
    "City": []
  }
}

Для запросов с отношениями пагинация работает аналогичным образом:

query {
  Country(title: "Russia") {
    title
    city(first: 2) {
        title
        population
        cursor
    }
  }
}

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

query {
    City(first: -2) {
        title
        country
        cursor
    }
}

Запросы по версии¶

В 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.