diff --git a/docs/modules/ROOT/content-nav.adoc b/docs/modules/ROOT/content-nav.adoc index 6b6cdde6..fa5f9706 100644 --- a/docs/modules/ROOT/content-nav.adoc +++ b/docs/modules/ROOT/content-nav.adoc @@ -4,6 +4,7 @@ ** xref:getting-started/querying.adoc[] ** xref:getting-started/filters-and-projections.adoc[] ** xref:getting-started/relationships-and-advanced-filtering.adoc[] +** xref:getting-started/connecting-to-neo4j.adoc[] * xref:functions.adoc[] * xref:procedures.adoc[] * xref:patterns.adoc[] diff --git a/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc b/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc new file mode 100644 index 00000000..5577bca5 --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc @@ -0,0 +1,124 @@ +[[connecting-to-neo4j]] +:description: "This tutorial demonstrates how to execute your Cypher Builder queries in a Neo4j instance using the Neo4j Javascript driver. += Connecting to Neo4j + +The Cypher Builder library helps you compose Cypher queries, but sending these to Neo4j must be done separately through a link:https://www.npmjs.com/package/neo4j-driver[Neo4j driver]. +This tutorial demonstrates how you can do that. + + +== Setup the project + +. Initialize your project by following the instructions in the xref:/getting-started/installation.adoc[Installation] page. + +. To connect to Neo4j, make sure you have both `@neo4j/cypher-builder` and `neo4j-driver` installed in your NodeJS project: ++ +[source, cmd] +---- +npm install @neo4j/cypher-builder neo4j-driver +---- ++ +For this example, the https://neo4j.com/docs/getting-started/appendix/example-data[Movies dataset] is used. +Alternatively, you can create entries with the following Cypher examples: ++ +[source, cypher] +---- +CREATE(:Movie {title: "The Matrix"}) +CREATE(:Movie {title: "The Terminal"}) +---- + +== Initialize the driver +Add the following lines to the JavaScript file created in the xref:/getting-started/installation.adoc[Installation] step to initialize the driver:``` + +I think the link to the JS manual makes it a bit confusing here because the instructions are also featured below, so if that makes sense, removing that notion can be a bit more clarifying. + + +[source, javascript] +---- +import Cypher from "@neo4j/cypher-builder"; +import neo4j from "neo4j-driver"; + +const driver = neo4j.driver("neo4j://localhost", neo4j.auth.basic("neo4j", "password")); +---- + +== Construct your Cypher query + +You can compose any query by using the Cypher object. +For instance, this query: + +[source, javascript] +---- +const movie = new Cypher.Node({ labels: ["Movie"] }); +const query = new Cypher.Match(movie).return([movie.property("title"), "title"]); +---- + +Will translate to: + +[source, cypher] +---- +MATCH (this0:Movie) +RETURN this0.title AS title +---- + +== Execute the query + +Use `.build` in the query object to generate the Cypher query and the necessary parameters to pass to `neo4j-driver`: + + +[source, javascript] +---- +const { cypher, params } = query.build(); +const { records } = await driver.executeQuery(cypher, params); +---- + +When you are finished, close the driver connection: + +[source, javascript] +---- +await driver.close(); +---- + + +== Consume the results + +The `records` object can be consumed as explained in the link:https://neo4j.com/docs/javascript-manual/current/transactions/[JavaScript Driver documentation]: + +[source, javascript] +---- +for (const record of records) { + console.log(record.get("title")); +} +---- + +With the xref:getting-started/connecting-to-neo4j.adoc#_initialize_the_driver[previous example data], this should output: + +[source] +---- +The Matrix +The Terminal +---- + + +== Conclusion + +After following the steps here described, your script should look like this: + + +[source, javascript] +---- +import Cypher from "@neo4j/cypher-builder"; +import neo4j from "neo4j-driver"; + +const driver = neo4j.driver("neo4j://localhost", neo4j.auth.basic("neo4j", "password")); + +const movie = new Cypher.Node({ labels: ["Movie"] }); +const query = new Cypher.Match(movie).return([movie.property("title"), "title"]); + +const { cypher, params } = query.build(); +const { records } = await driver.executeQuery(cypher, params); + +await driver.close(); + +for (const record of records) { + console.log(record.get("title")); +} +----