Rework getting started pages #273

rsill-neo4j · 2025-07-03T07:39:32Z

No description provided.

… tutorial

modules/ROOT/pages/getting-started/graphql-aura.adoc

mjfwebb · 2025-07-03T08:35:52Z

modules/ROOT/pages/getting-started/graphql-aura.adoc

+Alternatively, if you already have data in the AuraDB, you can obtain your type definitions via the https://graphql-toolbox.neo4j.io[Neo4j GraphQL Toolbox].
+The toolbox can connect to the AuraDB and automatically create type definitions and allow GraphQL operations.


Just to note we want to have the introspection feature in the Aura console soon, so this will need to be updated to reflect that when it's added.

mjfwebb · 2025-07-03T08:37:45Z

modules/ROOT/pages/getting-started/graphql-aura.adoc

+=== Authentication providers
+
+All requests to the GraphQL API are authenticated and there are two options for the type of authentication: API key or JSON Web Key Set (JWKS).
+It is possible to use these in combination and have multiples of each.


@Liam-Doodson just to double check, we only allow use of a single authentication provider per query, right?

That may need to be reflected here.

Yeah in a single request to the api, you can only use a single auth provider. However, the api can be configured multiple different auth providers e.g. on one request you can use an api key, the next request use a jwt and then maybe a different api key on a third request

modules/ROOT/pages/getting-started/graphql-aura.adoc

Co-authored-by: Michael Webb <28074382+mjfwebb@users.noreply.github.com>

neo4j-docops-agent · 2025-07-04T08:25:49Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-graphql-273.surge.sh

New pages:

Updated pages:

Liam-Doodson · 2025-07-07T10:04:21Z

modules/ROOT/pages/index.adoc

+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:


Sorry, I'm not able to comment on the section I want here 😬

This is just a minor point but in the features list filtering, sorting and pagination all belong in the same bullet point

Liam-Doodson · 2025-07-07T10:14:10Z

modules/ROOT/pages/index.adoc

-In the xref::getting-started/index.adoc[Getting Started] guide, Apollo Server is used to host the GraphQL schema, so you can interact directly with your API with no frontend.
+// Modify link below and add info about aura graphql
+
+In xref::getting-started/graphql-aura.adoc[] as well as xref::getting-started/graphql-self-hosted.adoc[], Apollo Server is used to host the GraphQL schema, so you can interact directly with your API with no frontend.


We don't actually use yoga instead of Apollo Server in Aura. We also don't really want to be opinionated about which server self-hosted customers use as the library should work with any graphql server

Suggested change

In xref::getting-started/graphql-aura.adoc[] as well as xref::getting-started/graphql-self-hosted.adoc[], Apollo Server is used to host the GraphQL schema, so you can interact directly with your API with no frontend.

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.

Liam-Doodson · 2025-07-07T10:15:34Z

modules/ROOT/pages/index.adoc

 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.


It might be good to mention something here about using Aura to deploy your API as that would be our preference

Liam-Doodson · 2025-07-07T10:21:13Z

modules/ROOT/pages/index.adoc

+. https://neo4j.com/product/auradb/[Neo4j AuraDB] version 5.x with APOC core plugin or https://neo4j.com/deployment-center/#gdb-selfmanaged[Neo4j Database].
+Note that version 5.15 or higher is required to use the xref:/directives/indexes-and-constraints.adoc#_vector_index_search[`@vector` directive].


We were actually discussing last week changing this wording as it's inaccurate. We require users to be on the latest patch of a major version. There's also not much reason they shouldn't be keeping up to date

Also Aura always ships with APOC and there is no 5.x dbs in Aura anymore

Suggested change

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

Note that version 5.15 or higher is required to use the xref:/directives/indexes-and-constraints.adoc#_vector_index_search[`@vector` directive].

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

Liam-Doodson · 2025-07-07T10:59:56Z

modules/ROOT/pages/getting-started/graphql-aura.adoc

+
+=== Via Apollo Server
+
+. On the https://studio.apollographql.com/[Apollo Studio] website, paste your GraphQL Data API URL to the **Sandbox** input.


If you go directly to https://studio.apollographql.com/sandbox/explorer you don't need to create an account or sign in

Suggested change

. On the https://studio.apollographql.com/[Apollo Studio] website, paste your GraphQL Data API URL to the **Sandbox** input.

. On the https://studio.apollographql.com/sandbox/explorer[Apollo Studio] website, paste your GraphQL Data API URL to the **Sandbox** input.

Liam-Doodson · 2025-07-07T12:38:56Z

modules/ROOT/pages/getting-started/graphql-self-hosted.adoc

+== Prerequisites
+
+- The tutorial assumes familiarity with the command line and JavaScript.
+- Make sure that you have a recent version of Node.js installed.


Probably better to be specific here. We require nodejs 20 or higher

Suggested change

- Make sure that you have a recent version of Node.js installed.

- Make sure that you have https://nodejs.org/en/[Node.js] 20+ installed.

Liam-Doodson · 2025-07-07T12:54:25Z

modules/ROOT/pages/getting-started/graphql-self-hosted.adoc

+
+[source, javascript, indent=0]
+----
+const driver = neo4j.driver(


I'm not sure I love that we're hardcoding the credentials here without a note that it's not best practice (anyone with access to your source code now has access to your DB).

Either we just add a warning/note about this risk or we should try to use environment variables e.g.

const { NEO4J_URI = "neo4j://localhost:7687/neo4j", NEO4J_USERNAME = "neo4j", NEO4J_PASSWORD = "password", } = process.env; const driver = neo4j.driver( NEO4J_URI, neo4j.auth.basic(NEO4J_USERNAME, NEO4J_PASSWORD) );

With this example it's still possible to hardcode to get going quickly but we should prompt the user to not commit real creds and set them using environment variables going forward

Not sure if you have any thoughts on this or better ideas @mjfwebb?

Liam-Doodson · 2025-07-07T12:59:19Z

modules/ROOT/pages/getting-started/index.adoc

-
-To learn more, keep reading the documentation about xref:queries-aggregations/index.adoc[Queries and aggregations] or alternatively learn how to use the xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox].
-For more advanced database settings, refer to the xref:driver-configuration.adoc[Driver configuration] page.
+These pages walks you through creating a new project with the Neo4j GraphQL Library.


These guides are both based on the northwind dataset right?

Is it worth mentioning here or maybe at the end of the guides that as a next step users could try loading that dataset into their db and extending the schema for the full data set to see what that adds to their api?

Ideally we could also write a guide for this in the future too!

yes, i had added a reference to the northwind dataset initially, but the examples work without it so far (or rather, only work when no other data is present). the idea was to go in that direction and make it the default data set for all examples

i'd say, we leave it out for now, and revisit when the picture is more coherent. maybe we could add a page that is specifically about importing and then making the northwind set available to a client via the api

Liam-Doodson · 2025-07-07T13:03:54Z

modules/ROOT/pages/getting-started/toolbox.adoc

-+
+Set your type definitions directly in the Toolbox editor or introspect the Neo4j database you connected to.
+
+If you followed the xref:getting-started/graphql-self-hosted.adoc[self-hosted GraphQL tutorial], use **Introspect** to see these type definitions in the GraphQL Toolbox:


It's worth bearing in mind that if the user has done extra things in their db since that tutorial, they will likely see different type definitions when they introspect the db

Liam-Doodson · 2025-07-07T13:05:54Z

modules/ROOT/pages/directives/custom-logic.adoc

@@ -334,6 +334,11 @@ type Movie @limit(max: 100, default: 10) @node {

 == `@customResolver`

+[NOTE]


👏

It's worth noting that there's a few other directives that are not supported currently.

The list is @populatedBy, @customResolvers, @subscriptions, @subscriptionsAuthorization&@vector`

Ideally we should add support for the last 3 soon though!

ah, good to know -
i added this note because John added it to the aura docs and i thought it's important enough to add to the directive itself. will add to the others 👍

rsill-neo4j added 5 commits June 18, 2025 16:29

some changes to getting started

a4cc094

integrated aura graphql, removed some screenshots, added graphql aura

4aca8ce

added usage section to aura graphql getting started, adjusted toolbox…

416b037

… tutorial

added section for apollo server in graphql aura

6307df8

replaced screenshots in toolbox page and modified structure

8d6d090

rsill-neo4j requested review from mjfwebb and Liam-Doodson July 3, 2025 07:39

addressed two comments in index.adoc

e184522

mjfwebb reviewed Jul 3, 2025

View reviewed changes

modules/ROOT/pages/getting-started/graphql-aura.adoc Outdated Show resolved Hide resolved

mjfwebb reviewed Jul 3, 2025

View reviewed changes

rsill-neo4j and others added 3 commits July 4, 2025 10:18

Apply suggestions from code review

70ec2db

Co-authored-by: Michael Webb <28074382+mjfwebb@users.noreply.github.com>

review suggestions

2f8b79b

Merge branch '7.x' into rework-getting-started-pages

f6f0b67

Liam-Doodson reviewed Jul 7, 2025

View reviewed changes

		Alternatively, if you already have data in the AuraDB, you can obtain your type definitions via the https://graphql-toolbox.neo4j.io[Neo4j GraphQL Toolbox].
		The toolbox can connect to the AuraDB and automatically create type definitions and allow GraphQL operations.

	In xref::getting-started/graphql-aura.adoc[] as well as xref::getting-started/graphql-self-hosted.adoc[], Apollo Server is used to host the GraphQL schema, so you can interact directly with your API with no frontend.
	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.

		. https://neo4j.com/product/auradb/[Neo4j AuraDB] version 5.x with APOC core plugin or https://neo4j.com/deployment-center/#gdb-selfmanaged[Neo4j Database].
		Note that version 5.15 or higher is required to use the xref:/directives/indexes-and-constraints.adoc#_vector_index_search[`@vector` directive].


		=== Via Apollo Server

		. On the https://studio.apollographql.com/[Apollo Studio] website, paste your GraphQL Data API URL to the Sandbox input.

	- Make sure that you have a recent version of Node.js installed.
	- Make sure that you have https://nodejs.org/en/[Node.js] 20+ installed.

		@@ -334,6 +334,11 @@ type Movie @limit(max: 100, default: 10) @node {

		== `@customResolver`

		[NOTE]

Rework getting started pages #273

Are you sure you want to change the base?

Rework getting started pages #273

Conversation

rsill-neo4j commented Jul 3, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

neo4j-docops-agent commented Jul 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!