Neo4j GraphQL Library

To use @neo4j/graphql, define your GraphQL schema using @relationship directives to map to Neo4j relationships, instantiate Neo4jGraphQL with your typeDefs and a neo4j-driver instance, and then use neoSchema.getSchema() to generate the executable schema for your GraphQL server (e.g., Apollo Server).

const { Neo4jGraphQL } = require("@neo4j/graphql");
const neo4j = require("neo4j-driver");
const { ApolloServer } = require("apollo-server");

const typeDefs = `
    type Movie {
        title: String
        year: Int
        imdbRating: Float
        genres: [Genre!]! @relationship(type: "IN_GENRE", direction: OUT)
    }

    type Genre {
        name: String
        movies: [Movie!]! @relationship(type: "IN_GENRE", direction: IN)
    }
`;

const driver = neo4j.driver("bolt://localhost:7687", neo4j.auth.basic("neo4j", "letmein"));

const neoSchema = new Neo4jGraphQL({ typeDefs, driver });

async function main() {
    const schema = await neoSchema.getSchema();

    const server = new ApolloServer({
        schema,
        context: ({ req }) => ({ req }),
    });

    await server.listen(4000);

    console.log("Online");
}

main();

This docker-compose.yml file sets up a local development environment consisting of a Neo4j Enterprise database and a products service. The products service is built from the local directory and is configured to connect to the Neo4j instance.

Service Configuration

Neo4j Service

• Image: neo4j:enterprise
• Ports:
  • 7474: HTTP Browser interface
  • 7687: Bolt protocol
• Environment Variables:
  • NEO4J_ACCEPT_LICENSE_AGREEMENT=yes: Required to start the enterprise edition.
  • NEO4J_AUTH=neo4j/password: Sets the default credentials.
  • NEO4J_PLUGINS=["apoc"]: Installs the APOC plugin.
• Healthcheck: Uses wget on the HTTP port to ensure the database is ready before dependent services start.

Products Service

• Build Context: Current directory (.)
• Ports: 4001:4001
• Environment Variables:
  • NEO4J_URI=neo4j://neo4j:7687/neo4j: The connection string used by the service to reach the Neo4j container.
• Dependencies: Waits for the neo4j service to pass its healthcheck before starting.

version: "3.9"
services:
  neo4j:
    image: "neo4j:enterprise"
    ports:
      - 7474:7474
      - 7687:7687
    environment:
      - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
      - NEO4J_AUTH=neo4j/password
      - NEO4J_PLUGINS=["apoc"]
    healthcheck:
      test: wget http://localhost:7474/browser -O -
      interval: 1s
      timeout: 1s
      retries: 40
  products:
    build: .
    ports:
      - "4001:4001"
    environment:
      - NEO4J_URI=neo4j://neo4j:7687/neo4j
    depends_on:
      neo4j:
        condition: service_healthy

The library automatically generates mutation and query capabilities based on your schema.

• Create: Use create<Type>s with an input array.
• Update/Connect: Use update<Type>s with a where clause and a connect object to link existing nodes.
• Nested Creation: You can connect existing nodes during a creation mutation using the connect key within the input object.
• Querying: Standard GraphQL queries allow traversing relationships defined via @relationship.

# Create Movies
mutation {
    createMovies(input: [{ title: "The Matrix", year: 1999, imdbRating: 8.7 }]) {
        movies {
            title
        }
    }
}

# Connect existing movies to genres
mutation {
    updateMovies(
        where: { title: "The Matrix" }
        connect: { genres: { where: { node: { OR: [{ name: "Sci-fi" }, { name: "Action" }] } } } }
    ) {
        movies {
            title
        }
    }
}

# Create Movie and connect Genre in one step
mutation {
    createMovies(
        input: [
            {
                title: "The Matrix"
                year: 1999
                imdbRating: 8.7
                genres: { connect: { where: { node: { AND: [{ name: "Sci-fi" }, { name: "Action" }] } } } }
            }
        ]
    ) {
        movies {
            title
        }
    }
}

# Find Movies with Genres
query {
    movies {
        title
        genres {
            name
        }
    }
}