В этом руководстве объясняется API запросов GraphQL, который используется в протоколе The Graph.

Материал для перевода взят из статьи.

Запросы

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

Примеры

Запрос одной сущности , определенной в вашей схеме:

{
token(id: "1") {
id
owner
}
}

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

Запросить все сущности :

{
tokens {
id
owner
}
}

Сортировка

При запросе коллекции параметр может использоваться для сортировки по определенному атрибуту. Кроме того, можно использовать для указания направления сортировки: для возрастания или для убывания.

Пример

{
tokens(orderBy: price, orderDirection: asc) {
id
owner
}
}

Нумерация

При запросе коллекции параметр может использоваться для разбивки на страницы с начала коллекции. Стоит отметить, что порядок сортировки по умолчанию — по идентификатору в возрастающем алфавитно-цифровом порядке, а не по времени создания.

Кроме того, параметр может использоваться для пропуска сущностей и разбивки на страницы. Например first: 100 показывает первые 100 объектов, показывает следующие 100 объектов.

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

Пример

Запросите первые 10 :

{
tokens(first: 10) {
id
owner
}
}

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

Пример

Запросить 10 сущностей , смещенных на 10 позиций от начала коллекции:

{
tokens(first: 10, skip: 10) {
id
owner
}
}

Пример

Если клиенту необходимо получить большое количество сущностей, гораздо эффективнее основывать запросы на атрибуте и фильтровать по этому атрибуту. Например, клиент может получить большое количество токенов с помощью этого запроса:

{
query manyTokens($lastID: String) {
tokens(first: 1000, where: { id_gt: $lastID }) {
id
owner
}
}
}

В первый раз он отправит запрос с , а для последующих запросов установит в атрибут последней сущности в предыдущем запросе. Этот подход будет работать значительно лучше, чем использование увеличивающихся значений .

Фильтрация

Вы можете использовать параметр в своих запросах для фильтрации различных свойств. Вы можете фильтровать несколько значений с параметром .

Пример

Запрос челленджей с неудачным результатом:

{
challenges(where: { outcome: "failed" }) {
challenger
outcome
application {
id
}
}
}

Для сравнения значений можно использовать суффиксы типа , :

Пример

{
applications(where: { deposit_gt: "10000000000" }) {
id
whitelisted
deposit
}
}

Полный список суффиксов параметров:

_not
_gt
_lt
_gte
_lte
_in
_not_in
_contains
_not_contains
_starts_with
_ends_with
_not_starts_with
_not_ends_with

Time-travel запросы

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

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

Пример

{
challenges(block: { number: 8000000 }) {
challenger
outcome
application {
id
}
}
}

Этот запрос вернет сущности и связанные с ними сущности , которые существовали непосредственно после обработки блока номер 8,000,000.

Пример

{
challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) {
challenger
outcome
application {
id
}
}
}

Полнотекстовые поисковые запросы

Поля полнотекстового поиска предоставляют API текстового поиска, который можно добавить в схему подграфа и настроить. См. Определение полей полнотекстового поиска, чтобы добавить полнотекстовый поиск в свой подграф.

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

Схема

Схема вашего источника данных, то есть типы сущностей, значения и отношения, доступные для запроса, определяются через язык описания интерфейсов GraphQL (IDL).

Схемы GraphQL обычно определяют корневые типы для , and . The Graph поддерживает только . Корневой тип для вашего подграфа автоматически генерируется из схемы GraphQL, включенной в манифест подграфа.

Примечание. Наш API не обнаруживает мутаций, потому что от разработчиков ожидается, что они будут выполнять транзакции непосредственно в базовом блокчейне из своих приложений.

Сущности

Все типы GraphQL с директивами в вашей схеме будут рассматриваться как объекты и должны иметь поле .

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

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store