Документация / GraphQL
Подписки (subscription)
Кроме чтения и записи данных операциями запросов и изменений, которые не хранят состояние, спецификация GraphQL описывает и получение обновлений в реальном времени по долгоживущим запросам. На этой странице разобрано, как клиенты подписываются на события сервера GraphQL операциями подписки.
Многое из того, что относится к запросам, относится и к подпискам, поэтому сначала прочитайте страницу «Запросы».
Подписка на обновления
Поля подписок определяются точно так же, как поля Query и Mutation, но в корневом типе subscription:
type Subscription {
reviewCreated: Review
}
Подписка начинается ключевым словом subscription в роли типа операции:
subscription NewReviewCreated {
reviewCreated {
rating
commentary
}
}
Обычно за подписками GraphQL стоит отдельная система публикации и подписки (pub/sub): сообщения об изменении данных публикуются в ней по мере необходимости, а резолверы полей подписки их получают.
Для примера выше: когда клиент отправляет новый отзыв изменением createReview, в систему pub/sub публикуется
сообщение REVIEW_CREATED, а резолвер поля подписки reviewCreated слушает это событие и отправляет данные
подписанным клиентам.
Подписки — не то же самое, что живые запросы (live queries): нестрого определённая возможность, которую предлагают некоторые реализации GraphQL. Обсуждение формальной спецификации живых запросов.
Как и для запросов и изменений, GraphQL не задаёт транспортный протокол — его выбирает сервер. На практике подписки часто реализуют через WebSocket или server-sent events (SSE). Клиенты, которые отправляют подписки, тоже должны поддерживать выбранный протокол. Сообщество поддерживает спецификации подписок GraphQL через WebSocket и server-sent events.
Важное отличие подписок: документ может содержать несколько разных операций подписки с разными корневыми полями, но у каждой операции должно быть ровно одно корневое поле.
Например, такая операция некорректна:
subscription {
reviewCreated {
rating
commentary
}
humanFriendsUpdated {
name
friends {
name
}
}
}
А такой документ корректен:
subscription NewReviewCreated {
reviewCreated {
rating
commentary
}
}
subscription FriendListUpdated($id: ID!) {
humanFriendsUpdated(id: $id) {
name
friends {
name
}
}
}
Как и с запросами и изменениями, в документе несколько операций, поэтому у каждой должно быть имя, а в запросе к серверу нужно указать имя выполняемой операции.
Подписки в масштабе
Подписки — мощная возможность GraphQL, но реализовать их сложнее, чем запросы и изменения: документ GraphQL, переменные и прочий контекст нужно хранить всё время жизни подписки. Это непросто при горизонтальном масштабировании серверов GraphQL — каждый подписанный клиент должен быть привязан к конкретному экземпляру сервера.
Клиентским библиотекам для таких операций тоже обычно нужны более сложные механизмы: повторная подписка при обрыве соединения, обработка гонок между начальным запросом и обновлениями из подписки.
На практике API GraphQL с подписками требует более сложной архитектуры, чем API только с запросами и изменениями. Её устройство зависит от реализации GraphQL, системы pub/sub, выбранного транспорта, а также от требований к доступности, масштабируемости и безопасности данных реального времени.
Подписки хорошо подходят для данных, которые меняются часто и понемногу, и для клиентов, которым эти изменения нужны почти в реальном времени. Если данные обновляются реже, держать интерфейс клиента в актуальном состоянии лучше периодическим опросом, push-уведомлениями на мобильных устройствах или повторными запросами по действиям пользователя.
Итоги
Подведём итоги о подписках:
- операции подписки GraphQL доставляют клиенту обновления данных по долгоживущим запросам;
- подписки обычно работают поверх протокола с состоянием, поэтому реализовать и поддерживать их сложнее, чем запросы и изменения;
- подписки лучше всего подходят там, где клиенту нужен поток частых и небольших обновлений.
Мы разобрали все три вида операций GraphQL; дальше — как сервер GraphQL проверяет запросы клиентов.
Похожие инструменты
Обновлено: 17 октября 2026 г.
