Data access requests¶

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) – это индекс по полю, которое содержит массив. Если под условие запроса по мультиключевому индексу подходят несколько элементов массива, будет несколько ключей, указывающих на один и тот же объект. Такой объект вернется несколько раз, и это нужно учитывать при составлении запросов и при обработке полученных результатов.

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

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

String field indexes support the _like operator so you can search for a particular pattern in a string. You can use the wildcard sign % in the pattern.

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

Multiple conditions¶

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

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

Requests by relations¶

To select objects by relations, use the same syntax as in the general object type query.

In the example model, there is a one-to-many relationship between the objects Country and City. Consequently, you can get the data both about the country and the cities in one request.

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.