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.

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
merged 6 commits into from
Jul 31, 2025
Merged

Rework index #275

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9652411
created new pages, slimmed down the introduction
rsill-neo4j Jul 17, 2025
4f97601
moved a section
rsill-neo4j Jul 18, 2025
5c42503
Update modules/ROOT/pages/versioning.adoc
rsill-neo4j Jul 23, 2025
8010594
review suggestions
rsill-neo4j Jul 23, 2025
4fbe814
path change
rsill-neo4j Jul 23, 2025
208f605
restored intro, restored order for 'how it works' section
rsill-neo4j Jul 24, 2025
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
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
* xref:index.adoc[Introduction]
* xref:using-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
View file
Open in desktop
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
127 changes: 66 additions & 61 deletions modules/ROOT/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,77 +1,82 @@
[[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.
The Neo4j GraphQL Library is:

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.
* highly flexible and low-code
* open source
* a JavaScript library
* leveraging graph-native data
Copy link
Member

Choose a reason for hiding this comment

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

I'm not 100% sure why this was moved to be a list, it feels much more concise to keep it as a single sentence, and maybe use the space for a reduced list of features to showcase at the beginning?

Copy link
Member

Choose a reason for hiding this comment

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

Maybe we can discuss on an introduction for the GraphQL library?

Something on the lines of:

Neo4j GraphQL is a low code tool to create powerful GraphQL APIs for your Neo4j database.

And then move on to a bullet list of the main features maybe?

* Out of the box API
* On prem and managed service on Aura
* Customizable API 
* Authorization and Authentication
* Custom Cypher
* Subscriptions
* GraphQL Federation support


It enables rapid API development for cross-platform and mobile applications.

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


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:

- 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].
- 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.
See xref:using-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.


== Resources
Expand Down
40 changes: 40 additions & 0 deletions modules/ROOT/pages/using-the-library.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
= Using the library
Copy link
Member

Choose a reason for hiding this comment

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

Could this be a bit confusing title?

I expected this to describe how to use the library, not how to integrate with my stack

:description: Learn how to use the Neo4j GraphQL Library with your technology stack.

== Library features
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm also not 100% sure this belongs here long term. That being said it see some value in it for now as it's actually quite hard to get a sense of the library features and how it's configured with the current docs layout as most of it buried

Not sure if anyone has any better ideas for this but maybe we leave for now and take another look once we've gone further with this rework of the docs?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

moved the section


The Neo4j GraphQL 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].
- A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop.
Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure if this is helpful here

This feels more like a "features" blurb to show off in the index, but we may want to refine a bit the list of features

There are some pretty big ones missing such as subscription and federation integration. And potentially Database mapping and autogeneration do not feel as big as to be part of the "main features" list?



== 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.
17 changes: 17 additions & 0 deletions modules/ROOT/pages/versioning.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
= 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


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.