Database Mapping

@alias

This directive maps a GraphQL field to a Neo4j property on a node or relationship.

This can be used on any fields that are not @cypher or @relationship fields.

Definition

"""Indicates that the field is to be mapped to the underlying Neo4j under a different property name."""
directive @alias(property: String!) on FIELD_DEFINITION

Usage

type User {
    id: ID! @id @alias(property: "dbId")
    username: String!
}
type User {
    id: ID! @id
    username: String! @alias(property: "dbUserName")
    livesIn: [City!]! @relationship(direction: OUT, type: "LIVES_IN", properties: "UserLivesInProperties")
}

type City {
    name: String
}

interface UserLivesInProperties @relationshipProperties {
    since: DateTime @alias(property: "moveInDate")
}

@plural

The @plural directive redefines how to compose the plural of the type for the generated operations. This is particularly useful for types that are not correctly pluralized or are non-English words.

type Tech @plural(value: "Techs") {
  name: String
}

This way, instead of the wrongly generated teches, the type is properly written as techs:

{
  techs {
    title
  }
}

The same is applied to other operations such as createTechs. Note that database labels will not change.

@node

The plural argument has been deprecated and will be removed in version 4.0. Please use the @plural directive instead.
The label and additionalLabels arguments of the @node directive have been deprecated and will be removed in version 4.0. Please use the labels argument instead.

The @node directive is used to specify the configuration of a GraphQL object type which represents a Neo4j node.

Definition

"""Informs @neo4j/graphql of node metadata"""
directive @node(
    """Map the GraphQL type to match Neo4j node labels"""
    labels: [String]
    """Map the GraphQL type to a custom Neo4j node label"""
    label: String
    """Map the GraphQL type to match additional Neo4j node labels"""
    additionalLabels: [String]
    """Allows for the specification of the plural of the type name."""
    plural: String
) on OBJECT

Usage

@node can be used with the following optional parameters.

labels

The parameter labels defines the list of label to be used in Neo4j instead of the GraphQL type name:

type Dog @node(labels: ["K9"]) {
    name: String!
}

This way, the following query:

{
  dogs {
    name
  }
}

Generates the cypher query:

MATCH (this: K9)
RETURN this { .name } as name

If the GraphQL type name should still be used as a label, it needs to be specified as well:

type Dog @node(labels: ["Dog", "K9"]) {
    name: String!
}

This way, the following query:

{
  dogs {
    name
  }
}

Generates the cypher query:

MATCH (this:Dog:K9)
RETURN this { .name } as this

Please note that defining labels means you take control of the database labels of the node. Indexes and constraints in Neo4j only support a single label, for which the first element of the labels argument will be used.

The following example results in a unique constraint be asserted for the label K9 and the property name:

type Dog @node(labels: ["K9", "Dog"]) {
    name: String! @unique
}

label

The label and additionalLabels arguments of the @node directive have been deprecated and will be removed in version 4.0. Please use the labels argument instead.

The parameter label defines the label to be used in Neo4j instead of the GraphQL type name:

type Movie @node(label: "Film") {
    title: String!
}

This way, the following query:

{
  movies {
    title
  }
}

Generates the cypher query:

MATCH (this: Film)
RETURN this { .title } as this
Using $jwt and $context

In some cases, we may want to generate dynamic labels depending on the user requesting. In these cases, we can use the variable $jwt to define a custom label define in the JWT (similarly to how it is used in the @auth directive):

type User @node(label: "$jwt.username") {
    name: String!
}

The following query will yield a different cypher query depending on the user JWT:

{
  users {
    name
  }
}

Assuming an user with the value "username": "arthur" in JWT, the Cypher query will look like:

MATCH (this:arthur)
RETURN this { .name } as this

Similarly, context values can be passed directly:

type User @node(label: "$context.appId") {
    name: String!
}

When running the server with Apollo:

const server = new ApolloServer({
    schema: await neoSchema.getSchema(),
});

await startStandaloneServer(server, {
    context: async ({ req }) => ({ req, appId: "myApp" }),
});

additionalLabels

The label and additionalLabels arguments of the @node directive have been deprecated and will be removed in version 4.0. Please use the labels argument instead.

additionalLabels lets you define extra Neo4j labels that need to exist on the node for that GraphQL type.

type Actor @node(additionalLabels: ["Person", "User"]) {
    name: String!
}

The following query:

{
  Actor {
    name
  }
}

Generates the following cypher query, with the labels Actor, Person and User:

MATCH (this:Actor:Person:User)
RETURN this { .name } as this

Note that additionalLabels can be used along with label:

type Actor @node(label: "ActorDB", additionalLabels: ["Person"]) {
    name: String!
}

In this case, the resulting Cypher query will use the labels ActorDB and Person instead of Actor:

MATCH (this:ActorDB:Person)
RETURN this { .name } as this

Context and JWT variables can be used with additionalLabels in the same fashion as in label:

type User @node(additionalLabels: ["$jwt.username"]) {
    name: String!
}

plural

The plural argument has been deprecated and will be removed in version 4.0. Please use the @plural directive instead.

The parameter plural redefines how to compose the plural of the type for the generated operations. This is particularly useful for types that are not correctly pluralized or are non-English words.

type Tech @node(plural: "Techs") {
  name: String
}

This way, instead of the wrongly generated teches, the type is properly written as techs:

{
  techs {
    title
  }
}

The same is applied to other operations such as createTechs. Note that database labels will not change.