> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL mutations

> Learn how to create and update instances using GraphQL mutations including upsert and delete operations.

You can create and update instances using GraphQL. The mutation capabilities available from the GraphQL API represent a subset of the capabilities of the [ingestion](/cdf/dm/dm_concepts/dm_ingestion) REST API endpoints. The GraphQL interface for data modeling doesn't anticipate receiving significant data ingestion traffic. For that, please use the DMS REST API, or the CDF Transformations service.

For a data model like the example below, mutations are generated for each type, except types annotated with the `@edge` directive:

```graphql wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
type Movie {
  title: String
  actors: [Person]
    @relation(
      edgeSource: "ActedIn"
      type: { space: "imdb", externalId: "HAS_ACTOR" }
      direction: OUTWARDS
    )
  director: Person
}

type Person {
  name: String!
}

type ActedIn @edge {
  role: String
  compensation: Float
  metadata: JSONObject
  lines: [String]
}
```

## `upsert` mutations

The mutations receive a list of instances you want to create for a specific type. For example:

```graphql wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
mutation CreateMovie {
  upsertMovie(
    items: [
      { space: "imdb", externalId: "the-prestige", title: "The Prestige" }
      { space: "imdb", externalId: "the-titanic", title: "The Titanic" }
    ]
  ) {
    externalId
    space
    createdTime
  }
}
```

You can extend the mutations to create or upsert nested types. When you upsert nested types, the input has a structure with `node` and `edge`. Direct relations only require `node`.

`node` includes the fields for the target type, while `edge` include the fields for the connecting edge. The edge could contain properties, if an edge type is defined in the model, or could be simply `space` and `externalId`. It's similar for direct relations, though only `node` should be included, no `edge`.

A more complex example could look like this:

```graphql wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
mutation CreateMoviesWithActors {
  upsertMovie(
    items: [
      {
        space: "imdb"
        externalId: "the-prestige"
        title: "The Prestige"
        director: {
          node: {
            space: "imdb"
            externalId: "christopher-nolan"
            name: "Christopher Nolan"
          }
        }
        actors: [
          {
            edge: {
              space: "imdb"
              externalId: "prestige-christian-bale"
              role: "Alfred Borden"
              compensation: 10000000
              lines: ["Are you watching closely?"]
            }
            node: {
              space: "imdb"
              externalId: "christian-bale"
              name: "Christian Bale"
            }
          }
          {
            edge: {
              space: "imdb"
              externalId: "prestige-hugh-jackman"
              role: "Robert Angier"
              compensation: 10000000
              lines: ["No one cares about the man in the box"]
            }
            node: {
              space: "imdb"
              externalId: "hugh-jackman"
              name: "Hugh Jackman"
            }
          }
        ]
      }
    ]
  ) {
    externalId
    space
    createdTime
    lastUpdatedTime
  }
}
```

<Tip>
  You can remove a direct relationship by setting its property to `null`. For example, to remove a
  director from a movie, set the director property to `{... director:null, ...}`.
</Tip>

* **Properties**

  * `externalId`
  * `space`
  * `createdTime`
  * `lastUpdatedTime`
  * `wasModified`: a `Boolean` to specify whether an existing instance was modified or a new
    instance was created, or an instance was unchanged.
  * `instanceType`: `node` or `edge`
  * `version`

* **Parameters**

  * `items`: a list of the instances to upsert. This has the shape of the type being upserted. Any nested items have the `node` field to contain the properties of the target type. Relations also have the `edge` field to contain edge properties.