Документация / GraphQL
Изменения (mutation)
Обычно о GraphQL говорят как о способе получать данные, но любой полноценной платформе данных нужно и изменять данные на сервере.
В REST любой запрос может вызвать побочные эффекты на сервере, но по соглашению запросы GET не используют для
изменения данных. В GraphQL похоже: технически любой резолвер поля может записывать данные, но
спецификация GraphQL требует: «вычисление полей, кроме
полей верхнего уровня изменения, всегда должно быть без побочных эффектов и идемпотентным». Поэтому в схемах по
спецификации побочные эффекты допустимы только у полей верхнего уровня операций mutation.
На этой странице разобрано, как записывать данные операциями изменения так, чтобы это было удобно клиентам.
Всё, что относится к запросам, относится и к изменениям, поэтому сначала прочитайте страницу «Запросы».
Добавление данных
Чтобы создать данные через REST API, отправляют запрос POST на определённый адрес и передают в теле запроса
сведения о создаваемых сущностях. В GraphQL подход другой.
Рассмотрим пример изменения, определённого в схеме:
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
input ReviewInput {
stars: Int!
commentary: String
}
type Mutation {
createReview(episode: Episode, review: ReviewInput!): Review
}
Как и поля запросов, поля изменений добавляются в один из корневых типов операций —
точек входа в API. Здесь поле createReview определено в типе Mutation.
Поля изменений тоже принимают аргументы. У аргумента review входной тип ReviewInput — это
входной тип, который позволяет передать изменению структурированный
объект, а не только отдельные скалярные значения.
Как и в запросах, если поле изменения возвращает объектный тип, в операции нужно указать набор его полей:
mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
createReview(episode: $ep, review: $review) {
stars
commentary
}
}
Переменные:
{
"ep": "JEDI",
"review": {
"stars": 5,
"commentary": "Отличный фильм!"
}
}
Ответ:
{
"data": {
"createReview": {
"stars": 5,
"commentary": "Отличный фильм!"
}
}
}
Поле createReview может возвращать любой допустимый выходной тип схемы, но принято возвращать тип того, что
изменилось, — здесь Review. Это удобно клиентам, которым после изменения нужно новое состояние объекта.
GraphQL работает с вашим существующим кодом и данными, поэтому как именно создаётся отзыв, когда клиент
отправляет эту операцию, решаете вы. Функция, которая записывает новый отзыв в базу данных при изменении
createReview, могла бы выглядеть так:
const Mutation = {
createReview(_obj, args, context, _info) {
return context.db
.createNewReview(args.episode, args.review)
.then(reviewData => new Review(reviewData));
},
};
О том, как GraphQL получает данные полей, — на странице «Выполнение».
Обновление данных
Изменениями же обновляют существующие данные. Чтобы изменить имя человека, определим новое поле изменения с
выходным типом Human — так после успешной записи клиент получит обновлённые сведения:
type Mutation {
updateHumanName(id: ID!, name: String!): Human
}
Эта операция изменит имя Люка Скайуокера:
mutation UpdateHumanName($id: ID!, $name: String!) {
updateHumanName(id: $id, name: $name) {
id
name
}
}
Переменные:
{
"id": "1000",
"name": "Luke Starkiller"
}
Ответ:
{
"data": {
"updateHumanName": {
"id": "1000",
"name": "Luke Starkiller"
}
}
}
Узкоспециализированные изменения
Предыдущий пример показывает важное отличие от REST. Чтобы обновить свойства человека через REST API, вы, скорее
всего, отправили бы изменённые данные запросом PATCH на общий адрес ресурса. В GraphQL вместо одного общего
изменения updateHuman можно определить более конкретные поля — например, updateHumanName, — рассчитанные на
конкретную задачу.
Узкоспециализированные поля делают схему выразительнее: их аргументы могут быть обязательными (общему изменению
updateHuman пришлось бы принимать много необязательных аргументов на разные случаи). Требования, записанные в
схеме, избавляют и от отдельной логики, которая проверяла бы, что для нужной клиенту записи переданы подходящие
значения.
GraphQL позволяет выразить и связи между данными, которые трудно смоделировать обычным запросом в стиле CRUD.
Например, пользователь хочет сохранить личную оценку фильма. Оценка принадлежит пользователю и ничего не меняет в
самом фильме, но её удобно связать с объектом Film:
mutation RateFilm($episode: Episode!, $rating: FilmRating!) {
rateFilm(episode: $episode, rating: $rating) {
episode
viewerRating
}
}
Переменные:
{
"episode": "EMPIRE",
"rating": "THUMBS_UP"
}
Ответ:
{
"data": {
"rateFilm": {
"episode": "EMPIRE",
"viewerRating": "THUMBS_UP"
}
}
}
Общее правило: API GraphQL проектируют так, чтобы клиентам было удобно получать и менять данные, поэтому поля схемы определяются сценариями их использования.
Удаление данных
Как в REST API ресурс удаляют запросом DELETE, так и в GraphQL можно удалять данные изменением — ещё одним
полем типа Mutation:
type Mutation {
deleteStarship(id: ID!): ID!
}
Пример использования:
mutation DeleteStarship($id: ID!) {
deleteStarship(id: $id)
}
Переменные:
{
"id": "3003"
}
Ответ:
{
"data": {
"deleteStarship": "3003"
}
}
Как и для создания и обновления, спецификация GraphQL не говорит, что должно вернуть успешное удаление, но какой-то выходной тип у поля в схеме указать нужно. Обычно возвращают идентификатор удалённой сущности или payload-объект со сведениями о ней — это и сигнал об успехе операции.
Несколько полей в изменении
Изменение, как и запрос, может содержать несколько полей. Но кроме названия между ними есть важное отличие:
поля запроса выполняются параллельно, а поля изменения — последовательно.
Пример:
mutation {
firstShip: deleteStarship(id: "3001")
secondShip: deleteStarship(id: "3002")
}
Ответ:
{
"data": {
"firstShip": "3001",
"secondShip": "3002"
}
}
Последовательное выполнение полей верхнего
уровня означает: если в одном запросе два изменения deleteStarship, первое гарантированно завершится до начала
второго, и мы не устроим гонку сами с собой.
Последовательное выполнение полей Mutation — не то же самое, что транзакция базы данных. Одни поля изменения
могут выполниться успешно, другие — вернуть ошибку, и откатить успешную часть операции GraphQL не может. Если в
примере выше первый корабль удалён, а поле secondShip вернуло ошибку, встроенного способа отменить уже
выполненное поле firstShip в GraphQL нет.
Итоги
Подведём итоги об изменениях:
- клиенты создают, обновляют и удаляют данные через API GraphQL — в пределах возможностей, открытых в схеме;
- изменения можно проектировать под конкретные сценарии записи, исходя из потребностей клиентов;
- поля верхнего уровня типа
Mutationвыполняются последовательно, в отличие от полей других типов, которые часто выполняются параллельно.
Теперь, умея читать и записывать данные, переходите к получению данных в реальном времени — подпискам.
Похожие инструменты
Обновлено: 17 октября 2026 г.
