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")
}

@node

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 a custom Neo4j node label"""
    label: String
    """Map the GraphQL type to match additional Neo4j node labels"""
    additionalLabels: [String]
) on OBJECT

Usage

@node can be used with the following optional parameters.

label

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:

new ApolloServer({
    schema: neoSchema.schema,
    context: ({ req }) => ({ req, appId: "myApp" }),
});

additionalLabels

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