Skip to main content

GraphQL mutations

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 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:

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:

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:

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, ...}.

  • 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.
Last updated