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

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

В качестве среды для выполнения запросов вы будете использовать уже развернутый TDG-кластер.

Чтобы загрузить данные в TDG, а затем получать к ним доступ через запросы GraphQL, нужно сначала определить модель данных. В этом руководстве используется модель из раздела по настройке модели данных:

1. Определение модели данных.
2. Загрузка модели данных.

Модель данных загружена. Теперь можно добавлять, выбирать и удалять данные.

Загрузить данные в TDG можно с помощью мутации GraphQL:

1. В меню слева выберите вкладку GraphQL.

2. Выберите default в качестве нужной схемы и очистите поле запроса.

   

3. В поле слева вставьте следующий запрос:

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

4. Выполните мутацию, нажав кнопку Execute Query (Выполнить запрос):

   

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

Вот типичные сценарии использования, связанные с запросами данных:

• Общий запрос объектов по типу
• Запросы по первичному индексу
• Запросы по вторичному индексу
• Запросы по составному индексу
• Запросы по мультиключевому индексу
• Операторы сравнения
• Множественные условия
• Запросы по отношениям
• Пагинация
• Запросы по версии
• Выбор экземпляров для выполнения запросов

Примеры запросов GraphQL, приведенные ниже, проще всего запустить через встроенный клиент GraphiQL в веб-интерфейсе TDG. Отправляя запросы на доступ к данным, используйте схему по умолчанию (default):

1. В меню слева выберите вкладку GraphQL.
2. Выберите default в качестве нужной схемы, очистите поле запроса и вставьте код примера.

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

 
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 - выборка по шаблону;
• _ilike - выборка по шаблону без учета регистра.

В шаблонах можно использовать подстановочный символ %.

 
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 реализовано версионирование объектов, поэтому в условие запроса можно включать версии. Подробности вы найдете на этой странице: /development/versioning.

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