Autogeneration

This page describes directives used for autogeneration:

`@id`

This directive marks a field as an identifier for an object type. This enables autogeneration of IDs for the field.

The format of each generated ID is a UUID generated by randomUUID() function. The field will not be present in input types for mutations.

It is recommended to use @unique in conjunction with this to add a unique node property constraint.

Definition

"""Indicates that the field is an identifier for the object type."""
directive @id on FIELD_DEFINITION

Usage

The following type definition specifies the id field as an autogenerated value:

type User {
    id: ID! @id
    username: String!
}

`@timestamp`

This directive marks a field as a timestamp field, which can be used to store timestamps of when particular events happen through the GraphQL API.

These events are triggered and stored at the GraphQL API layer. Events happening in your database through other routes do not trigger updates of these timestamps.

Definition

enum TimestampOperation {
    CREATE
    UPDATE
}

"""Instructs @neo4j/graphql to generate timestamps on particular events, which will be available as the value of the specified field."""
directive @timestamp(
    """Which events to generate timestamps on. Defaults to both create and update."""
    operations: [TimestampOperation!]! = [CREATE, UPDATE]
) on FIELD_DEFINITION

Usage

The following type definition has two individual fields to store the timestamps of create and update events:

type User {
    createdAt: DateTime! @timestamp(operations: [CREATE])
    updatedAt: DateTime! @timestamp(operations: [UPDATE])
}

The following two equivalent type definitions have a single field storing the event timestamp of the last create or update:

type User {
    lastModified: DateTime! @timestamp
}

type User {
    lastModified: DateTime! @timestamp(operations: [CREATE, UPDATE])
}

`@populatedBy`

This directive is used to specify a callback function that gets executed during GraphQL query parsing, to populate fields which have not been provided within the input.

For non-required values, callbacks may return undefined (meaning that nothing is changed or added to the property) or null (meaning that the property will be removed).

Definition

enum PopulatedByOperation {
    CREATE
    UPDATE
}

"""Instructs @neo4j/graphql to invoke the specified callback function to populate the field when updating or creating the properties on a node or relationship."""
directive @populatedBy(
    """The name of the callback function."""
    callback: String!
    """Which events to invoke the callback on."""
    operations: [PopulatedByOperation!]! = [CREATE, UPDATE]
) on FIELD_DEFINITION

Usage

Type definitions:

type Product {
    name: String!
    slug: String! @populatedBy(callback: "slug", operations: [CREATE, UPDATE])
}

Schema construction (note that the callback is asynchronous):

const slugCallback = async (root) => {
    return `${root.name}_slug`
}

new Neo4jGraphQL({
    typeDefs,
    driver,
    features: {
        populatedBy: {
            callbacks: {
                slug: slugCallback
            }
        }
    }
})

Context values

The GraphQL context for the request is available as the third argument in a callback. This maps to the argument pattern for GraphQL resolvers.

For example, if you want a field modifiedBy:

type Record {
    content: String!
    modifiedBy: @populatedBy(callback: "modifiedBy", operations: [CREATE, UPDATE])
}

If the username is located in context.username, you could define a callback such as:

const modifiedByCallback = async (_parent, _args, context) => {
    return context.username;
}

new Neo4jGraphQL({
    typeDefs,
    driver,
    features: {
        populatedBy: {
            callbacks: {
                modifiedBy: modifiedByCallback
            }
        }
    }
})

Note that the second positional argument, in this case _args, has a type of Record<string, never>, and as such it will always be an empty object.

Definition

enum CallbackOperation {
    CREATE
    UPDATE
}

"""Instructs @neo4j/graphql to invoke the specified callback function when updating or creating the properties on a node or relationship."""
directive @callback(
    """Which events to invoke the callback on."""
    operations: [CallbackOperation!]! = [CREATE, UPDATE]
    """The name of the callback function."""
    name: String!
) on FIELD_DEFINITION

Usage

Type definitions:

type Product {
    name: String!
    slug: String! @callback(operations: [CREATE, UPDATE], name: "slug")
}

Schema construction (note that the callback is asynchronous):

const slugCallback = async (root) => {
    return `${root.name}_slug`
}

new Neo4jGraphQL({
    typeDefs,
    driver,
    features: {
        populatedBy: {
            callbacks: {
                slug: slugCallback
            }
        }
    }
})