diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 751870ed..13c4af8e 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -3,6 +3,8 @@ * *Getting started* * xref:getting-started/index.adoc[] +** xref:getting-started/graphql-aura.adoc[] +** xref:getting-started/graphql-self-hosted.adoc[] * xref:getting-started/toolbox.adoc[] * *Reference* diff --git a/modules/ROOT/images/apollo-server-landing-page.png b/modules/ROOT/images/apollo-server-landing-page.png deleted file mode 100644 index bc964271..00000000 Binary files a/modules/ROOT/images/apollo-server-landing-page.png and /dev/null differ diff --git a/modules/ROOT/images/neo4j-aura-dashboard.png b/modules/ROOT/images/neo4j-aura-dashboard.png deleted file mode 100644 index f68cefb6..00000000 Binary files a/modules/ROOT/images/neo4j-aura-dashboard.png and /dev/null differ diff --git a/modules/ROOT/images/toolbox-editor-view.png b/modules/ROOT/images/toolbox-editor-view.png index ad8b1bc2..b93bb0bf 100644 Binary files a/modules/ROOT/images/toolbox-editor-view.png and b/modules/ROOT/images/toolbox-editor-view.png differ diff --git a/modules/ROOT/images/toolbox-favorite.png b/modules/ROOT/images/toolbox-favorite.png index f6d3b060..0473c0f9 100644 Binary files a/modules/ROOT/images/toolbox-favorite.png and b/modules/ROOT/images/toolbox-favorite.png differ diff --git a/modules/ROOT/images/toolbox-schema-view.png b/modules/ROOT/images/toolbox-schema-view.png index 5f0985b7..26f3ba40 100644 Binary files a/modules/ROOT/images/toolbox-schema-view.png and b/modules/ROOT/images/toolbox-schema-view.png differ diff --git a/modules/ROOT/pages/directives/custom-logic.adoc b/modules/ROOT/pages/directives/custom-logic.adoc index d860c50f..45370ddc 100644 --- a/modules/ROOT/pages/directives/custom-logic.adoc +++ b/modules/ROOT/pages/directives/custom-logic.adoc @@ -334,6 +334,11 @@ type Movie @limit(max: 100, default: 10) @node { == `@customResolver` +[NOTE] +==== +Data APIs created in Aura Console currently do not support custom resolvers. +==== + The Neo4j GraphQL Library generates query and mutation resolvers, so you don't need to implement them yourself. However, if you need additional behaviors besides the autogenerated CRUD operations, you can specify custom resolvers for these scenarios. @@ -493,6 +498,11 @@ type Journal implements Publication @node { == `@populatedBy` +[NOTE] +==== +Data APIs created in Aura Console currently do not support the `@populatedBy` directive. +==== + This directive is used to specify a callback function, which is executed during GraphQL query parsing, to populate fields which have not been provided within the input. diff --git a/modules/ROOT/pages/directives/indexes-and-constraints.adoc b/modules/ROOT/pages/directives/indexes-and-constraints.adoc index 4594e12a..74c4a606 100644 --- a/modules/ROOT/pages/directives/indexes-and-constraints.adoc +++ b/modules/ROOT/pages/directives/indexes-and-constraints.adoc @@ -168,6 +168,11 @@ query { [#_vector_index_search] == `@vector` +[NOTE] +==== +Data APIs created in Aura Console currently do not support the `@vector` directive. +==== + With the `@vector` GraphQL directive you can query your database to perform a vector index search. Queries are performed by passing in either a vector index or a query phrase. diff --git a/modules/ROOT/pages/getting-started/graphql-aura.adoc b/modules/ROOT/pages/getting-started/graphql-aura.adoc new file mode 100644 index 00000000..0513a06d --- /dev/null +++ b/modules/ROOT/pages/getting-started/graphql-aura.adoc @@ -0,0 +1,229 @@ += GraphQL and Aura Console + +This tutorial shows you how to create and use a GraphQL Data API in Aura Console. + + +== Create a GraphQL Data API + +In the Aura Console, select **Data services** > **Data APIs** from the left side navigation and then **Create API**. + + +=== Details + +Provide a name for your new API as well the instance data for the instance you want to use under **Details**. +Also do **Enable introspection** and **Enable field suggestions** for use with xref:#_via_apollo_server[Apollo Server]. + +[CAUTION] +==== +If you set **Enable introspection** and **Enable field suggestions** for production systems the information they provide can be used by malicious actors to reverse-engineer your GraphQL schema and execute arbitrary operations. + +**Enable introspection** allows you to query the schema and discover the available queries, mutations, subscriptions, types and fields in the GraphQL API. + +**Enable field suggestions** provides suggestions that hint towards GraphQL typos. +Even with just field suggestions enabled, it is possible for a malicious actor to discover your entire schema. +==== + + +=== Type definitions + +Paste 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) +} +---- + +The type definitions describe what parts of the graph database in the AuraDB are accessible by requests made via the GraphQL API. + +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. + +If you are using link:https://graphql.org/learn/federation/[GraphQL Federation] then make sure to select **Enable GraphQL subgraph**. + + +=== Cross-Origin Resource Sharing (CORS) policy + +To use your GraphQL API with a browser-based application, add an entry in your Cross-Origin Resource Sharing (CORS) policy. +CORS is a browser-based security mechanism that prevents web pages from accessing resources from a server with a different origin. + +Add the URL `https://studio.apollographql.com` to the **Origin** box to enable the use of https://studio.apollographql.com/[Apollo Studio]. +If you need more entries, **Add allowed origin** for those. + +[NOTE] +==== +The URL entered in the CORS policy must be an exact match. +Wildcards are not supported. +==== + + +=== 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 set up multiple authentication providers and select a different one for each request. + +For the purpose of this tutorial, avoid setting up a JWKS endpoint, select **API Key** from the dropdown list and enter a name. +The API key will be shown after the GraphQL API key has been created. + +[CAUTION] +==== +It is not recommended to use API keys with user-facing applications that are using the GraphQL API. +This is due to the risk of the API key being visible to malicious users and very little control over GraphQL operations. + +A 3rd party identity provider with JWKS provides better security and allows for granular security rules, based on information within the JWKS token, to be defined within the type definitions to control GraphQL operations. +==== + + +=== Sizing + +Sizing a GraphQL API is based on the size and complexity of the type definitions and the expected workload. +Larger sizes have a higher hourly cost. +If the cost is not displayed, refer to the agreement you have with Neo4j. + + +== API key + +**Create** the GraphQL API. + +Your API key is now displayed. +Store this information securely as it cannot be retrieved again. +Confirm with **I understand** and **Close**. + +The GraphQL API will be provisioned. +You can see the status via **Data APIs** from the left side navigation. + + +== Create nodes in the database + +When the status for the GraphQL API is **Ready** you can send GraphQL requests to it. + + +=== Via cURL + +[source, bash, indent=0] +---- +curl --location --header 'Content-Type: application/json' --header 'x-api-key: ' --data '{ "query": "" }' +---- + +On the command line, execute: + +[source, bash, indent=0] +---- +curl --location --header 'Content-Type: application/json' --header 'x-api-key: ' --data '{ "query": "mutation { createProducts( input: [ { productName: \"New Product\" category: { create: [ { node: { categoryName: \"New Category\" } } ] } } ] ) { products { productName category { categoryName } } } }" }' +---- + +Verify by querying the data you just added: + +[source, bash, indent=0] +---- +curl --location --header 'Content-Type: application/json' --header 'x-api-key: ' --data '{ "query": "query { products { productName category { categoryName } } }" }' +---- + +You should see this: + +[source, bash, indent=0] +---- +{ "data": { "products": [ { "productName": "New Product", "category": [{ "categoryName": "New Category" }] } ] } } +---- + + +=== Via Apollo Server + +. On the https://studio.apollographql.com/sandbox/explorer[Apollo Studio] website, paste your GraphQL Data API URL to the **Sandbox** input. +. Use the cog icon and add `x-api-key` and the API key for your data API under **Shared headers** and **Save**. +. To start adding data, copy and paste the following mutation to the **Operation** panel to create a product and category in that product: ++ +[source, graphql, indent=0] +---- +mutation { + createProducts( + input: [ + { + productName: "New Product" + category: { create: [{ node: { categoryName: "New Category" } }] } + } + ] + ) { + products { + productName + category { + categoryName + } + } + } +} +---- + +. Use **Run** on the top right. +You should get the following confirmation that the data has been created in the database in the **Response** panel: ++ +[source, json, indent=0] +---- +{ + "data": { + "createProducts": { + "products": [ + { + "productName": "New Product", + "category": [ + { + "categoryName": "New Category" + } + ] + } + ] + } + } +} +---- + +. Query the data you just added. +Copy and paste the following query to the **Operations** panel: ++ +[source, graphql, indent=0] +---- +query { + products { + productName + category { + categoryName + } + } +} +---- ++ +Since you only created one "Product" node and one "Category" node, the **Response** panel shows the following: ++ +[source, json, indent=0] +---- +{ + "data": { + "products": [ + { + "productName": "New Product", + "category": [ + { + "categoryName": "New Category" + } + ] + } + ] + } +} +---- + + +This concludes the tutorial. +You now have a GraphQL Data API connected to a Neo4j AuraDB and you have added two nodes. + +To learn more, see xref:queries-aggregations/index.adoc[Queries and aggregations] and xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox]. +For more advanced database settings, refer to xref:driver-configuration.adoc[Driver configuration]. + +// Edit at: https://github.com/neo4j-graphacademy/courses/blob/main/asciidoc/courses/graphql-basics/promo.adoc +include::https://raw.githubusercontent.com/neo4j-graphacademy/courses/main/asciidoc/courses/graphql-basics/promo.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc b/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc new file mode 100644 index 00000000..1819f18d --- /dev/null +++ b/modules/ROOT/pages/getting-started/graphql-self-hosted.adoc @@ -0,0 +1,281 @@ += Self-hosting GraphQL + +This tutorial shows you how to: + +- Install the Neo4j GraphQL Library and its dependencies. +- Set type definitions that represent the structure of your graph database. +- Start an instance of the library to generate a GraphQL schema. +- Run an instance of a server to execute queries and mutations against your schema. + + +== Prerequisites + +- The tutorial assumes familiarity with the command line and JavaScript. +- 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. + + +== Set up a directory + +. Create a new directory and `cd` into it: ++ +[source, bash, indent=0] +---- +mkdir neo4j-graphql-example +cd neo4j-graphql-example +---- ++ +. Create a new Node.js project (with ESM modules enabled by using the es6 option): ++ +[source, bash, indent=0] +---- +npm init es6 --yes +---- ++ +. Create an empty `index.js` file which will contain all of the code for this tutorial: ++ +[source, bash, indent=0] +---- +touch index.js +---- + + +== Install dependencies + +Install the Neo4j GraphQL Library and its dependencies with: + +[source, bash, indent=0] +---- +npm install @neo4j/graphql graphql neo4j-driver @apollo/server +---- + +- `@neo4j/graphql` is the official Neo4j GraphQL Library package. +It takes your GraphQL type definitions and generates a schema backed by a Neo4j database. +- `graphql` is the package used to generate a schema and execute queries and mutations. +- `neo4j-driver` is the official Neo4j Driver package for JavaScript, of which an instance must be passed into the Neo4j GraphQL Library. + +Install a GraphQL server package to host your schema and allow the execution of queries and mutations against it. +The https://www.apollographql.com/docs/apollo-server/[`@apollo/server`] is the default package for Apollo Server. + + +== Add GraphQL type definitions + +The Neo4j GraphQL Library is driven by type definitions which map to the nodes and relationships in your Neo4j database. +Open the file `index.js` from xref:#_set_up_a_directory[] in your editor and paste the following type definitions alongside the necessary package imports: + +[source, javascript, indent=0] +---- +import { ApolloServer } from '@apollo/server'; +import { startStandaloneServer } from '@apollo/server/standalone'; +import { Neo4jGraphQL } from "@neo4j/graphql"; +import neo4j from "neo4j-driver"; + +const typeDefs = `#graphql + 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) + } +`; +---- + +These type definitions only define the node labels "Product" and "Category", and a relationship "PART_OF" between the two. +When the schema has been generated, you can execute queries for `products` and `category` to read data from the database. + +Note that you can alternatively generate type definitions automatically from an existing database by xref::introspector.adoc[introspecting the schema]. + + +== Create an instance of `Neo4jGraphQL` + +For a database located at the default "neo4j://localhost:7687" (see more about https://neo4j.com/docs/operations-manual/current/configuration/ports[port configuration]), with the username "username" and the password "password", add the following to the bottom of your `index.js` file: + +[source, javascript, indent=0] +---- +const driver = neo4j.driver( + "neo4j://localhost:7687", + neo4j.auth.basic("username", "password") +); + +const neoSchema = new Neo4jGraphQL({ typeDefs, driver }); +---- + + +== Create an instance of `ApolloServer` + +To create an Apollo Server instance using the generated schema, in which you can execute queries against it, add the following to the bottom of `index.js`: + +[source, javascript, indent=0] +---- +const server = new ApolloServer({ + schema: await neoSchema.getSchema(), +}); + +const { url } = await startStandaloneServer(server, { + listen: { port: 4000 }, +}); + +console.log(`🚀 Server ready at ${url}`); +---- + + +== Start the server + +Make sure that your `index.js` file looks like this full example: + +[source, javascript] +---- +import { ApolloServer } from '@apollo/server'; +import { startStandaloneServer } from '@apollo/server/standalone'; +import { Neo4jGraphQL } from "@neo4j/graphql"; +import neo4j from "neo4j-driver"; + +const typeDefs = `#graphql + 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) + } +`; + +const driver = neo4j.driver( + "neo4j://localhost:7687", + neo4j.auth.basic("username", "password") +); + +const neoSchema = new Neo4jGraphQL({ typeDefs, driver }); + +const server = new ApolloServer({ + schema: await neoSchema.getSchema(), +}); + +const { url } = await startStandaloneServer(server, { + context: async ({ req }) => ({ req }), + listen: { port: 4000 }, +}); + +console.log(`🚀 Server ready at ${url}`); +---- + +You are ready to start up your GraphQL server. +Back in the command line, run: + +[source, bash, indent=0] +---- +node index.js +---- + +If successful, you should see the following output: + +[source, bash, indent=0] +---- +🚀 Server ready at http://localhost:4000/ +---- + +The address http://localhost:4000/ is the URL where the Apollo Server starts. + + +== Create nodes in the database + +. Visit http://localhost:4000/ in your web browser. +You should get redirected to the Apollo Sandbox. + +. At the moment your database is empty. +To start adding data, copy and paste the following mutation to the **Operation** panel to create a product and a category in that product: ++ +[source, graphql, indent=0] +---- +mutation { + createProducts( + input: [ + { + productName: "New Product" + category: { create: [{ node: { categoryName: "New Category" } }] } + } + ] + ) { + products { + productName + category { + categoryName + } + } + } +} +---- + +. Use **Run** on the top right. +You should get the following confirmation that the data has been created in the database in the **Response** panel: ++ +[source, json, indent=0] +---- +{ + "data": { + "createProducts": { + "products": [ + { + "productName": "New Product", + "category": [ + { + "categoryName": "New Category" + } + ] + } + ] + } + } +} +---- + +. Query the data you just added. +Copy and paste the following query to the **Operations** panel: ++ +[source, graphql, indent=0] +---- +query { + products { + productName + category { + categoryName + } + } +} +---- ++ +Since you only created one "Product" node and one "Category" node, the **Response** panel shows the following: ++ +[source, json, indent=0] +---- +{ + "data": { + "products": [ + { + "productName": "New Product", + "category": [ + { + "categoryName": "New Category" + } + ] + } + ] + } +} +---- + +This concludes the tutorial. +You now have a GraphQL API connected to a Neo4j database and you have added two nodes. + +To learn more, see xref:queries-aggregations/index.adoc[Queries and aggregations] and xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox]. +For more advanced database settings, refer to xref:driver-configuration.adoc[Driver configuration]. + +// Edit at: https://github.com/neo4j-graphacademy/courses/blob/main/asciidoc/courses/graphql-basics/promo.adoc +include::https://raw.githubusercontent.com/neo4j-graphacademy/courses/main/asciidoc/courses/graphql-basics/promo.adoc[] diff --git a/modules/ROOT/pages/getting-started/index.adoc b/modules/ROOT/pages/getting-started/index.adoc index 2320ba46..0b56a255 100644 --- a/modules/ROOT/pages/getting-started/index.adoc +++ b/modules/ROOT/pages/getting-started/index.adoc @@ -2,296 +2,9 @@ = Creating a new project :description: This section describes how to get started with the Neo4j GraphQL Library. - -This tutorial walks you through creating a new project with the Neo4j GraphQL Library. - -This tutorial shows you how to: - -- Install the Neo4j GraphQL Library and its dependencies. -- Set type definitions that represent the structure of your graph database. -- Start an instance of the library to generate a GraphQL schema. -- Run an instance of a server to execute queries and mutations against your schema. - -The tutorial assumes familiarity with command line and JavaScript, and also that you have a recent version of Node.js installed. -The examples use the default `npm` package manager, but you can use another one of choice. - -== Create a new project - -. Create a new directory and `cd` into it: -+ -[source, bash, indent=0] ----- -mkdir neo4j-graphql-example -cd neo4j-graphql-example ----- -+ -. Create a new Node.js project (with ESM modules enabled by using the es6 option): -+ -[source, bash, indent=0] ----- -npm init es6 --yes ----- -+ -. Create an empty `index.js` file which will contain all of the code for this tutorial: -+ -[source, bash, indent=0] ----- -touch index.js ----- - -== Install dependencies - -. Install the Neo4j GraphQL Library and its dependencies: -+ -.. `@neo4j/graphql`: the official Neo4j GraphQL Library package. -It takes your GraphQL type definitions and generates a schema backed by a Neo4j database. -.. `graphql`: the package used to generate a schema and execute queries and mutations. -.. `neo4j-driver`: the official Neo4j Driver package for JavaScript, of which an instance must be passed into the Neo4j GraphQL Library. - -. Install a GraphQL server package to host your schema and allow the execution of queries and mutations against it. -.. The https://www.apollographql.com/docs/apollo-server/[`@apollo/server`] is the default package for Apollo Server: -+ -[source, bash, indent=0] ----- -npm install @neo4j/graphql graphql neo4j-driver @apollo/server ----- - -. Set up a https://neo4j.com[Neo4j database]. -Make sure it fulfills the xref::index.adoc#_requirements[requirements], including the necessary plugins. - -== Set GraphQL type definitions - -The Neo4j GraphQL Library is primarily driven by type definitions which map to the nodes and relationships in your Neo4j database. -To get started, use a simple example with two node types, one with label "Actor" and the other "Movie": - -. Open the previously created `index.js` in your editor of choice and write your type definitions. -Add all of the necessary package imports: -+ -[source, javascript, indent=0] ----- -import { ApolloServer } from '@apollo/server'; -import { startStandaloneServer } from '@apollo/server/standalone'; -import { Neo4jGraphQL } from "@neo4j/graphql"; -import neo4j from "neo4j-driver"; - -const typeDefs = `#graphql - type Movie @node { - title: String - actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) - } - - type Actor @node { - name: String - movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT) - } -`; ----- -+ -Note that these type definitions only *define* the node labels "Actor" and "Movie", and a relationship "ACTED_IN" between the two. -When the schema is generated, you can then execute queries for `actors` and `movies` to read data from the database. - -. Alternatively, you can also automatically generate type definitions from an existing database by xref::introspector.adoc[introspecting the schema]. - -== Create an instance of `Neo4jGraphQL` - -To create an instance of the Neo4j GraphQL Library, you need a Neo4j driver to connect to your database. - -=== Using AuraDB - -. For an AuraDB database, https://neo4j.com/cloud/platform/aura-graph-database/?ref=docs-graphql[create an instance]. - -. Make sure to save the generated password and the connection URI provided after the instance is ready and looking similar to this: -+ -image::neo4j-aura-dashboard.png[width=500] - -=== Using a Neo4j database - -For a database located at the default "neo4j://localhost:7687" (see more about https://neo4j.com/docs/operations-manual/current/configuration/ports[port configuration]), with the username "username" and the password "password", add the following to the bottom of your `index.js` file: - -[source, javascript, indent=0] ----- -const driver = neo4j.driver( - "neo4j://localhost:7687", - neo4j.auth.basic("username", "password") -); - -const neoSchema = new Neo4jGraphQL({ typeDefs, driver }); ----- - -== Create an instance of `ApolloServer` - -To create an Apollo Server instance using the generated schema, in which you can execute queries against it, add the following to the bottom of `index.js`: - -[source, javascript, indent=0] ----- -const server = new ApolloServer({ - schema: await neoSchema.getSchema(), -}); - -const { url } = await startStandaloneServer(server, { - listen: { port: 4000 }, -}); - -console.log(`🚀 Server ready at ${url}`); ----- - -== Start the server - - -Make sure that your `index.js` file looks like this: - -[source, javascript] ----- -import { ApolloServer } from '@apollo/server'; -import { startStandaloneServer } from '@apollo/server/standalone'; -import { Neo4jGraphQL } from "@neo4j/graphql"; -import neo4j from "neo4j-driver"; - -const typeDefs = `#graphql - type Movie @node { - title: String - actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) - } - - type Actor @node { - name: String - movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT) - } -`; - -const driver = neo4j.driver( - "neo4j://localhost:7687", - neo4j.auth.basic("username", "password") -); - -const neoSchema = new Neo4jGraphQL({ typeDefs, driver }); - -const server = new ApolloServer({ - schema: await neoSchema.getSchema(), -}); - -const { url } = await startStandaloneServer(server, { - context: async ({ req }) => ({ req }), - listen: { port: 4000 }, -}); - -console.log(`🚀 Server ready at ${url}`); ----- - -You are ready to start up your GraphQL server. -Back in the command line, run: - -[source, bash, indent=0] ----- -node index.js ----- - -If successful, you should see the following output: - -[source, bash, indent=0] ----- -🚀 Server ready at http://localhost:4000/ ----- - -The address http://localhost:4000/ is the URL where the Apollo Server starts. - - -== Create nodes in the database - -. Visit http://localhost:4000/ in your web browser. -You should get redirected to the Apollo Sandbox: -+ -image::apollo-server-landing-page.png[] - -. At the moment your database is empty. -To start adding data, copy and paste the following mutation to the Operation panel to create a movie and an actor in that movie: -+ -[source, graphql, indent=0] ----- -mutation { - createMovies( - input: [ - { - title: "Forrest Gump" - actors: { create: [{ node: { name: "Tom Hanks" } }] } - } - ] - ) { - movies { - title - actors { - name - } - } - } -} ----- - -. Click the "Run" button on the top right. -You should get the following confirmation that the data has been created in the database in the Response panel: -+ -[source, json, indent=0] ----- -{ - "data": { - "createMovies": { - "movies": [ - { - "title": "Forrest Gump", - "actors": [ - { - "name": "Tom Hanks" - } - ] - } - ] - } - } -} ----- - -. Query the data which you just added. -Copy and paste the following query to the Operations panel: -+ -[source, graphql, indent=0] ----- -query { - movies { - title - actors { - name - } - } -} ----- -+ -Since you only created one "Movie" node and one "Actor", the Response panel shows the following: -+ -[source, json, indent=0] ----- -{ - "data": { - "movies": [ - { - "title": "Forrest Gump", - "actors": [ - { - "name": "Tom Hanks" - } - ] - } - ] - } -} ----- - -== Conclusion - -This concludes the tutorial. -By now, you should have a GraphQL API connected to a Neo4j database, to which you added two nodes. - -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. +See xref::getting-started/graphql-aura.adoc[] for how to set up a GraphQL Data API in Aura. +Alternatively, learn how to set up a self-hosted GraphQL project in xref:getting-started/graphql-self-hosted.adoc[]. // Edit at: https://github.com/neo4j-graphacademy/courses/blob/main/asciidoc/courses/graphql-basics/promo.adoc -include::https://raw.githubusercontent.com/neo4j-graphacademy/courses/main/asciidoc/courses/graphql-basics/promo.adoc[] +include::https://raw.githubusercontent.com/neo4j-graphacademy/courses/main/asciidoc/courses/graphql-basics/promo.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/getting-started/toolbox.adoc b/modules/ROOT/pages/getting-started/toolbox.adoc index 6a736819..0ecba78c 100644 --- a/modules/ROOT/pages/getting-started/toolbox.adoc +++ b/modules/ROOT/pages/getting-started/toolbox.adoc @@ -12,58 +12,68 @@ With it, you can: . Build the Neo4j GraphQL schema. . Experiment, query, and play. + == 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. You can use https://neo4j.com/docs/desktop-manual/current/[Neo4j Desktop] or https://neo4j.com/docs/aura/auradb/[Neo4j AuraDB] for that. + == Set the type definitions -. Set your type definitions directly in the Toolbox editor or introspect the Neo4j database you connected to. -+ -If you followed the xref:getting-started/index.adoc[Getting started tutorial], you should see these type definitions in the GraphQL Toolbox: -+ +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: + [source, graphql, indent=0] ---- -type Actor @node { - actedInMovies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT) - name: String! +type Product @node { + productName: String + category: [Category!]! @relationship(type: "PART_OF", direction: OUT) } -type Movie @node { - actorsActedIn: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) - title: String! +type Category @node { + categoryName: String + products: [Product!]! @relationship(type: "PART_OF", direction: IN) } ---- -+ + image::toolbox-schema-view.png[GraphQL Toolbox schema view] -. Click the button "Build schema" and then go to the Query editor tab. +[NOTE] +==== +If you modified your database after following the xref:getting-started/graphql-self-hosted.adoc[self-hosted GraphQL tutorial], you may see different introspection results. +==== -. Query the Neo4j database using the autogenerated GraphQL queries and mutations from the `@neo4j/graphql` library: + +== Build the schema and query the database + +**Build schema** which takes you to **Query editor** tab. + +Query the Neo4j database. Paste the following or interact with the autogenerated GraphQL queries and mutations from the `@neo4j/graphql` library from the **Explorer**: + [source, graphql, indent=0] ---- { - actors { - name + products { + productName } } ---- -+ + image::toolbox-editor-view.png[GraphQL Toolbox editor view] -The query returns the name of the single actor in the database: +The query returns the name of the single product in the database: [source, graphql, indent=0] ---- -{ "data": { "actors": [{ "name": "Tom Hanks" }] } } +{ "data": { "products": [{ "productName": "New Product" }] } } ---- + == Store type definitions as favorite You can store your type definitions as favorites and access a range of settings to work with. +In the **Type definitions** tab, the star icon will will save it as a favorite: -. Go to the Type definitions tab and click on the star icon to save it as a favorite: -+ image:toolbox-favorite.png[Save a type definition as favorite] diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 58e796c9..8da8abb2 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -10,44 +10,46 @@ This avoids duplicate schema work and ensures flawless integration between front 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. -[NOTE] -==== -The GRANDstack starter app has been deprecated. -For more information, read the section on xref::deprecations.adoc[Deprecations]. -==== == 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. -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. +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] and xref::queries-aggregations/sorting.adoc[Sorting] options. +- 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::/queries-aggregations/pagination.adoc[Pagination] options. - 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 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. +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. -In the xref::getting-started/index.adoc[Getting Started] guide, Apollo Server is being used for demonstration. -You can check their own documentation about https://www.apollographql.com/docs/apollo-server/deployment[Deployment] for more details. + +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 @@ -66,10 +68,11 @@ Additionally, prerelease version numbers may have additional suffixes, for examp `NUMBER` in the suffix is simply an incrementing release number in each phase. + == Requirements -. https://neo4j.com/deployment-center/#gdb-selfmanaged[Neo4j Database] or https://neo4j.com/product/auradb/[Neo4j AuraDB] version 5.x with APOC core plugin. Note that with version 5.15 or higher you are using using the xref:/directives/indexes-and-constraints.adoc#_vector_index_search[`@vector` directive]. -. https://nodejs.org/en/[Node.js] 20+. +. 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 @@ -77,6 +80,7 @@ Additionally, prerelease version numbers may have additional suffixes, for examp . https://github.com/neo4j/graphql/issues[Issue Tracker] . https://www.npmjs.com/package/@neo4j/graphql[npm package] + == License ifndef::backend-pdf[] diff --git a/modules/ROOT/pages/security/subscriptions-authorization.adoc b/modules/ROOT/pages/security/subscriptions-authorization.adoc index 536de37b..907df6a2 100644 --- a/modules/ROOT/pages/security/subscriptions-authorization.adoc +++ b/modules/ROOT/pages/security/subscriptions-authorization.adoc @@ -2,6 +2,11 @@ :description: This page describes how to set up authorization features for subscriptions in the Neo4j GraphQL Library. = Subscriptions authorization +[NOTE] +==== +Data APIs created in Aura Console currently do not support the `subscriptionsAuthorization` directive. +==== + Subscriptions require their own authorization rules, which are configured with the `@subscriptionsAuthorization` directive. These rules are different to authorization rules for queries and mutations because they use filtering rules available for subscriptions events. These filtering rules can only be used to filter against the properties of the nodes impacted by the events.