We just launched our new Hygraph Studio in beta. Learn more

Hygraph
Docs

Mutations

Your project endpoint exposes GraphQL mutations you can use to modify the contents of your project. The mutations API allows you to interact with content outside of the Hygraph UI using GraphQL.

#Auto-generated mutations

When a new model is added to your project, so are custom GraphQL mutations.

For example, if you created a Product model, these mutations would also be generated inside your GraphQL schema:

  • createProduct
  • updateProduct
  • deleteProduct
  • upsertProduct
  • publishProduct
  • unpublishProduct
  • updateManyProductsConnection
  • deleteManyProductsConnection
  • publishManyProductsConnection
  • unpublishManyProductsConnection

All of these mutations accept input types that are specific to your projects GraphQL schema.

As an example, these are the mutations that are added to the Hygraph GraphQL schema for a model called Author:

createAuthor(data: AuthorCreateInput!): Author
updateAuthor(where: AuthorWhereUniqueInput!, data: AuthorUpdateInput!): Author
deleteAuthor(where: AuthorWhereUniqueInput!): Author
upsertAuthor(
where: AuthorWhereUniqueInput!
upsert: AuthorUpsertInput!
): Author
publishAuthor(
where: AuthorWhereUniqueInput!
to: [Stage!]! = [PUBLISHED]
): Author
unpublishAuthor(
where: AuthorWhereUniqueInput!
from: [Stage!]! = [PUBLISHED]
): Author
updateManyAuthorsConnection(
where: AuthorManyWhereInput
data: AuthorUpdateManyInput!
skip: Int
first: Int
last: Int
before: ID
after: ID
): AuthorConnection!
deleteManyAuthorsConnection(
where: AuthorManyWhereInput
skip: Int
first: Int
last: Int
before: ID
after: ID
): AuthorConnection!
publishManyAuthorsConnection(
where: AuthorManyWhereInput
from: Stage = DRAFT
to: [Stage!]! = [PUBLISHED]
skip: Int
first: Int
last: Int
before: ID
after: ID
): AuthorConnection!
unpublishManyAuthorsConnection(
where: AuthorManyWhereInput
stage: Stage = DRAFT
from: [Stage!]! = [PUBLISHED]
skip: Int
first: Int
last: Int
before: ID
after: ID
): AuthorConnection!

#Create entries

When creating new content entries, the data argument will have an associated input type that is specific to your content model.

For example, if your project contains the model Product, you will have:

MutationArgumentInput Type
createProductdataProductCreateInput!

The id is a default system field that is automatically generated for all new entries.

#Update entries

When updating single content entry, you must specify the unique where criteria of which you want to update, as well as the new data.

For example, if your project contains the model Product, you will have:

ArgumentInput Type
whereProductWhereUniqueInput!
dataProductUpdateInput!

#Upsert entries

The upsert mutation allows you to create, or update a content entry based on whether the unique where values exist.

For example, if your project contains the model Product, you will have:

ArgumentInput Type
whereProductWhereUniqueInput!
upsertProductUpsertInput!
upsert > createProductCreateInput!
upsert > updateProductUpdateInput!

#Delete entries

Similar to updating, and upserting entries, you can specify using where the entries you want to delete.

For example, if your project contains the model Product, you will have:

ArgumentInput Type
whereProductWhereUniqueInput!

#Nested mutations

  • create: Create and relate entries
  • connect: Connect additional existing entries by unique field
  • update: Update the connected entries
  • upsert: Create or update connected entries
  • disconnect: Disconnect connected relations by unique field
  • delete: Delete all connected entries
  • set: Override all connected entries

#Create

#Update

#Insert at position

When inserting related entries, you can connect entries at a given position. The position of entries reflects that fetching relations.

The position input accepts the following values:

FieldTypeDefinition
beforeIDThe ID of the entry you want to insert before
afterIDThe ID of the entry you want to insert after
startBooleanSet to true if you want to insert at the start
endBooleanSet to true if you want to insert at the end

Before

mutation {
updateAuthor(
where: { id: "..." }
data: { posts: { connect: { position: { before: "..." } } } }
) {
id
}
}

After

mutation {
updateAuthor(
where: { id: "..." }
data: { posts: { connect: { position: { after: "..." } } } }
) {
id
}
}

Start

mutation {
updateAuthor(
where: { id: "..." }
data: { posts: { connect: { position: { start: true } } } }
) {
id
}
}

End

mutation {
updateAuthor(
where: { id: "..." }
data: { posts: { connect: { position: { end: true } } } }
) {
id
}
}

#Publishing content mutations

Hygraph automatically generates publish, and unpublish mutations for each of your content models, including the asset model.

Learn more about publishing and unpublishing content.

#Batch mutations

Hygraph supports batch mutations that can be applied to "many" entries at once. You may wish to update, or delete many entries at once that fit given criteria.

Batch mutations comply with the Relay connection type specification.

#Update many

To update many entries at once, you must use the updateMany[Model]Connection mutation. You can use where, or pagination filters to set the criteria you wish to update.

ArgumentInput TypeDescription
whereProductManyWhereInputFiltering criteria for entries you want to update.
dataCreateInput!An object that specifies the data you'd like to update matching entries with.
firstIntSeek forwards from end of result set.
lastIntSeek backwards from start of result set.
skipIntSkip result set by given amount.
beforeIDSeek backwards before specific ID.
afterIDSeeks forwards after specific ID.

For example, let's update all products where featured: true, to be featured: false.

#Delete many

To delete many entries at once, you must use the deleteMany[Model]Connection mutation. You can use where, or pagination filters to set the criteria you wish to delete.

ArgumentInput TypeDescription
whereProductManyWhereInputFiltering criteria for entries you want to delete.
firstIntSeek forwards from end of result set.
lastIntSeek backwards from start of result set.
skipIntSkip result set by given amount.
beforeIDSeek backwards before specific ID.
afterIDSeeks forwards after specific ID.

#Publish many

Just like you can publish content, you can also batch publish.

ArgumentInput TypeDescription
whereProductManyWhereInputFiltering criteria finding entries.
fromStage = DRAFTThe content stage to find entries from.
to[Stage!]! = [PUBLISHED]The target published content stage.
firstIntSeek forwards from end of result set.
lastIntSeek backwards from start of result set.
skipIntSkip result set by given amount.
beforeIDSeek backwards before specific ID.
afterIDSeeks forwards after specific ID.

For example, we could publish the first 5 products to the PUBLISHED stage.

#Unpublish many

Just like you can batch publish, you can also batch unpublish.

ArgumentInput TypeDescription
whereProductManyWhereInputFiltering criteria for entries you want to find.
stageStage = DRAFTThe content stage to find entries in.
to[Stage!]! = [PUBLISHED]The target published content stage.
firstIntSeek forwards from end of result set.
lastIntSeek backwards from start of result set.
skipIntSkip result set by given amount.
beforeIDSeek backwards before specific ID.
afterIDSeeks forwards after specific ID.

#Localized content mutations

Depending on whether or not you have localized fields in your schema, you will be able to mutate each of the localized content entries.

Learn more about mutating localized content.

#Rich Text mutations

Like every other content model, and field type inside Hygraph, you can also mutate data using the Mutations API.

When you save content, it is saved as an abstract syntax tree (AST), and can be queried in the format of HTML, Markdown, Text, and the "raw" AST itself (JSON). The AST is based on Slate.

To mutate Rich Text, you will need to pass it to Hygraph in Slate AST nodes format.

Here's an example: