Документация / 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 г.