Union types

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

The Neo4j GraphQL Library supports the use of unions on relationship fields.

As an example, consider the following schema. It defines a User type that has a relationship HAS_CONTENT, of type [Content!]!. Content is of type union, representing either a Blog or a Post:

union Content = Blog | Post

type Blog @node {
    title: String
    posts: [Post!]! @relationship(type: "HAS_POST", direction: OUT)
}

type Post @node {
    content: String
}

type User @node {
    name: String
    content: [Content!]! @relationship(type: "HAS_CONTENT", direction: OUT)
}

Creating a union

To create the union featured in the example, you need to do this mutation:

mutation CreateUserAndContent {
    createUsers(
        input: [
            {
                name: "Dan"
                content: {
                    Blog: {
                        create: [
                            {
                                node: {
                                    title: "My Cool Blog"
                                    posts: {
                                        create: [
                                            {
                                                node: {
                                                    content: "My Cool Post"
                                                }
                                            }
                                        ]
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        ]
    ) {
        users {
            name
        }
    }
}

Querying a union

Which union members are returned by a query are dictated by the where filter applied to the query. The following example returns all user content, more specifically the title of each blog:

query GetUsersWithBlogs {
    users {
        name
        content {
            ... on Blog {
                title
            }
        }
    }
}

While this particular query only returns blogs, you could for instance use a filter to check that the title is not null when the list of blogs is returned:

query GetUsersWithAllContent {
    users {
        name
        content(where: { Blog: { NOT: { title_EQ: null } }}) {
            ... on Blog {
                title
            }
        }
    }
}

This also helps with preventing overfetching.