diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 13c4af8..7242354 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -1,4 +1,5 @@ * xref:index.adoc[Introduction] +* xref:integrating-the-library.adoc[] * *Getting started* @@ -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[] diff --git a/modules/ROOT/pages/getting-started/graphql-aura.adoc b/modules/ROOT/pages/getting-started/graphql-aura.adoc index 278fd4b..29eb8b1 100644 --- a/modules/ROOT/pages/getting-started/graphql-aura.adoc +++ b/modules/ROOT/pages/getting-started/graphql-aura.adoc @@ -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 { diff --git a/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc b/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc index 7b02da2..54d8af9 100644 --- a/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc +++ b/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc @@ -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 diff --git a/modules/ROOT/pages/getting-started/toolbox.adoc b/modules/ROOT/pages/getting-started/toolbox.adoc index da87aeb..e2460de 100644 --- a/modules/ROOT/pages/getting-started/toolbox.adoc +++ b/modules/ROOT/pages/getting-started/toolbox.adoc @@ -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. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 8da8abb..393938e 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -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 + } + } +} +---- + +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] diff --git a/modules/ROOT/pages/integrating-the-library.adoc b/modules/ROOT/pages/integrating-the-library.adoc new file mode 100644 index 0000000..25eba5d --- /dev/null +++ b/modules/ROOT/pages/integrating-the-library.adoc @@ -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. \ No newline at end of file diff --git a/modules/ROOT/pages/versioning.adoc b/modules/ROOT/pages/versioning.adoc new file mode 100644 index 0000000..2e85e30 --- /dev/null +++ b/modules/ROOT/pages/versioning.adoc @@ -0,0 +1,28 @@ += Versioning +:description: The approach to versioning of the Neo4j GraphQL Library. + + +== 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. \ No newline at end of file