Skip to content

Rework index #275

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.

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
merged 6 commits into from
Jul 31, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 3 additions & 1 deletion modules/ROOT/content-nav.adoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
* xref:index.adoc[Introduction]
* xref:integrating-the-library.adoc[]

* *Getting started*

Expand Down Expand Up @@ -74,7 +75,8 @@

* *Versions and support*

* xref:versioning.adoc[]
* xref:migration/index.adoc[Migration guide]
* xref:deprecations.adoc[Deprecations]
* xref:deprecations.adoc[]
* xref:optimization.adoc[]
* xref:troubleshooting.adoc[]
1 change: 1 addition & 0 deletions modules/ROOT/pages/getting-started/graphql-aura.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Even with just field suggestions enabled, it is possible for a malicious actor t
=== Type definitions

Paste these **Type definitions**:

[source, graphql, indent=0]
----
type Product @node {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This tutorial shows you how to:
- Make sure that you have https://nodejs.org/en/[Node.js] 20+ installed.
- The examples use the default `npm` package manager, but you can use other package managers.
- Set up a https://neo4j.com[Neo4j database].
Make sure it fulfills the xref::index.adoc#_requirements[requirements], including the necessary plugins.
Make sure it fulfills the xref::integrating-the-library.adoc#_requirements[requirements], including the necessary plugins.


== Set up a directory
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/getting-started/toolbox.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ With it, you can:

== Connect to a Neo4j database

Before you start using the Toolbox, make sure you have followed all xref:index.adoc#_requirements[requirements] to run a Neo4j database.
Before you start using the Toolbox, make sure you have followed all xref::integrating-the-library.adoc#_requirements[requirements] to run a Neo4j database.
You can use https://neo4j.com/docs/desktop-manual/current/[Neo4j Desktop] or https://neo4j.com/docs/aura/auradb/[Neo4j AuraDB] for that.


Expand Down
140 changes: 86 additions & 54 deletions modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
@@ -1,79 +1,111 @@
[[index]]
= Introduction
:page-aliases: introduction.adoc
:description: This section describes the Neo4j GraphQL Library.
:description: An introduction to the Neo4j GraphQL Library.

The Neo4j GraphQL Library is a highly flexible, low-code, open source JavaScript library that enables rapid API development for cross-platform and mobile applications by tapping into the power of connected data.

With Neo4j as the graph database, the GraphQL Library makes it simple for applications to have data treated as a graph natively from the frontend all the way to storage.
This avoids duplicate schema work and ensures flawless integration between frontend and backend developers.

If you are new to Neo4j and GraphQL take a look at xref:getting-started/index.adoc[Creating a new project] and xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox] to learn the fundamentals of the Neo4j GraphQL Library and how to create GraphQL APIs backed by a Neo4j graph database.


== How it works

The Neo4j GraphQL Library requires a set of type definitions that describes the shape of your graph data.
It can generate an entire executable schema with all of the additional types needed to execute queries and mutations to interact with your Neo4j database.
The Neo4j GraphQL Library requires a set of type definitions that describes the shape of your graph data and creates an API layer to communicate with the data.

It generates an entire executable schema with all additional types needed to execute queries and mutations to interact with your Neo4j database.

For example, consider these type definitions:

[source, graphql, indent=0]
----
type Product @node {
productName: String
category: [Category!]! @relationship(type: "PART_OF", direction: OUT)
}

type Category @node {
categoryName: String
products: [Product!]! @relationship(type: "PART_OF", direction: IN)
}
----

Based on these type definitions, the library generates query and mutation templates to create new instances of the types as well as query existing instances.

The following mutation creates a new product as well as a new category:

[source, graphql, indent=0]
----
mutation {
createProducts(
input: [
{
productName: "New Product"
category: { create: [{ node: { categoryName: "New Category" } }] }
}
]
) {
products {
productName
category {
categoryName
}
}
}
}
----

Here is an example of how you can query existing data:

[source, graphql, indent=0]
----
query {
products {
productName
category {
categoryName
}
}
}
----
Comment on lines +34 to +67
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would consider putting the query first, along with an example response, as this feels like the most prominent and use case


The response looks like this:

[source, json, indent=0]
----
{
"data": {
"products": [
{
"productName": "New Product",
"category": [
{
"categoryName": "New Category"
}
]
}
]
}
}
----

For every query and mutation that is executed against this generated schema, the Neo4j GraphQL Library generates a single Cypher query which is executed against the database.
This eliminates the https://www.google.com/search?q=graphql+n%2B1[N+1 Problem], which can make GraphQL implementations slow and inefficient.

The Neo4j GraphQL Library features:
See xref:integrating-the-library.adoc[] to learn how to use the GraphQL Library in your technology stack.
Check out xref:getting-started/index.adoc[] to create a new project, either based on Neo4j Aura or self-hosted.


== Library features

- Automatic generation of xref::queries-aggregations/queries.adoc[Queries] and xref::mutations/index.adoc[Mutations] for CRUD interactions.
- xref::/types/index.adoc[Types], including temporal and spatial.
- Support for both node and relationship properties.
- Extensibility through the xref::/directives/custom-logic.adoc#_cypher[`@cypher` directive] and/or xref::/directives/custom-logic.adoc#_customresolver[Custom Resolvers].
- Extensive xref::filtering.adoc[Filtering], xref::queries-aggregations/sorting.adoc[Sorting] and xref::/queries-aggregations/pagination.adoc[Pagination] options.
- Options for xref::/directives/database-mapping.adoc[Database mapping] and value xref::/directives/autogeneration.adoc[Autogeneration].
- xref::/security/index.adoc[Security options] and additional xref::schema-configuration/index.adoc[Schema Configuration].
- xref:/subscriptions/index.adoc[Subscriptions] to server events.
- xref:integrations/apollo-federation.adoc[Apollo federation integration].
- Extensibility through the xref::/directives/custom-logic.adoc#_cypher[`@cypher` directive] and/or xref::/directives/custom-logic.adoc#_customresolver[Custom Resolvers].
- A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop.


== Interaction

In xref::getting-started/graphql-aura.adoc[] as well as xref::getting-started/graphql-self-hosted.adoc[], a GraphQL server is used to serve the GraphQL schema, so you can interact directly with your API with no frontend.
In case you prefer to use frontend frameworks, these are some clients that interact with GraphQL APIs:

- https://reactjs.org/[React] - support through https://www.apollographql.com/docs/react/[Apollo Client]
- https://vuejs.org/[Vue.js] - support through https://apollo.vuejs.org/[Vue Apollo]
- https://angularjs.org/[AngularJS] - support through https://apollo-angular.com/docs/[Apollo Angular].


== Deployment

There are a variety of methods for deploying GraphQL APIs.

With Aura Console, you can create and use a GraphQL API, see xref::getting-started/graphql-aura.adoc[].

The xref::getting-started/graphql-self-hosted.adoc[] guide uses Apollo Server.
You can check the Apollo documentation on https://www.apollographql.com/docs/apollo-server/deployment[Deployment] for more details.


== Versioning

The Neo4j GraphQL Library uses https://semver.org/[Semantic Versioning].
Given a version number `MAJOR.MINOR.PATCH`, the increment is based on:

- `MAJOR` - incompatible API changes compared to the previous `MAJOR` version, for which you will likely have to migrate
- `MINOR` - new features have been added in a backwards compatible manner
- `PATCH` - bug fixes have been added in a backwards compatible manner.

Additionally, prerelease version numbers may have additional suffixes, for example `MAJOR.MINOR.PATCH-PRERELEASE.NUMBER`, where `PRERELEASE` is one of the following:

- `alpha` - unstable prerelease artifacts, and the API may change between releases during this phase
- `beta` - feature complete prerelease artifacts, which will be more stable than `alpha` releases but will likely still contain bugs
- `rc` - release candidate including artifacts to be promoted to a stable release, in a last effort to find trailing bugs.

`NUMBER` in the suffix is simply an incrementing release number in each phase.


== Requirements

. https://neo4j.com/product/auradb/[Neo4j AuraDB] version 2025.x or https://neo4j.com/deployment-center/#gdb-selfmanaged[Neo4j Database] running the latest 5.x version or above with the APOC core plugin.


== Resources

. https://github.com/neo4j/graphql[GitHub]
Expand Down
27 changes: 27 additions & 0 deletions modules/ROOT/pages/integrating-the-library.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
= Integrating the library
:description: Learn how to use the Neo4j GraphQL Library with your technology stack.


== Interaction

In xref::getting-started/graphql-aura.adoc[] as well as xref::getting-started/graphql-self-hosted.adoc[], a GraphQL server serves the GraphQL schema, so you can interact directly with your API with no frontend.
In case you prefer to use frontend frameworks, these are some clients that interact with GraphQL APIs:

- https://reactjs.org/[React] - support through https://www.apollographql.com/docs/react/[Apollo Client]
- https://vuejs.org/[Vue.js] - support through https://apollo.vuejs.org/[Vue Apollo]
- https://angularjs.org/[AngularJS] - support through https://apollo-angular.com/docs/[Apollo Angular].


== Deployment

There are a variety of methods for deploying GraphQL APIs.

With Aura Console, you can create and use a GraphQL API, see xref::getting-started/graphql-aura.adoc[].

The xref::getting-started/graphql-self-hosted.adoc[] guide uses Apollo Server.
You can check the Apollo documentation on https://www.apollographql.com/docs/apollo-server/deployment[Deployment] for more details.


== Requirements

. https://neo4j.com/product/auradb/[Neo4j AuraDB] version 2025.x or https://neo4j.com/deployment-center/#gdb-selfmanaged[Neo4j Database] running the latest 5.x version or above with the APOC core plugin.
28 changes: 28 additions & 0 deletions modules/ROOT/pages/versioning.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
= Versioning
:description: The approach to versioning of the Neo4j GraphQL Library.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth mentioning the LTS vs latest approach?

Currently version 5 is LTS, which is still maintained but no new features are added, whilst version 7 (recommended) is actively being worked on



== LTS version

GraphQL Library version 5 is the long-term support (LTS) version.
It is maintained but no new features are added to it.

Version 7 is the recommended version and actively being developed.


== Semantic versioning

The Neo4j GraphQL Library uses https://semver.org/[Semantic Versioning].
Given a version number `MAJOR.MINOR.PATCH`, the increment is based on:

- `MAJOR` - incompatible API changes compared to the previous `MAJOR` version, for which you will likely have to migrate.
- `MINOR` - new features have been added in a backwards compatible manner.
- `PATCH` - bug fixes have been added in a backwards compatible manner.

Additionally, prerelease version numbers may have additional suffixes, for example `MAJOR.MINOR.PATCH-PRERELEASE.NUMBER`, where `PRERELEASE` is one of the following:

- `alpha` - unstable prerelease artifacts, and the API may change between releases during this phase
- `beta` - feature complete prerelease artifacts, which will be more stable than `alpha` releases but will likely still contain bugs
- `rc` - release candidate including artifacts to be promoted to a stable release, in a last effort to find trailing bugs.

`NUMBER` in the suffix is simply an incrementing release number in each phase.