Документация / GraphQL

Запросы

В GraphQL три основных вида операций — запросы (query), изменения (mutation) и подписки (subscription). Несколько простых запросов уже встречались выше; на этой странице подробно разобраны возможности операций query для чтения данных с сервера.

Поля

В простейшем случае GraphQL — это запрос определённых полей у объектов. Начнём с поля hero, определённого в типе Query схемы:

type Query {
  hero: Character
}

Посмотрим, что вернёт запрос этого поля:

{
  hero {
    name
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}

Документ GraphQL всегда начинается с корневого типа операции (здесь — объектного типа Query), потому что он — точка входа в API. Дальше указывается набор выбора (selection set) — нужные поля вплоть до листьев, то есть скаляров или перечислений. Поле name возвращает тип String — здесь имя главного героя «Звёздных войн», "R2-D2".

По спецификации GraphQL результат запроса возвращается в ключе data верхнего уровня ответа. Если при обработке запроса возникли ошибки, сведения о них будут в ключе errors верхнего уровня. Видно, что форма результата совпадает с формой запроса. Это суть GraphQL: вы всегда получаете то, что ожидаете, а сервер точно знает, какие поля запросил клиент.

В предыдущем примере запрашивалось только имя героя — строка String, но поля могут возвращать и объектные типы (и списки объектов). Тогда у такого объекта выбирают вложенные поля — подвыборку:

{
  hero {
    name
    friends {
      name
    }
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

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

Обратите внимание: поле friends возвращает массив. Запросы GraphQL выглядят одинаково для одного объекта и для списка — что именно придёт, видно по схеме.

Аргументы

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

type Query {
  human(id: ID!): Human
}

Клиент должен передать в запросе обязательное значение id:

{
  human(id: "1000") {
    name
    height
  }
}

Ответ:

{
  "data": {
    "human": {
      "name": "Luke Skywalker",
      "height": 1.72
    }
  }
}

В REST можно передать только один набор аргументов — параметры запроса и сегменты URL. В GraphQL свой набор аргументов может получить каждое поле и каждый вложенный объект, поэтому GraphQL полностью заменяет несколько обращений к API.

Аргументы можно передавать даже полям, которые возвращают скаляры, — например, чтобы преобразовать данные один раз на сервере, а не в каждом клиенте отдельно:

{
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}

Ответ:

{
  "data": {
    "human": {
      "name": "Luke Skywalker",
      "height": 5.6430448
    }
  }
}

Аргументы бывают разных типов. В примере выше — перечисление: одно значение из конечного набора (здесь единицы длины, METER или FOOT). В GraphQL есть набор встроенных типов, но сервер может объявить и свои — лишь бы их можно было сериализовать в формат передачи.

Подробнее о системе типов GraphQL.

Тип и имя операции

В примерах выше использовалась краткая запись: слово query перед набором выбора опущено. Кроме явного типа операции можно указать и уникальное имя операции — в боевых приложениях оно упрощает отладку и трассировку.

Пример с ключевым словом query в роли типа операции и именем операции HeroNameAndFriends:

query HeroNameAndFriends {
  hero {
    name
    friends {
      name
    }
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Тип операции — query, mutation или subscription — описывает, что вы собираетесь сделать. Ключевое слово обязательно, если не используется краткая запись запроса (для изменений и подписок оно обязательно всегда). А чтобы дать операции имя, тип операции тоже нужно указать.

Имя операции — явное имя, которое вы ей даёте; выбирайте осмысленное. Оно обязательно, если в одном документе несколько операций, но и для единственной операции его рекомендуется задавать: имена помогают при отладке и в журналах сервера. Когда что-то идёт не так (ошибки видны в журнале сети или в журнале сервера GraphQL), запрос проще найти в коде по имени, чем разбирать его содержимое.

Это как имя функции в любимом языке программирования. В JavaScript можно обходиться одними анонимными функциями, но функцию с именем проще найти, отладить и записать в журнал её вызовы. Точно так же имена запросов и изменений GraphQL, как и имена фрагментов, помогают на сервере различать запросы.

Псевдонимы

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

query {
  empireHero: hero(episode: EMPIRE) {
    name
  }
  jediHero: hero(episode: JEDI) {
    name
  }
}

Ответ:

{
  "data": {
    "empireHero": {
      "name": "Luke Skywalker"
    },
    "jediHero": {
      "name": "R2-D2"
    }
  }
}

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

Переменные

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

Подставлять такие значения прямо в текст запроса — плохая идея: клиентскому коду пришлось бы на ходу собирать строку запроса и сериализовать значения в формат GraphQL. Вместо этого в GraphQL есть встроенный способ вынести динамические значения из запроса и передать их отдельным словарём. Эти значения называются переменными.

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

  1. заменить статическое значение в запросе на $variableName;
  2. объявить $variableName одной из переменных, которые принимает запрос;
  3. передать variableName: value в отдельном словаре переменных — его формат зависит от транспорта, обычно это JSON.

Всё вместе выглядит так:

query HeroNameAndFriends($episode: Episode) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

Переменные:

{
  "episode": "JEDI"
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

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

Теперь клиенту достаточно передать другую переменную, а не собирать новый запрос. Это и хорошая практика: так видно, какие аргументы запроса динамические. Никогда не собирайте запросы подстановкой строк из значений, введённых пользователем.

Объявление переменных

Объявление переменных — часть вида ($episode: Episode) в запросе выше. Оно работает как объявление параметров функции в типизированном языке: перечисляются все переменные с префиксом $ и их типы — здесь Episode.

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

Переменные бывают необязательными и обязательными. В примере выше рядом с типом Episode нет !, значит, переменная необязательная. Но если поле, в которое передаётся переменная, требует обязательный аргумент, то и переменная должна быть обязательной.

Синтаксис объявления переменных проще понять, зная язык описания схемы (SDL) — он подробно разобран на странице «Схема и типы».

Значения по умолчанию

Переменным в запросе можно задать значения по умолчанию — после объявления типа:

query HeroNameAndFriends($episode: Episode = JEDI) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Если значения по умолчанию заданы для всех переменных, запрос можно выполнить, не передавая переменных вовсе. Переданные в словаре переменные заменяют значения по умолчанию.

Фрагменты

Допустим, в приложении есть довольно сложная страница: два героя рядом, вместе с их друзьями. Такой запрос быстро усложнится — поля пришлось бы повторять как минимум дважды, по разу для каждой стороны сравнения.

Поэтому в GraphQL есть повторно используемые части — фрагменты. Фрагмент задаёт набор полей, который затем включают в запросы там, где он нужен. Так эту задачу решают фрагментами:

query {
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  appearsIn
  friends {
    name
  }
}

Ответ:

{
  "data": {
    "leftComparison": {
      "name": "Luke Skywalker",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "friends": [
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        },
        {
          "name": "C-3PO"
        },
        {
          "name": "R2-D2"
        }
      ]
    },
    "rightComparison": {
      "name": "R2-D2",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

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

Переменные во фрагментах

Фрагменты могут обращаться к переменным, объявленным в операции:

query HeroComparison($first: Int = 3) {
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  friendsConnection(first: $first) {
    totalCount
    edges {
      node {
        name
      }
    }
  }
}

Ответ:

{
  "data": {
    "leftComparison": {
      "name": "Luke Skywalker",
      "friendsConnection": {
        "totalCount": 4,
        "edges": [
          {
            "node": {
              "name": "Han Solo"
            }
          },
          {
            "node": {
              "name": "Leia Organa"
            }
          },
          {
            "node": {
              "name": "C-3PO"
            }
          }
        ]
      }
    },
    "rightComparison": {
      "name": "R2-D2",
      "friendsConnection": {
        "totalCount": 3,
        "edges": [
          {
            "node": {
              "name": "Luke Skywalker"
            }
          },
          {
            "node": {
              "name": "Han Solo"
            }
          },
          {
            "node": {
              "name": "Leia Organa"
            }
          }
        ]
      }
    }
  }
}

Встроенные фрагменты

Как и многие системы типов, схемы GraphQL позволяют определять интерфейсы и объединения. Подробнее о них — на странице «Интерфейсы, объединения и входные типы».

Если запрашивается поле, которое возвращает интерфейс или объединение, то для данных конкретного типа нужны встроенные фрагменты (inline fragments). Проще всего показать на примере:

query HeroForEpisode($ep: Episode!) {
  hero(episode: $ep) {
    name
    ... on Droid {
      primaryFunction
    }
    ... on Human {
      height
    }
  }
}

Переменные:

{
  "ep": "JEDI"
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "primaryFunction": "Astromech"
    }
  }
}

Здесь поле hero возвращает тип Character — в зависимости от аргумента episode это Human или Droid. Напрямую можно запросить только поля интерфейса Character, например name.

Чтобы запросить поле конкретного типа, нужен встроенный фрагмент с условием на тип. Первый фрагмент помечен ... on Droid, поэтому поле primaryFunction выполняется, только если hero вернул Character типа Droid. Так же и поле height — для типа Human.

Именованные фрагменты работают так же: у именованного фрагмента всегда есть тип.

Мета-поля

Как видно на примере объединений, иногда заранее неизвестно, какой тип вернёт сервис GraphQL, и клиенту нужно как-то понять, как обрабатывать данные.

В любом месте запроса можно запросить мета-поле __typename — имя объектного типа в этой точке:

{
  search(text: "an") {
    __typename
    ... on Human {
      name
    }
    ... on Droid {
      name
    }
    ... on Starship {
      name
    }
  }
}

Ответ:

{
  "data": {
    "search": [
      {
        "__typename": "Human",
        "name": "Han Solo"
      },
      {
        "__typename": "Human",
        "name": "Leia Organa"
      },
      {
        "__typename": "Starship",
        "name": "TIE Advanced x1"
      }
    ]
  }
}

Здесь search возвращает объединение одного из трёх типов. Без поля __typename клиент не смог бы их различить.

Все имена полей, которые начинаются с двух подчёркиваний (__), зарезервированы GraphQL. Кроме __typename, сервисы GraphQL предоставляют мета-поля __schema и __type — это система интроспекции.

Директивы

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

Составим запрос для такого компонента:

query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

Переменные:

{
  "episode": "JEDI",
  "withFriends": false
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}

С переменной withFriends, равной true, в ответ попадут и друзья:

query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

Переменные:

{
  "episode": "JEDI",
  "withFriends": true
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Здесь использована директива. Точнее, исполняемая директива: клиент ставит её у поля или включения фрагмента, и она может влиять на выполнение запроса так, как решит сервер. В основной спецификации GraphQL ровно две такие директивы — их обязана поддерживать любая реализация сервера по спецификации:

  • @include(if: Boolean) — включить поле в результат, только если аргумент равен true;
  • @skip(if: Boolean) — пропустить поле, если аргумент равен true.

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

Как объявлять директивы, которыми размечают типы, поля и аргументы схемы, — на странице «Директивы и документирование».

Итоги

Подведём итоги о запросах:

  • операция GraphQL для чтения данных начинается с корневого типа query и проходит по полям набора выбора до листьев — скаляров или перечислений;
  • поля принимают аргументы, которые меняют результат поля;
  • тип операции указывается ключевыми словами query, mutation или subscription;
  • ключевое слово типа операции можно опустить только у некоторых запросов query;
  • операциям стоит давать уникальные имена: запросы становятся понятнее, отладка — проще;
  • псевдонимы полей переименовывают ключи ответа и позволяют запросить одно поле несколько раз с разными аргументами;
  • переменные начинаются с символа $ и передают динамические значения в аргументы полей;
  • фрагмент — повторно используемый набор полей, который можно включать в разные запросы;
  • исполняемые директивы в запросе меняют результат при выполнении запроса на сервере;
  • все серверы GraphQL по спецификации поддерживают встроенные директивы @include и @skip.

Теперь, разобравшись, как читать данные запросами, узнаем, как менять данные и вызывать побочные эффекты изменениями.

Обновлено: 17 октября 2026 г.