Skip to content

Update for GraphQL 7.2.0 middleware support #1327

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matea16 merged 1 commit into from
Jul 3, 2025
Merged

Update for GraphQL 7.2.0 middleware support #1327

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 142 additions & 31 deletions pages/client-libraries/graphql.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,18 @@ queries against it.

## Quickstart

We'll be using a simple Node.js application using the Neo4j GraphQL Library to connect
to a running Memgraph instance and execute GraphQL queries against the database.
We'll be using a simple Node.js application using the Neo4j GraphQL Library to
connect to a running Memgraph instance and execute GraphQL queries against the
database.

Necessary prerequisites that should be installed in your local environment are:

- [The Neo4j GraphQL Library](https://neo4j.com/docs/graphql/current/).
- The [npm](https://www.npmjs.com/) package manager.
- The [Node.js](https://nodejs.org/en) runtime environment.
- A utility that can be used to host the GraphQL schema, e.g. [Apollo Server](https://www.apollographql.com/docs/apollo-server/).

<Steps>

### Run Memgraph
### Run Memgraph

If you're new to Memgraph or you're in a developing stage, we
recommend using the Memgraph Platform. Besides the database, it also
Expand Down Expand Up @@ -58,15 +57,15 @@ communicate with the client using the exposed 7687 port. Memgraph Lab is a web
application you can use to visualize the data. It's accessible at
[http://localhost:3000](http://localhost:3000) if Memgraph Platform is running
correctly. The 7444 port enables Memgraph Lab to access and preview the logs,
which is why both of these ports need to be exposed.
which is why both of these ports need to be exposed.

For more information visit the getting started guide on [how to run Memgraph
with Docker](/getting-started/install-memgraph/docker).


### Create a work directory

Next, create a directory for your project and positioning yourself in it:
Next, create a directory for your project and position yourself in it:

```
mkdir graphql-example
Expand All @@ -83,36 +82,98 @@ npm init es6 --yes

### Setup the Neo4j GraphQL Library

Install the library and its dependencies by running the following command:
Install the library, its dependencies, and a GraphQL server (such as [Apollo
Server](https://www.apollographql.com/docs/apollo-server/)) by running the
following command:

```
npm install @neo4j/graphql graphql neo4j-driver @apollo/server
npm install @neo4j/graphql@7.2.0 graphql neo4j-driver @apollo/server
```

<Callout type="warning">
Memgraph is currently compatible with `@neo4j/graphql@7.2.0`. Other versions of
the GraphQL middleware may not generate Memgraph-compatible queries.
</Callout>

### Create the Schema

GraphQL APIs need to be aware of the shape of the data they are working with,
which is abstracted into the concept of GraphQL schemas. This must be explicitly
specified in the Node.js application file. In terms of a property graph, the
schema must contain the labels and properties of nodes and relationships.
(Whilst the Neo4j GraphQL Library has support for automatic graph introspection,
Memgraph currently does not support this feature.)

More information on defining a GraphQL schema can be found in the
[GraphQL documentation](https://graphql.org/learn/schema/).

Given the following dataset:

```cypher
CREATE (u1:User {id: "user1", name: "Alice"})
CREATE (u2:User {id: "user2", name: "Bob"})
CREATE (p1:Post {id: "post1", content: "Alice's first post!"})
CREATE (p2:Post {id: "post2", content: "Bob's great idea."})
CREATE (p3:Post {id: "post3", content: "Another thought from Alice."})
CREATE (u1)-[:HAS_POST]->(p1)
CREATE (u2)-[:HAS_POST]->(p2)
CREATE (u1)-[:HAS_POST]->(p3);
```

We could create the following schema, where `type Post @node` corresponds to a
vertex with a `:Post` label, `content: String` to a `content` property on the
vertex, and `:HAS_POST` edges are notated using the `@relationship` directive
with type `HAS_POST`.

```graphql
type Post @node {
id: ID! @id
content: String!
creator: [User!]! @relationship(type: "HAS_POST", direction: IN)
}

type User @node {
id: ID! @id
name: String
posts: [Post!]! @relationship(type: "HAS_POST", direction: OUT)
}
```

<Callout>
Note that relationships in the schema must always be expressed as many-to-many
(i.e, as array `[ ]` types), even if they model one-to-one, one-to-many, or
many-to-one relationships. This is a restriction of the GraphQL middleware.
</Callout>

### Create the application file

The application file will be used to setup the Neo4j GraphQL Library and connect to the running Memgraph instance.
The application file will be used to setup the Neo4j GraphQL Library and connect
to the running Memgraph instance.

Create the file and add the content below.
Create the file:

```
touch index.js
```

Add the content below. Note that the schema we created above is used as a
string literal for `typeDefs`:


```js
import { Neo4jGraphQL } from "@neo4j/graphql";
import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone';
import neo4j from 'neo4j-driver'

const typeDefs = `#graphql
type Post {
const typeDefs = `
type Post @node {
id: ID! @id
content: String!
creator: User! @relationship(type: "HAS_POST", direction: IN)
creator: [User!]! @relationship(type: "HAS_POST", direction: IN)
}

type User {
type User @node {
id: ID! @id
name: String
posts: [Post!]! @relationship(type: "HAS_POST", direction: OUT)
Expand All @@ -131,16 +192,24 @@ const server = new ApolloServer({
});

const { url } = await startStandaloneServer(server, {
context: async ({ req }) => ({ req, sessionConfig: {database: "memgraph"}}),
context: async ({ req }) => ({
req,
sessionConfig: { database: "memgraph" },
cypherQueryOptions: { addVersionPrefix: false }
}),
listen: { port: 4000 },
});

console.log(`🚀 Server ready at ${url}`);
```

The example above shows that the data schema must be explicitly defined. The GraphQL server can only process queries that operate on data conforming to the specified schemas. In this example, the schema defines a graph, where the nodes labeled as `User` or `Post` may be connected with a `HAS_POST` relationship.
```

To set up a GraphQL client against a running Memgraph instance, you have to specify the GraphQL schema, set up the used drivers, and specify Memgraph as the used database. Specifying the used database is especially important because the default database name in the `driverConfig` is not compatible with Memgraph.
To set up a GraphQL client against a running Memgraph instance, you have to
specify the GraphQL schema, set up the used drivers, and specify Memgraph as the
used database. Specifying the used database is especially important because the
default database name in the `driverConfig` is not compatible with Memgraph.
You must also use `cypherQueryOptions: { addVersionPrefix: false }` to ensure
that any Cypher queries are compatible with Memgraph.

### Run the application

Expand All @@ -152,27 +221,69 @@ node index.js

### Interact with Memgraph

You are now ready to interact with Memgraph using GraphQL queries through **localhost(127.0.0.1):4000**.
You are now ready to interact with Memgraph using GraphQL queries through the
GraphQL server on `localhost:4000` or `127.0.0.1:4000`.

Running a GraphQL query on the example dataset, such as:

```graphql
query Users {
users {
name
posts {
content
}
}
}
```

will yield the following results:

```json
{
"data": {
"users": [
{
"name": "Alice",
"posts": [
{
"content": "Alice's first post!"
},
{
"content": "Another thought from Alice."
}
]
},
{
"name": "Bob",
"posts": [
{
"content": "Bob's great idea."
}
]
}
]
}
}
```

</Steps>

## Current limitations
## Features

Memgraph currently supports CRUD operations using GraphQL. That means that the entities inside
the database can be updated and basic traversals can be done, but more complicated operations
are currently not supported through GraphQL.
Memgraph support includes the following GraphQL features:

GraphQL APIs need to be aware of the shape of data they are working with which is abstracted
into the concept of GraphQL schemas. Currently this has to be specified in the Node.js
application file explicitly. In terms of a property graph, this means the labels and properties
of nodes and relationships. The Neo4j GraphQL Library has support for automatic graph
introspection, Memgraph currently does not support this feature.
- [Read queries based on a defined schema.](https://neo4j.com/docs/graphql/current/queries-aggregations/queries/)
- [Aggregations on nodes and edges.](https://neo4j.com/docs/graphql/current/queries-aggregations/aggregations/)
- [Sorting results on any object type defined in the schema.](https://neo4j.com/docs/graphql/current/queries-aggregations/sorting/)
- [Offset and cursor based pagination.](https://neo4j.com/docs/graphql/current/queries-aggregations/pagination/)
- [Create, update, and delete mutations.](https://neo4j.com/docs/graphql/current/mutations/)
- [Custom Cypher statements with the `@cypher` directive.](https://neo4j.com/docs/graphql/current/directives/custom-logic/#_cypher)

<Callout type="info">

If you encounter serialization errors while using GraphQL client, we recommend
referring to our [Serialization errors](/help-center/errors/serialization) page
for detailed guidance on troubleshooting and best practices.

for detailed guidance on troubleshooting and best practices.

</Callout>