Документация / 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 есть встроенный способ вынести динамические значения из запроса и передать их отдельным словарём. Эти значения называются переменными.
Чтобы использовать переменные, нужно:
- заменить статическое значение в запросе на
$variableName; - объявить
$variableNameодной из переменных, которые принимает запрос; - передать
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 г.
