Neo4j GraphQL Server
A quick way to get started using neo4j-graphql-binding with Apollo Server.

Installation

1
npm install -s neo4j-graphql-server
Copied!

Strategy

This package uses neo4j-graphql-binding with Apollo Server to make it easier to get started using a generated API or setting up multiple bindings.
Create this graph in the Quick Start below! (image from Neo4j Bloom)
The following describes the server setup process based on the default configuration:
  1. 1.
    neo4jIDL is called to update your Neo4j-GraphQL schema.
  2. 2.
    neo4jAssertConstraints is used to support a @unique directive by creating constraints in your Neo4j instance. It uses the APOC extension.
  3. 3.
    buildNeo4jTypeDefs then augments the same typeDefs provided to your Neo4j-GraphQL schema.
  4. 4.
    neo4jGraphQLBinding is used to create a custom GraphQL Binding over the resulting augmented typeDefs. The binding is added into your server's context parameter (default key: 'neo4j' so you can access it the way you normally would access a GraphQL Binding.
  5. 5.
    buildNeo4jResolvers then generates any unprovided resolvers for query and mutation types that were generated or that use a @cypher directive. Each resolver uses a created binding to delegate all such queries and mutations to a Neo4j-GraphQL endpoint.
  6. 6.
    Finally, steps 1-5 are processed for any additional binding configurations provided in bindings and the resulting typeDefs and resolvers are merged and provided to Apollo Server.

Quick Start

This example server setup uses only auto-generated query and mutation types.
typeDefs
1
const typeDefs = `
2
type Technology @model {
3
name: String! @unique
4
integration: [Technology] @relation(
5
name: "HAPPINESS",
6
direction: OUT
7
)
8
}
9
`;
Copied!
Server
1
import { Neo4jGraphQLServer } from 'neo4j-graphql-server';
2
import { v1 as neo4j } from 'neo4j-driver';
3
4
const driver = neo4j.driver(
5
process.env.NEO4J_URI || "bolt://localhost:7687",
6
neo4j.auth.basic(
7
process.env.NEO4J_USER || "neo4j",
8
process.env.NEO4J_PASSWORD || "neo4j"
9
)
10
);
11
12
const server = Neo4jGraphQLServer({
13
typeDefs: typeDefs,
14
driver: driver
15
});
16
17
server.listen().then( ({ url }) => {
18
console.log(`🚀 Server ready at ${url}`);
19
});
Copied!
If you navigate to http://localhost:4000/, you should see GraphQL Playground.

Nested Mutation

This example uses nested create and connect mutations and takes advantage of the @unique directive to create the above graph with three Technology nodes.
Request
1
mutation {
2
createTechnology(
3
data: {
4
name: "Apollo",
5
integration: {
6
create: [
7
{
8
name: "GraphQL",
9
integration: {
10
create: [
11
{
12
name: "Neo4j",
13
integration: {
14
connect: [
15
{
16
name: "Apollo"
17
}
18
]
19
}
20
}
21
]
22
}
23
}
24
]
25
}
26
}
27
) {
28
id
29
name
30
integration {
31
id
32
name
33
integration {
34
id
35
name
36
integration {
37
id
38
name
39
}
40
}
41
}
42
}
43
}
Copied!
Response
1
{
2
"data": {
3
"createTechnology": {
4
"id": "cjj0dr5i00006fgr0tfukv1tn",
5
"name": "Neo4j",
6
"integration": [
7
{
8
"id": "cjj0dr5i00007fgr05js3fg30",
9
"name": "GraphQL",
10
"integration": [
11
{
12
"id": "cjj0dr5i00008fgr06ugrjnze",
13
"name": "Apollo",
14
"integration": [
15
{
16
"id": "cjj0dr5i00006fgr0tfukv1tn",
17
"name": "Neo4j"
18
}
19
]
20
}
21
]
22
}
23
]
24
}
25
}
26
}
Copied!

Query

Now we can run the following query:
Request
1
query {
2
Technology(orderBy: name_desc) {
3
id
4
name
5
}
6
}
Copied!
Response
1
{
2
"data": {
3
"Technology": [
4
{
5
"id": "cjj0dr5i00006fgr0tfukv1tn",
6
"name": "Neo4j"
7
},
8
{
9
"id": "cjj0dr5i00007fgr05js3fg30",
10
"name": "GraphQL"
11
},
12
{
13
"id": "cjj0dr5i00008fgr06ugrjnze",
14
"name": "Apollo"
15
}
16
]
17
}
18
}
Copied!

More Examples

Using @cypher Directives

The below typeDefs shows the use of the @cypher directive for a computed field, a query, and a mutation type. Any query and mutation types, or resolvers, that you provide are not overwritten by the schema augmenting process.
typeDefs
1
type Movie @model {
2
title: String!
3
released: Int
4
actors: [Person] @relation(name:"ACTED_IN",direction:IN)
5
# computed field
6
directors: [Person] @cypher(statement: """
7
MATCH (this)<-[:DIRECTED]-(d) RETURN d
8
""")
9
}
10
type Person @model {
11
name: String!
12
born: Int
13
movies: [Movie] @relation(name:"ACTED_IN")
14
}
15
type Query {
16
coActors(name:ID!): [Person] @cypher(statement:"""
17
MATCH (p:Person {name:$name})-[:ACTED_IN]->()<-[:ACTED_IN]-(co)
18
RETURN distinct co
19
""")
20
}
21
type Mutation {
22
rateMovie(user:ID!, movie:ID!, rating:Int!): Int @cypher(statement: """
23
MATCH (p:Person {name:$user}),(m:Movie {title:$movie})
24
MERGE (p)-[r:RATED]->(m) SET r.rating=$rating
25
RETURN r.rating
26
""")
27
}
28
schema {
29
query: Query
30
mutation: Mutation
31
}
Copied!
The corresponding resolvers can be provided if you want to handle the data or be explicit. Otherwise, they will be generated.
1
Query: {
2
coActors: (obj, params, ctx, info) => {
3
return ctx.neo4j.query.coActors(params, info);
4
}
5
// Movie (generated)
6
// Person
7
},
8
Mutation: {
9
rateMovie: async (obj, params, ctx, info) => {
10
const result = await ctx.neo4j.mutation.rateMovie(params, info);
11
// using result
12
return result;
13
}
14
// createMovie (generated)
15
// createPerson
16
}
Copied!

Using Multiple Bindings

See the section on using the GraphQL Community Graph for an example of configuring bindings for multiple local or remote Neo4j instances with the Neo4j-GraphQL extension available.

Prism Graph

This mutation creates a Prism Graph! 🌈
Prism Graph in Neo4j Bloom
1
mutation {
2
createTechnology(
3
data: {
4
name: "A",
5
integration: {
6
create: [
7
{
8
name: "B",
9
integration: {
10
connect: {
11
name: "D"
12
}
13
}
14
},
15
{
16
name: "C",
17
integration: {
18
create: [
19
{
20
name: "E",
21
integration: {
22
connect: [
23
{
24
name: "F"
25
},
26
{
27
name: "B"
28
}
29
]
30
}
31
},
32
{
33
name: "F",
34
integration: {
35
connect: {
36
name: "D"
37
}
38
}
39
}
40
]
41
}
42
},
43
{
44
name: "D"
45
}
46
]
47
}
48
}) {
49
id
50
name
51
integration {
52
id
53
name
54
integration {
55
id
56
name
57
integration {
58
id
59
name
60
}
61
}
62
}
63
}
64
}
Copied!

API Reference

All the same arguments as Apollo Server are supported, in addition to the following:
  • typeDefs (required): Your GraphQL type definitions in SDL format
  • driver(required): Your Neo4j driver instance (More info here).
  • calls Configures the use of neo4jAssertConstraints and neo4jIDL during setup.
    • assert (default: true): A boolean control that updates the unique property constraints in your Neo4j instance.
    • idl (default: true): A boolean control that updates your Neo4j-GraphQL schema.
  • augment Configures the use of buildNeo4jTypeDefs and buildNeo4jResolversduring setup.
    • typeDefs
      • query (default: true) A boolean controlling the generation of query types.
      • mutation (default: true) A boolean controlling the generation of mutation types.
    • resolvers
      • query (default: true) A boolean controlling the generation of resolvers for query types.
      • mutation (default: true) A boolean controlling the generation of resolvers for mutation types.
  • indexConfig Configures the management of generated id fields.
    • use (default/only: 'cuid') Configures what method to use when generating id field values.
  • bindingKey (default: 'neo4j'): The key used when storing the created binding into the server's context object.
  • log (default: false): Logs the result of any delegated query or mutation operation, buildNeo4jTypeDefs,neo4jAssertConstraints, and neo4jIDL.
  • readOnly (default: false): If you only have read access to a remote server, then you can use this parameter to turn off all processes that assume write access. Mutation types are not generated, idl and assert calls are prevented, and id fields are not generated and managed because we would never be able to write them to the instance. So, this results in forcing the following configuration:
1
calls: {
2
idl: false,
3
assert: false
4
},
5
augment: {
6
mutation: false
7
},
8
indexConfig: false
Copied!
  • bindings An object of bindings where each key is the name for a binding and each value is a configuration object containing the parameters: typeDefs, resolvers, driver, calls, augment, log, and readOnly. This can be used to network together a GraphQL binding for multiple remote Neo4j instances with the Neo4j-GraphQL extension installed.

Default Configuration

1
Neo4jGraphQLServer({
2
typeDefs: typeDefs,
3
resolvers: resolvers,
4
driver: driver,
5
calls: {
6
assert: true,
7
idl: true
8
},
9
augment: {
10
typeDefs: {
11
query: true,
12
mutation: true
13
},
14
resolvers: {
15
query: true,
16
mutation: true
17
}
18
},
19
indexConfig: {
20
use: "cuid"
21
},
22
bindingKey: 'neo4j',
23
log: true,
24
readOnly: false,
25
bindings: {
26
...
27
}
28
});
Copied!
Last modified 3yr ago