|
1 | 1 | [[index]] |
2 | 2 | = Introduction |
3 | 3 | :page-aliases: introduction.adoc |
4 | | -:description: This section describes the Neo4j GraphQL Library. |
| 4 | +:description: An introduction to the Neo4j GraphQL Library. |
5 | 5 |
|
6 | 6 | 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. |
7 | 7 |
|
8 | | -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. |
9 | | -This avoids duplicate schema work and ensures flawless integration between frontend and backend developers. |
10 | | - |
11 | | -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. |
12 | | - |
13 | 8 |
|
14 | 9 | == How it works |
15 | 10 |
|
16 | | -The Neo4j GraphQL Library requires a set of type definitions that describes the shape of your graph data. |
17 | | -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. |
| 11 | +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. |
| 12 | + |
| 13 | +It generates an entire executable schema with all additional types needed to execute queries and mutations to interact with your Neo4j database. |
| 14 | + |
| 15 | +For example, consider these type definitions: |
| 16 | + |
| 17 | +[source, graphql, indent=0] |
| 18 | +---- |
| 19 | +type Product @node { |
| 20 | + productName: String |
| 21 | + category: [Category!]! @relationship(type: "PART_OF", direction: OUT) |
| 22 | +} |
| 23 | +
|
| 24 | +type Category @node { |
| 25 | + categoryName: String |
| 26 | + products: [Product!]! @relationship(type: "PART_OF", direction: IN) |
| 27 | +} |
| 28 | +---- |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +The following mutation creates a new product as well as a new category: |
| 33 | + |
| 34 | +[source, graphql, indent=0] |
| 35 | +---- |
| 36 | +mutation { |
| 37 | + createProducts( |
| 38 | + input: [ |
| 39 | + { |
| 40 | + productName: "New Product" |
| 41 | + category: { create: [{ node: { categoryName: "New Category" } }] } |
| 42 | + } |
| 43 | + ] |
| 44 | + ) { |
| 45 | + products { |
| 46 | + productName |
| 47 | + category { |
| 48 | + categoryName |
| 49 | + } |
| 50 | + } |
| 51 | + } |
| 52 | +} |
| 53 | +---- |
| 54 | + |
| 55 | +Here is an example of how you can query existing data: |
| 56 | + |
| 57 | +[source, graphql, indent=0] |
| 58 | +---- |
| 59 | +query { |
| 60 | + products { |
| 61 | + productName |
| 62 | + category { |
| 63 | + categoryName |
| 64 | + } |
| 65 | + } |
| 66 | +} |
| 67 | +---- |
| 68 | + |
| 69 | +The response looks like this: |
| 70 | + |
| 71 | +[source, json, indent=0] |
| 72 | +---- |
| 73 | +{ |
| 74 | + "data": { |
| 75 | + "products": [ |
| 76 | + { |
| 77 | + "productName": "New Product", |
| 78 | + "category": [ |
| 79 | + { |
| 80 | + "categoryName": "New Category" |
| 81 | + } |
| 82 | + ] |
| 83 | + } |
| 84 | + ] |
| 85 | + } |
| 86 | +} |
| 87 | +---- |
18 | 88 |
|
19 | 89 | 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. |
20 | 90 | This eliminates the https://www.google.com/search?q=graphql+n%2B1[N+1 Problem], which can make GraphQL implementations slow and inefficient. |
21 | 91 |
|
22 | | -The Neo4j GraphQL Library features: |
| 92 | +See xref:integrating-the-library.adoc[] to learn how to use the GraphQL Library in your technology stack. |
| 93 | +Check out xref:getting-started/index.adoc[] to create a new project, either based on Neo4j Aura or self-hosted. |
| 94 | + |
| 95 | + |
| 96 | +== Library features |
23 | 97 |
|
24 | 98 | - Automatic generation of xref::queries-aggregations/queries.adoc[Queries] and xref::mutations/index.adoc[Mutations] for CRUD interactions. |
25 | 99 | - xref::/types/index.adoc[Types], including temporal and spatial. |
26 | 100 | - Support for both node and relationship properties. |
27 | | -- Extensibility through the xref::/directives/custom-logic.adoc#_cypher[`@cypher` directive] and/or xref::/directives/custom-logic.adoc#_customresolver[Custom Resolvers]. |
28 | 101 | - Extensive xref::filtering.adoc[Filtering], xref::queries-aggregations/sorting.adoc[Sorting] and xref::/queries-aggregations/pagination.adoc[Pagination] options. |
29 | | -- Options for xref::/directives/database-mapping.adoc[Database mapping] and value xref::/directives/autogeneration.adoc[Autogeneration]. |
30 | 102 | - xref::/security/index.adoc[Security options] and additional xref::schema-configuration/index.adoc[Schema Configuration]. |
| 103 | +- xref:/subscriptions/index.adoc[Subscriptions] to server events. |
| 104 | +- xref:integrations/apollo-federation.adoc[Apollo federation integration]. |
| 105 | +- Extensibility through the xref::/directives/custom-logic.adoc#_cypher[`@cypher` directive] and/or xref::/directives/custom-logic.adoc#_customresolver[Custom Resolvers]. |
31 | 106 | - A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop. |
32 | 107 |
|
33 | 108 |
|
34 | | -== Interaction |
35 | | - |
36 | | -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. |
37 | | -In case you prefer to use frontend frameworks, these are some clients that interact with GraphQL APIs: |
38 | | - |
39 | | -- https://reactjs.org/[React] - support through https://www.apollographql.com/docs/react/[Apollo Client] |
40 | | -- https://vuejs.org/[Vue.js] - support through https://apollo.vuejs.org/[Vue Apollo] |
41 | | -- https://angularjs.org/[AngularJS] - support through https://apollo-angular.com/docs/[Apollo Angular]. |
42 | | - |
43 | | - |
44 | | -== Deployment |
45 | | - |
46 | | -There are a variety of methods for deploying GraphQL APIs. |
47 | | - |
48 | | -With Aura Console, you can create and use a GraphQL API, see xref::getting-started/graphql-aura.adoc[]. |
49 | | - |
50 | | -The xref::getting-started/graphql-self-hosted.adoc[] guide uses Apollo Server. |
51 | | -You can check the Apollo documentation on https://www.apollographql.com/docs/apollo-server/deployment[Deployment] for more details. |
52 | | - |
53 | | - |
54 | | -== Versioning |
55 | | - |
56 | | -The Neo4j GraphQL Library uses https://semver.org/[Semantic Versioning]. |
57 | | -Given a version number `MAJOR.MINOR.PATCH`, the increment is based on: |
58 | | - |
59 | | -- `MAJOR` - incompatible API changes compared to the previous `MAJOR` version, for which you will likely have to migrate |
60 | | -- `MINOR` - new features have been added in a backwards compatible manner |
61 | | -- `PATCH` - bug fixes have been added in a backwards compatible manner. |
62 | | - |
63 | | -Additionally, prerelease version numbers may have additional suffixes, for example `MAJOR.MINOR.PATCH-PRERELEASE.NUMBER`, where `PRERELEASE` is one of the following: |
64 | | - |
65 | | -- `alpha` - unstable prerelease artifacts, and the API may change between releases during this phase |
66 | | -- `beta` - feature complete prerelease artifacts, which will be more stable than `alpha` releases but will likely still contain bugs |
67 | | -- `rc` - release candidate including artifacts to be promoted to a stable release, in a last effort to find trailing bugs. |
68 | | - |
69 | | -`NUMBER` in the suffix is simply an incrementing release number in each phase. |
70 | | - |
71 | | - |
72 | | -== Requirements |
73 | | - |
74 | | -. 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. |
75 | | - |
76 | | - |
77 | 109 | == Resources |
78 | 110 |
|
79 | 111 | . https://github.com/neo4j/graphql[GitHub] |
|
0 commit comments