create

This is the documentation of the GraphQL Library version 7. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

Consider the following type definitions:

type Post @node {
    id: ID! @id
    content: String!
    creator: User! @relationship(type: "HAS_POST", direction: IN)
}

type User @node {
    id: ID! @id
    name: String
    posts: [Post!]! @relationship(type: "HAS_POST", direction: OUT)
}

The following create mutations and response types are generated:

type CreatePostsMutationResponse {
    posts: [Post!]!
}

type CreateUsersMutationResponse {
    users: [User!]!
}

type Mutation {
    createPosts(input: [PostCreateInput!]!): CreatePostsMutationResponse!
    createUsers(input: [UsersCreateInput!]!): CreateUsersMutationResponse!
}

Note that the CreateInput types closely mirror the object type definitions. This allows you to create not only the type in question, but to recurse down and perform further operations on related types in the same mutation.

The id field is absent from both create input types as the @id directive has been used.

Single create

A single User can be created by executing the following GraphQL statement:

mutation {
    createUsers(input: [
        {
            name: "John Doe"
        }
    ]) {
        users {
            id
            name
        }
    }
}

This creates a User with the name "John Doe". The name and the autogenerated ID are returned.

Nested create

You can create a User and their initial Post at once by executing the following:

mutation {
    createUsers(input: [
        {
            name: "John Doe"
            posts: {
                create: [
                    {
                        node: {
                            content: "Hi, my name is John!"
                        }
                    }
                ]
            }
        }
    ]) {
        users {
            id
            name
            posts {
                id
                content
            }
        }
    }
}

This creates a User with name "John Doe" and an introductory post. Both are returned with their autogenerated IDs.

create optimization

With create operations, there is no limit on how many nodes can be created at once. However, there is a known performance issue for large batch sizes.

The Neo4j GraphQL Library contains an optimization feature designed to mitigate it, but it does not work in the following scenarios:

  • A field is populated using the directive @populated_by.

  • The connect operations are used.

  • Interface and union types are present in the mutation.