diff --git a/docs/modules/ROOT/pages/clauses/create.adoc b/docs/modules/ROOT/pages/clauses/create.adoc index d7e6c236..18a95b52 100644 --- a/docs/modules/ROOT/pages/clauses/create.adoc +++ b/docs/modules/ROOT/pages/clauses/create.adoc @@ -4,8 +4,7 @@ This page describes how to add a link:https://neo4j.com/docs/cypher-manual/current/clauses/create/[`CREATE`] clause with the `Cypher.Create` class. -To make a `CREATE` clause, first create a valid pattern using the xref:/patterns.adoc[Pattern] class: - +To add the `CREATE` clause, first create a valid pattern using the xref:/patterns.adoc[Pattern] class: [source, javascript] ---- @@ -39,8 +38,8 @@ This generates the following `CREATE` clause: CREATE (this:Movie {title: "The Matrix"}) ---- -== Relationships +== Relationships Relationships can be used in a match clause by creating the relevant xref:/patterns.adoc[Pattern]: @@ -62,9 +61,9 @@ CREATE (this1:`Person`)-[this0:ACTED_IN]->(this2:`Movie`) == Update properties -The clauses `SET` and `REMOVE` can be added with the methods `.set` and `.remove` respectively. +Add the `SET` and `REMOVE` clauses with the methods `.set` and `.remove` respectively. -`.set` take tuples of 2 elements, the first being the property to update and the second the value: +`.set` takes one or more tuples, each consisting of a property to update and a new value: [source, javascript] ---- @@ -82,7 +81,6 @@ SET this0.title = $param0 Multiple properties can be updated by passing multiple tuples. - `.remove` takes the properties to remove: [source, javascript] diff --git a/docs/modules/ROOT/pages/clauses/foreach.adoc b/docs/modules/ROOT/pages/clauses/foreach.adoc index c7c3251a..f3d968ea 100644 --- a/docs/modules/ROOT/pages/clauses/foreach.adoc +++ b/docs/modules/ROOT/pages/clauses/foreach.adoc @@ -4,7 +4,8 @@ This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/foreach/[`FOREACH`] clause using the `Cypher.Foreach` class. -A `Foreach` clause takes a single variable to be used in a loop. The methods `.in` and `.do` are used to defined the list and update clauses: +A `Foreach` clause takes a single variable to be used in a loop. +Use the `.in` and `.do` methods to define the list and update clauses respectively: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/clauses/load-csv.adoc b/docs/modules/ROOT/pages/clauses/load-csv.adoc index d15ee9d3..654fb274 100644 --- a/docs/modules/ROOT/pages/clauses/load-csv.adoc +++ b/docs/modules/ROOT/pages/clauses/load-csv.adoc @@ -2,7 +2,8 @@ :description: This page describes how to create `LOAD CSV` clauses. = Load CSV -This page describes how to create link:https://neo4j.com/docs/cypher-manual/current/clauses/load-csv/[`LOAD CSV`] clauses in Cypher with Cypher Builder. To achieve this, use the `LoadCSV` class: +This page describes how to create link:https://neo4j.com/docs/cypher-manual/current/clauses/load-csv/[`LOAD CSV`] clauses in Cypher with Cypher Builder. +To achieve this, use the `LoadCSV` class: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/clauses/match.adoc b/docs/modules/ROOT/pages/clauses/match.adoc index 139081af..6f075ef5 100644 --- a/docs/modules/ROOT/pages/clauses/match.adoc +++ b/docs/modules/ROOT/pages/clauses/match.adoc @@ -4,7 +4,7 @@ This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/match/[`MATCH`] clause with the `Cypher.Match` class. -To create a `MATCH` clause, first create a valid pattern using the xref:/patterns.adoc[Pattern] class and pass it to `Match` constructor: +To add the `MATCH` clause, first create a valid pattern using the xref:/patterns.adoc[Pattern] class and pass it to the `Match` constructor: [source, javascript] @@ -23,7 +23,8 @@ This generates the following `MATCH` clause: MATCH (this:Movie) ---- -Afterwards, other clauses can be added. For example: +Afterwards, other clauses can be added. +For example: [source, javascript] ---- @@ -32,16 +33,17 @@ const matchQuery = new Cypher.Match(pattern) .return(movie); ---- -Extra match clauses can also be chained: +You can also chain extra match clauses: [source, javascript] ---- const matchQuery = new Cypher.Match(pattern).match(pattern2).return(movie) ---- + == Relationships -Relationships can be used in a match clause by creating the relevant xref:/patterns.adoc[Pattern]: +You can use relationships in a match clause by creating the relevant xref:/patterns.adoc[Pattern]: [source, javascript] @@ -58,6 +60,7 @@ const matchQuery = new Cypher.Match(actedInPattern) MATCH (this0:Person)-[:ACTED_IN]->(this1:Movie) ---- + == Filtering with `WHERE` A `WHERE` clause can be appended with the `.where` method, this accepts any predicate: @@ -74,7 +77,7 @@ MATCH (this0:Movie) WHERE title = $param0 ---- -Multiple predicates can be chained by using the `.and` or `.where` method after `.where`: +You can chain multiple predicates by using the `.and` or `.where` method after `.where`: [source, javascript] ---- @@ -90,9 +93,10 @@ WHERE this0.title = $param0 AND this0.year <> $param1 ---- + === Logical filters -For more complex logical filters, the predicates `Cypher.and`, `Cypher.or`, `Cypher.not` and `Cypher.xor` can be used inside `where`: +For more complex logical filters, use the `Cypher.and`, `Cypher.or`, `Cypher.not` and `Cypher.xor` predicates inside `where`: [source, javascript] ---- @@ -111,6 +115,7 @@ MATCH (this0:Movie) WHERE ((this0.title = $param0 OR this0.year > $param1) AND this0.year <> $param2) ---- + === Filtering properties shorthand `.where` also supports passing a variable and an object with variables to check for equality of multiple values in a more concise way: @@ -130,7 +135,7 @@ WHERE (this0.id = $param0 AND this0.name = $param1) == Optional match -The clause link:https://neo4j.com/docs/cypher-manual/current/clauses/optional-match/[`OPTIONAL MATCH`] can be created in the same manner as `MATCH` by using the class `Cypher.OptionalMatch`: +You can create the clause link:https://neo4j.com/docs/cypher-manual/current/clauses/optional-match/[`OPTIONAL MATCH`] similarly to `MATCH` by using the class `Cypher.OptionalMatch`: [source, javascript] ---- @@ -140,7 +145,7 @@ const pattern = new Cypher.Pattern(movie, { labels: ["Movie"] }); const matchQuery = new Cypher.OptionalMatch(pattern); ---- -Alternatively, an existing `Match` instance can be transformed into an `OptionalMatch` with the method `.optional()`: +Alternatively, you can transform an existing `Match` instance into an `OptionalMatch` with the method `.optional()`: [source, javascript] ---- @@ -150,9 +155,10 @@ const pattern = new Cypher.Pattern(movie, { labels: ["Movie"] }); const matchQuery = new Cypher.Match(pattern).optional(); ---- + == Shortest paths -link:https://neo4j.com/docs/cypher-manual/current/patterns/shortest-paths/#shortest[Shortest paths] and its variations can be added in a Match clause with the following methods in `Cypher.Match`: +You can add link:https://neo4j.com/docs/cypher-manual/current/patterns/shortest-paths/#shortest[Shortest paths] and its variations in a Match clause with the following methods in `Cypher.Match`: * `.shortest(k)` * `.shortestGroups(k)` diff --git a/docs/modules/ROOT/pages/clauses/merge.adoc b/docs/modules/ROOT/pages/clauses/merge.adoc index d21bf263..dc731994 100644 --- a/docs/modules/ROOT/pages/clauses/merge.adoc +++ b/docs/modules/ROOT/pages/clauses/merge.adoc @@ -4,7 +4,7 @@ This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/merge/[`MERGE`] clause with the `Cypher.Merge` class. -To create a `Merge` clause, first create a valid pattern using the xref:/patterns.adoc[Pattern] class and pass it to `Merge` constructor: +To add a `MERGE` clause, first create a valid pattern using the xref:/patterns.adoc[Pattern] class and pass it to `Merge` constructor: [source, javascript] @@ -24,7 +24,8 @@ This generates the following `MERGE` clause: MERGE (this:Movie)-[:ACTED_IN]->(this1) ---- -Afterwards, other clauses can be added. For example: +Afterwards, you can add other clauses. +For example: [source, javascript] ---- @@ -40,9 +41,9 @@ WHERE this.name = $param1 return this ---- -== On Create / On Match +== `ON CREATE` and `ON MATCH` -A `MERGE` statement can be followed by `ON CREATE SET` and `ON MATCH SET`, this can be achieved with the methods `onCreateSet` and `onMatchSet` respectively: +Use the methods `onCreateSet` or `onMatchSet` to add `ON CREATE SET` or `ON MATCH SET` after a `MERGE` statement: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/clauses/return.adoc b/docs/modules/ROOT/pages/clauses/return.adoc index 39d96ca9..e590b4d9 100644 --- a/docs/modules/ROOT/pages/clauses/return.adoc +++ b/docs/modules/ROOT/pages/clauses/return.adoc @@ -4,7 +4,8 @@ This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/return/[`RETURN`] clause with the `Cypher.Return` class. -Return clauses can be created with `new Cypher.Return`, but more commonly they are created after an existing clause, such as `MATCH`, by using the method `.return`. +You can add return clauses with `new Cypher.Return`. +However, more commonly they are added after an existing clause, such as `MATCH`, by using the method `.return`. In both cases, the return variables can be passed as parameters: [source, javascript] @@ -27,16 +28,16 @@ Any expression can be passed to return, for example a function: const returnQuery = new Cypher.Return(Cypher.round(new Cypher.Param(2.3))); ---- -Which translates to: +This translates to: [source, cypher] ---- RETURN round($param1) ---- -## Aliasing results +== Aliasing results -Results can be aliased by using an array with two elements - the variable and the aliased name, which can be a string or a variable: +You can alias results by using an array with two elements - the variable and the aliased name, which can be a string or a variable: [source, javascript] ---- @@ -51,9 +52,9 @@ This generates the following clause: RETURN this0 AS my-node ---- -## Unique results +== Unique results -`DISTINCT` can be added to `RETURN` by using the `.distinct` method: +Add `DISTINCT` to `RETURN` by using the `.distinct` method: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/clauses/set.adoc b/docs/modules/ROOT/pages/clauses/set.adoc index 051e3b6b..43af7482 100644 --- a/docs/modules/ROOT/pages/clauses/set.adoc +++ b/docs/modules/ROOT/pages/clauses/set.adoc @@ -2,13 +2,13 @@ :description: This page describes how to create `SET` clauses. = Set -This page describes how to create link:https://neo4j.com/docs/cypher-manual/current/clauses/set/[`SET`] clauses. `SET` statements are appended to an a clause with the method `.set`. +This page describes how to create link:https://neo4j.com/docs/cypher-manual/current/clauses/set/[`SET`] clauses. +Append `SET` statements to a clause with the method `.set`. == Update properties with `SET` -The `.set` method is used to update xref:../variables-and-params/variables.adoc#_properties[properties] of a node or relationship. - +You can update xref:../variables-and-params/variables.adoc#_properties[properties] of a node or relationship with the `.set` method. For example, to update the properties of a node: [source, javascript] @@ -20,7 +20,7 @@ const matchQuery = new Cypher.Match(new Cypher.Pattern(personNode, { labels: ["P ); ---- -This will generate the following Cypher: +This generates the following Cypher: [source, cypher] ---- @@ -30,7 +30,7 @@ SET RETURN this0 ---- -Multiple pairs of property-expression can be passed to update multiple properties: +You can pass multiple pairs of property expressions to update multiple properties: [source, javascript] ---- @@ -42,7 +42,7 @@ const matchQuery = new Cypher.Match(new Cypher.Pattern(personNode, { labels: ["P ); ---- -This will generate the following Cypher: +This generates the following Cypher: [source, cypher] ---- @@ -56,7 +56,8 @@ RETURN this0 === Use `SET` to replace all node properties -To update all the properties of a node or relationship, instead of a property, pass the variable directly as the first element of the array. The second element must be a `Cypher.Map` or a variable: +To update all the properties of a node or relationship, instead of a property, pass the variable directly as the first element of the array. +The second element must be a `Cypher.Map` or a variable: [source, javascript] ---- @@ -70,7 +71,7 @@ const matchQuery = new Cypher.Match(new Cypher.Pattern(personNode, { labels: ["P ]); ---- -This generates the Cypher: +This generates the following Cypher: [source, cypher] @@ -97,7 +98,8 @@ SET this1 = this0 ---- -==== Using operator `+=` + +==== The `+=` operator When passing a map to update a node properties with `SET`, it is possible to use the operator `+=` to add new properties, instead of replacing them: @@ -113,7 +115,7 @@ const matchQuery = new Cypher.Match(new Cypher.Pattern(personNode, { labels: ["P ]); ---- -This generates the cypher: +This generates the following Cypher: [source, cypher] @@ -124,7 +126,7 @@ SET ---- +== `SET` with labels -== Set with labels - -Set can be used to update the labels of a node or the type of a relationship. More information on xref:../../how-to/update-labels.adoc#_add_labels[How to update labels]. +You can use `SET` to update the labels of a node or the type of a relationship. +For more information, see xref:../../how-to/update-labels.adoc#_add_labels[How to update labels]. diff --git a/docs/modules/ROOT/pages/clauses/union.adoc b/docs/modules/ROOT/pages/clauses/union.adoc index 249b77a1..917f0107 100644 --- a/docs/modules/ROOT/pages/clauses/union.adoc +++ b/docs/modules/ROOT/pages/clauses/union.adoc @@ -4,7 +4,8 @@ This page describes how to create link:https://neo4j.com/docs/cypher-manual/current/clauses/union/[`UNION`] clauses with the `Cypher.Union` class. -A union between multiple queries can be created by passing multiple clauses into a `Cypher.Union` class to combine them. Note that all clauses must be different instances, as Cypher Builder clauses cannot be reused: +Create a union between multiple queries by passing multiple clauses to the `Cypher.Union` class to combine them. +Note that all clauses must be different instances, as Cypher Builder clauses cannot be reused: [source, javascript] ---- @@ -35,10 +36,11 @@ RETURN this3 AS var1 Note that this example uses the extra variable `returnVar` to make sure that all the queries return the same variable name. + == Union all Unions remove duplicates by default. -To keep all the results, use the `.all()` method to create a `UNION ALL` clause instead: +To keep all results, use the `.all()` method to create a `UNION ALL` clause instead: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/clauses/use.adoc b/docs/modules/ROOT/pages/clauses/use.adoc index 4baaedc9..0f51466e 100644 --- a/docs/modules/ROOT/pages/clauses/use.adoc +++ b/docs/modules/ROOT/pages/clauses/use.adoc @@ -4,7 +4,7 @@ This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/use/[`USE`] clause with the `Cypher.Use` class. -To create an `Use` clause, you can pass an existing query to `Cypher.use` to prepend an `USE` statement before the query: +To create an `Use` clause, pass an existing query to `Cypher.use` to prepend a `USE` statement before the query: [source, javascript] diff --git a/docs/modules/ROOT/pages/clauses/with.adoc b/docs/modules/ROOT/pages/clauses/with.adoc index 3e309f6a..0d54294f 100644 --- a/docs/modules/ROOT/pages/clauses/with.adoc +++ b/docs/modules/ROOT/pages/clauses/with.adoc @@ -2,9 +2,11 @@ :description: This page describes how to create `WITH` clauses. = With -This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/with/[`WITH`] clause using the `Cypher.With` class. Note that this is different to the xref:../subqueries/call.adoc#_importwith[ImportWith] statement inside `CALL`. +This page describes how to create a link:https://neo4j.com/docs/cypher-manual/current/clauses/with/[`WITH`] clause using the `Cypher.With` class. +Note that this is different from the xref:../subqueries/call.adoc#_importwith[ImportWith] statement inside `CALL`. -A `With` clause will take multiple parameters. Variables can be passed directly without aliasing: +A `With` clause takes multiple parameters. +Pass variables directly without aliasing: [source, javascript] ---- @@ -20,7 +22,7 @@ WITH this0 == Aliasing -Any expression can be passed to `With` and aliased to a `Variable` to be used later in the query by passing a tuple of an expression and the aliaed variable: +You can pass any expression to `With` and alias it to a `Variable` to use it later in the query by passing a tuple of an expression and the aliased variable: [source, javascript] ---- @@ -33,7 +35,7 @@ new Cypher.With([new Cypher.Literal("Hello"), variable]); WITH "Hello" AS var0 ---- -A string can be used directly as the alias value, when the name is already known. +Use a string as the alias value if you already know the name: [source, javascript] ---- @@ -45,10 +47,11 @@ new Cypher.With([new Cypher.Literal("Hello"), "myVar"]); WITH "Hello" AS myVar ---- -== Wildcard +== Wildcard -`With` accepts the string `"*"` to add a wildcard to carry over all existing variables. This parameter cannot be aliased, and will always be added at the beginning of the `WITH` statement: +`With` accepts the string `"*"` to add a wildcard to carry over all existing variables. +This parameter cannot be aliased, and is always added at the beginning of the `WITH` statement: [source, javascript] diff --git a/docs/modules/ROOT/pages/compatibility.adoc b/docs/modules/ROOT/pages/compatibility.adoc index d6e69c41..6aea90c5 100644 --- a/docs/modules/ROOT/pages/compatibility.adoc +++ b/docs/modules/ROOT/pages/compatibility.adoc @@ -9,5 +9,6 @@ This page outlines the compatibility requirements for `@neo4j/cypher-builder` ve [NOTE] ==== -`@neo4j/cypher-builder` version 1 is no longer supported. Version 2 is a full replacement and maintains the same compatibility with Cypher and Node.js. +`@neo4j/cypher-builder` version 1 is no longer supported. +Version 2 is a full replacement and maintains the same compatibility with Cypher and Node.js. ==== diff --git a/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc b/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc index fc0cac54..02bb06ec 100644 --- a/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc +++ b/docs/modules/ROOT/pages/getting-started/connecting-to-neo4j.adoc @@ -1,14 +1,14 @@ [[connecting-to-neo4j]] -:description: "This tutorial demonstrates how to execute your Cypher Builder queries in a Neo4j instance using the Neo4j Javascript driver. +:description: This page 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. +This page 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. +. Initialize your project by following the instructions in xref:/getting-started/installation.adoc[Installation]. . To connect to Neo4j, make sure you have both `@neo4j/cypher-builder` and `neo4j-driver` installed in your NodeJS project: + @@ -17,8 +17,8 @@ This tutorial demonstrates how you can do that. 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: +For this example, the https://neo4j.com/docs/getting-started/appendix/example-data[movies data set] is used. +Alternatively, you can create entries with the following Cypher: + [source, cypher] ---- @@ -26,8 +26,9 @@ 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: +Add the following lines to the xref:/getting-started/installation.adoc[installation] JavaScript file to initialize the driver: [source, javascript] ---- @@ -37,10 +38,11 @@ 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: +For example: [source, javascript] ---- @@ -51,7 +53,7 @@ const query = new Cypher.Match(new Cypher.Pattern(movie, { labels: ["Movie"] })) ]); ---- -This will translate to: +This creates the following query: [source, cypher] ---- @@ -59,6 +61,7 @@ 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`: @@ -89,7 +92,7 @@ for (const record of records) { } ---- -With the xref:getting-started/connecting-to-neo4j.adoc#_initialize_the_driver[previous example data], this should output: +For the example data from xref:getting-started/connecting-to-neo4j.adoc#_setup_the_project[], this yields: [source] ---- @@ -100,7 +103,7 @@ The Terminal == Conclusion -After following the steps here described, your script should look like this: +Your script should look like this: [source, javascript] diff --git a/docs/modules/ROOT/pages/getting-started/filters-and-projections.adoc b/docs/modules/ROOT/pages/getting-started/filters-and-projections.adoc index f7a0fa21..fb1eb58c 100644 --- a/docs/modules/ROOT/pages/getting-started/filters-and-projections.adoc +++ b/docs/modules/ROOT/pages/getting-started/filters-and-projections.adoc @@ -1,10 +1,10 @@ [[filters-and-projections]] -:description: This tutorial shows how to use filters and projections in Cypher Builder. +:description: This page shows you how to use filters and projections in Cypher Builder. = Filters and projections -After learning how to write a basic `MATCH` and `RETURN` Cypher query in the xref:getting-started/querying.adoc[Querying] tutorial, you can now add filters and change the projection to only return some fields, as well as work with parameters. +After learning how to write a xref:getting-started/querying.adoc[basic Cypher query] using `MATCH` and `RETURN`, you can add filters and change the projection to only return some fields, as well as work with parameters. -This tutorial shows how to achieve the resulting query when using the link:https://neo4j.com/docs/getting-started/appendix/example-data/#built-in-examples[Movies Dataset]: +This page shows you how to achieve the resulting query when using the link:https://neo4j.com/docs/getting-started/appendix/example-data/#built-in-examples[movies data set]: [source, cypher] ---- @@ -13,8 +13,9 @@ WHERE (m.title = "The Matrix" AND m.released < 2000) RETURN m.title, m.tagline, m.released ---- -This query should return all movies with the title `"The Matrix"` released before the year of `2000`. -It should return only the movie "The Matrix", released in 1999. +This query returns all movies with the title `"The Matrix"` released before the year of `2000`. +It only returns the movie "The Matrix", released in 1999. + == Filtering @@ -37,7 +38,7 @@ const clause = new Cypher.Match(new Cypher.Pattern(movieNode, { labels: ["Movie" m.title = "The Matrix" ---- -.. Use the function `Cypher.eq()` to add an **eq**uality operator (`=`) in where: +.. Use the function `Cypher.eq()` to add an equality operator (`=`) to the where statement: + [source, javascript] ---- @@ -51,14 +52,14 @@ m.title = "The Matrix" movieNode.property("title") ---- -.. The second argument is the value to compare (`"The Matrix"`). Pass it as a link:https://neo4j.com/docs/cypher-manual/current/syntax/parameters/[Parameter] with `new Cypher.Param` +.. The second argument is the value to compare (`"The Matrix"`). Pass it as a link:https://neo4j.com/docs/cypher-manual/current/syntax/parameters/[parameter] with `new Cypher.Param`: + [source, javascript] ---- new Cypher.Param("The Matrix") ---- + -`Cypher.Param` will replace the string with a suitable `$param`, to avoid injecting values directly into the generated Cypher. +`Cypher.Param` replaces the string with a suitable `$param`, to avoid injecting values directly into the generated Cypher. . Your `MATCH` clause should now look like this: + @@ -70,7 +71,7 @@ const clause = new Cypher.Match(new (movieNode, { labels: ["Movie"] })) ---- . Run the script again (`node main.js`). -You should now get the following Cypher: +This results in the following Cypher: + [source, cypher] ---- @@ -79,8 +80,8 @@ WHERE this0.title = $param0 RETURN this0 ---- + -That means `Movie` is now filtered by its title to a param, but the param itself is missing from the output. -To fix that, you need to modify the build process at the end of the script: +It filters `Movie` nodes by their title when they match a parameter, but the parameter itself is missing from the output. +To fix that, modify the build process at the end of the script: + [source, javascript] ---- @@ -103,6 +104,7 @@ RETURN this0 { param0: 'The Matrix' } ---- + === `AND` filtering Here is how to add an `AND` filter to your query: @@ -117,9 +119,10 @@ Here is how to add an `AND` filter to your query: + This takes the same parameters as `.where` and ensures the proper concatenation of the filters with `AND`. + -In this case, the function `Cypher.lt` will add the operator `<` (**l**ower **t**han) and, like before, the comparison happens between a property of `movieNode` and a param. +In this case, the function `Cypher.lt` adds the operator `<` (less than). +Like before, a property of `movieNode` is compared to a parameter. -. Run the script again. You should get these results: +. Run the script again to get these results: + [source, cypher] ---- @@ -137,12 +140,13 @@ RETURN this0 ==== The `AND` operation automatically adds parentheses to ensure operation precedence. This is an important feature when dealing with complex and nested filters. -See more information about xref:getting-started/relationships-and-advanced-filtering.adoc[Advanced filtering]. +For more information see xref:getting-started/relationships-and-advanced-filtering.adoc[Advanced filtering]. ==== + == Projection -Returning the full node is usually not necessary, but you can do that by explicitly setting a projection in `RETURN`. +Returning the full node is not necessary, but you can do that by explicitly setting a projection in `RETURN`. For example: [source, cypher] @@ -157,7 +161,7 @@ To define these columns, you can pass the variables into the `.return` method: .return(movieNode.property("title"), movieNode.property("tagline"), movieNode.property("year")); ---- -The returned Cypher now should have the explicit projection: +The returned Cypher has the explicit projection: [source, cypher] ---- @@ -166,12 +170,13 @@ WHERE (this0.title = $param0 AND this0.released < $param1) RETURN this0.title, this0.tagline, this0.released ---- + === Reusing variables -The current query is filtering and returning the properties `id` and `title` of the `Movie` nodes. -However, relying on the name of the properties might make maintenance unecessarily more difficult. +The query so far filters and returns the properties `id` and `title` of the `Movie` nodes. +However, relying on the name of the properties might make maintenance unecessarily difficult. -To avoid that scenario, make sure both filters and projections use the same property variable (in this case, `movieNode.`): +To avoid that, make sure both filters and projections use the same property variable (in this case, `movieNode.`): [source, javascript] ---- @@ -185,18 +190,19 @@ const clause = new Cypher.Match(movieNode) .return(titleProp, taglineProp, yearProp); ---- -That should keep different parts of the query in sync and also make the clause itself shorter. +This should keep different parts of the query in sync and also make the clause itself shorter. [NOTE] ==== -Params can also be assigned to a variable and be reused. +Parameters can also be assigned to a variable and be reused. This can be particularly useful when having multiple filters over the same parameter. See an example in xref:getting-started/relationships-and-advanced-filtering.adoc#_boolean_operations[Relationships and advanced filtering]. ==== + == Conclusion -After going through all the steps previously described, your script should look like this: +Your script should look like this: [source, javascript] ---- @@ -220,7 +226,7 @@ console.log(cypher); console.log(params); ---- -And its execution should show the following query: +It results in the following query: [source, cypher] ---- @@ -234,6 +240,6 @@ RETURN this0.title, this0.tagline, this0.released { param0: 'The Matrix', param1: 2000 } ---- -With this, you already have the tools to write simple queries and to add parameters to it. +You can now add parameters to simple queries. Refer to xref:/getting-started/relationships-and-advanced-filtering.adoc[Relationships and advanced filtering] to learn how to add relationships and more advanced filters to this query. diff --git a/docs/modules/ROOT/pages/getting-started/installation.adoc b/docs/modules/ROOT/pages/getting-started/installation.adoc index 55ec1863..cfdbbc46 100644 --- a/docs/modules/ROOT/pages/getting-started/installation.adoc +++ b/docs/modules/ROOT/pages/getting-started/installation.adoc @@ -1,14 +1,16 @@ [[installation]] -:description: This guide shows how to start using Cypher Builder. +:description: This page shows you how to install Cypher Builder. = Installation -This guide shows how to start using Cypher Builder by setting up a Node.js project with `@neo4j/cypher-builder`. +This page shows you how to set up a Node.js project with `@neo4j/cypher-builder`. + == Requirements * link:https://nodejs.org/[Node.js] 16.0.0 or greater * link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[npm] -* **[Optional]** A link:https://neo4j.com/cloud/platform/aura-graph-database/?ref=nav-get-started-cta[Neo4j] database to try Cypher queries. +* **[Optional]** A link:https://neo4j.com/cloud/platform/aura-graph-database/?ref=nav-get-started-cta[Neo4j database] where you can try Cypher queries + == Instructions diff --git a/docs/modules/ROOT/pages/getting-started/querying.adoc b/docs/modules/ROOT/pages/getting-started/querying.adoc index 6837427a..bdb608e3 100644 --- a/docs/modules/ROOT/pages/getting-started/querying.adoc +++ b/docs/modules/ROOT/pages/getting-started/querying.adoc @@ -1,8 +1,8 @@ [[querying]] -:description: This guide shows how to create a simple Cypher query to `MATCH` and `RETURN` Movies using the Cypher Builder. +:description: This page shows you how to create a Cypher query to retrieve movie data using the Cypher Builder. = Querying -This guide shows how to create a simple Cypher query to `MATCH` and `RETURN` Movies using the Cypher Builder: +This page shows you how to create the following simple Cypher query to `MATCH` and `RETURN` movies using the Cypher Builder: [source, cypher] ---- @@ -10,6 +10,7 @@ MATCH(m:Movie) RETURN m ---- + == Instructions . Define a node variable by creating a new instance of `Cypher.Node`: @@ -34,14 +35,14 @@ const matchPattern = new Cypher.Pattern(movieNode, { labels: ["Movie"] }); const clause = new Cypher.Match(matchPattern); ---- -. To `RETURN` the Node variables, use the `.return` method in the `MATCH` clause: +. To `RETURN` the node variables, use the `.return` method in the `MATCH` clause: + [source, javascript] ---- clause.return(movieNode); ---- -.. Alternatively, you can do the same thing by creating the clause in a single statement: +.. Alternatively, you can do the same by creating the clause with a single statement: + [source, javascript] ---- @@ -49,7 +50,7 @@ const clause = new Cypher.Match(matchPattern).return(movieNode); ---- . After the query is ready, it is time to build it. -This step will generate the actual Cypher string that can be used in a Neo4j database: +This step generates the actual Cypher string that can be used in a Neo4j database: + [source, javascript] ---- @@ -58,9 +59,10 @@ const { cypher } = clause.build(); console.log(cypher); ---- + == Conclusion -Altogether, your script should look like this: +Your full script should look like this: [source, javascript] ---- @@ -76,7 +78,7 @@ const { cypher } = clause.build(); console.log(cypher); ---- -Now, if you execute `node main.js` again, it will output the following query: +If you execute `node main.js` again, it outputs the following query: [source, cypher] ---- @@ -86,5 +88,5 @@ RETURN this0 [NOTE] ==== -Note that `this0` is an autogenerated name for the Node variable created by the Cypher Builder. +Note that `this0` is an autogenerated name for the node variable created by the Cypher Builder. ==== diff --git a/docs/modules/ROOT/pages/getting-started/relationships-and-advanced-filtering.adoc b/docs/modules/ROOT/pages/getting-started/relationships-and-advanced-filtering.adoc index 8d1c27dd..14bdd63b 100644 --- a/docs/modules/ROOT/pages/getting-started/relationships-and-advanced-filtering.adoc +++ b/docs/modules/ROOT/pages/getting-started/relationships-and-advanced-filtering.adoc @@ -1,9 +1,9 @@ [[relationships-advanced-filtering]] -:description: This tutorial shows how to add relationships and more advanced filters, as well as alias the results of the projection +:description: This page shows you how to add relationships and more advanced filters, and how to alias the results of a projection. = Relationships and advanced filtering -This tutorial shows how to add relationships and more advanced filters, as well as alias the results of the projection. -It extends the Cypher query example from the xref:getting-started/filters-and-projections.adoc[Filters and projections] tutorial and the link:https://neo4j.com/docs/getting-started/appendix/example-data/#built-in-examples[Movies Dataset]. +This page shows you how to add relationships and more advanced filters, and how to alias the results of a projection +It extends the Cypher query example from xref:getting-started/filters-and-projections.adoc[Filters and projections] based link:https://neo4j.com/docs/getting-started/appendix/example-data/#built-in-examples[movies data set]. [source, cypher] ---- @@ -16,7 +16,7 @@ This query matches a `Movie` along with its actors. It should only return movies with the actor `Keanu Reeves`, excluding any movie with a title containing `Matrix` released after 1999. It also adds the property `roles` from the relationship to the projection, aliasing it to `actingRoles`. -Querying it on the Movies Dataset should prompt this result: +Executing it against the movies data set prompts this result: .Result [role="queryresult",options="header",cols="4*("my-procedure") Trying to use `.yield` with anything different to `"columnA"` or `"columnB"` returns as a TypeScript error. ==== + ==== Void procedures -Some procedures cannot be used along with `YIELD` as they do not return any values. +Some procedures cannot be used alongside `YIELD` as they do not return any values. These can be defined with `Cypher.VoidProcedure`: [source, javascript] @@ -229,6 +237,7 @@ const myProcedure = new Cypher.VoidProcedure("my-proc"); This can be used as any other procedure, except that the `.yield` method is not available. + ==== Reusing custom procedures Custom procedures can be reused by wrapping them with a JavaScript function: @@ -256,8 +265,7 @@ CALL my-custom-procedure(var0) YIELD "column" The class `Cypher.Raw` allows embedding a Cypher string within a larger query built with Cypher Builder. It acts as a wildcard that can be used anywhere. - -For instance, this query: +For example: [source, javascript] ---- @@ -268,14 +276,14 @@ const returnClause = new Cypher.Return(customReturn); const { cypher, params } = returnClause.build(); ---- -Returns the following Cypher: +This query returns the following Cypher: [source, cypher] ---- RETURN 10 as myVal ---- -In this case, the `RETURN` clause is being generated by Cypher Builder, but the actual value `10 as myVal` has been injected with `Raw`. +In this case, the `RETURN` clause is generated by Cypher Builder, but the actual value `10 as myVal` has been injected with `Raw`. This string can be anything, including other clauses or invalid Cypher, and can be generated dynamically: [source, javascript] @@ -288,6 +296,7 @@ const returnClause = new Cypher.Return(customReturn); Additionally, `Raw` can also be used in `Cypher.utils.concat` to attach an arbitrary string to any Cypher Builder element. + === Using a callback In more complex scenarios, you may need to access variables created with the Cypher Builder in your custom Cypher string. @@ -299,10 +308,10 @@ It returns the following values: * `string`: Cypher string to be used for this element. * `[string, object]`: a tuple with the first element being the Cypher string, and the second an object with the parameters to be injected in the query. -* `undefined`: if undefined, `Raw` will be translated as an empty string. +* `undefined`: if undefined, `Raw` is translated as an empty string. -In this example, a `MATCH...RETURN` statement is being created with Cypher Builder in the usual way. -However, a custom `Raw` is being injected as part of the `WHERE` subclause: +In this example, Cypher Builder creates a `MATCH...RETURN` statement the usual way. +However, a custom `Raw` is injected as part of the `WHERE` subclause: [source, javascript] ---- @@ -343,7 +352,7 @@ And the following parameters: } ---- -The callback passed into `Raw` is producing the string `this0.prop = $myParam`. +The callback passed into `Raw` produces the string `this0.prop = $myParam`. To achieve this, it uses the utility method `utils.compileCypher` and passes the variable `movie` and the `context` parameter, which then returns the string `this0`. Finally, the custom parameter `$myParam` is returned in the tuple `[cypher, params]`, ensuring that it is available when executing `match.build()`. @@ -355,10 +364,11 @@ Finally, the custom parameter `$myParam` is returned in the tuple `[cypher, para Changing these options may lead to code injection and unsafe Cypher. ==== -Cypher Builder automatically escapes unsafe strings that could lead to code injection. This behavior can be configured using the `unsafeEscapeOptions` parameter in the `.build` method of clauses: +Cypher Builder automatically escapes unsafe strings that could lead to code injection. +This behavior can be configured using the `unsafeEscapeOptions` parameter in the `.build` method of clauses: -- `disableNodeLabelEscaping` (defaults to `false`): If set to `true`, node labels will not be escaped, even if unsafe. -- `disableRelationshipTypeEscaping` (defaults to `false`): If set to `true`, relationship types will not be escaped, even if unsafe. +- `disableNodeLabelEscaping` (defaults to `false`): If set to `true`, node labels are not escaped, even if unsafe. +- `disableRelationshipTypeEscaping` (defaults to `false`): If set to `true`, relationship types are not escaped, even if unsafe. For example: @@ -386,7 +396,7 @@ const queryResult = matchQuery.build({ }); ---- -This query will generate the following (invalid) Cypher: +This query generates the following (invalid) Cypher: [source] @@ -405,7 +415,8 @@ RETURN this0 === Manually escaping labels and types -If automatic escaping is disabled, strings used for labels and relationship types must be escaped manually. This can be done using the following utility functions: +If automatic escaping is disabled, strings used for labels and relationship types must be escaped manually. +This can be done using the following utility functions: * `Cypher.utils.escapeLabel(str)` * `Cypher.utils.escapeType(str)` diff --git a/docs/modules/ROOT/pages/how-to/define-cypher-version.adoc b/docs/modules/ROOT/pages/how-to/define-cypher-version.adoc index cd7a5af3..f42b6069 100644 --- a/docs/modules/ROOT/pages/how-to/define-cypher-version.adoc +++ b/docs/modules/ROOT/pages/how-to/define-cypher-version.adoc @@ -4,7 +4,6 @@ It is possible to define the version of Cypher to use in a query by prepending that query with `CYPHER [version]`. For example: - [source, cypher] ---- CYPHER 5 @@ -12,7 +11,6 @@ MATCH (this0) RETURN this0 ---- - To add the Cypher version at the beggining of the query, pass the parameter `cypherVersion` to `.build`: [source, javascript] @@ -39,4 +37,5 @@ WHERE this0.title = $param0 RETURN this0.title ---- -Note that this setting only prepends the `CYPHER` statement to the query. The query itself is unchanged. +Note that this setting only prepends the `CYPHER` statement to the query. +The query itself is unchanged. diff --git a/docs/modules/ROOT/pages/how-to/filter-by-labels.adoc b/docs/modules/ROOT/pages/how-to/filter-by-labels.adoc index 367becad..45a133ef 100644 --- a/docs/modules/ROOT/pages/how-to/filter-by-labels.adoc +++ b/docs/modules/ROOT/pages/how-to/filter-by-labels.adoc @@ -2,12 +2,15 @@ :description: This page describes how to filter by labels and types. = Filter by labels -Most patterns are composed with labels such as `(m:Movie)` to make simple filtering by labels. xref:../patterns.adoc#_label_expressions[Label expressions] can also be used to perform complex filtering by labels. +Most patterns are composed with labels such as `(m:Movie)` to make filtering by labels easy. +You can also use xref:../patterns.adoc#_label_expressions[Label expressions] to perform complex filtering by labels. == `.hasLabel` -It is possible to check for label existence in `WHERE` filters. To do so, the methods `.hasLabel` and `.hasLabels` from `Node` variables can be used in predicates. For example, to match nodes with either the `Movie` or `Film` labels: +It is possible to check for label existence in `WHERE` filters. +Use the methods `.hasLabel` and `.hasLabels` for `Node` variables. +For example, to match nodes with either the `Movie` or `Film` labels: [source, javascript] ---- @@ -25,7 +28,7 @@ WHERE (this0:Movie OR this0:Film) RETURN this0 ---- -The method `.hasLabels` allow to provide multiple labels that the node must have +The method `.hasLabels` allows you to provide multiple labels that the node must have: [source, javascript] ---- @@ -47,7 +50,7 @@ RETURN this0 == `.hasType` -Like labels, relationship types can be filtered in `WHERE` statements with the method `.hasType` +Like labels, relationship types can be filtered in `WHERE` statements with the method `.hasType`: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/how-to/type-predicate-expressions.adoc b/docs/modules/ROOT/pages/how-to/type-predicate-expressions.adoc index e748c7e3..4d25f17f 100644 --- a/docs/modules/ROOT/pages/how-to/type-predicate-expressions.adoc +++ b/docs/modules/ROOT/pages/how-to/type-predicate-expressions.adoc @@ -4,23 +4,26 @@ This section outlines the process of creating link:https://neo4j.com/docs/cypher-manual/current/values-and-types/type-predicate/[type predicate expressions] within your queries using Cypher Builder. -A type predicate expression serves to validate the type of a variable, literal, property, or another Cypher expression. It follows the syntax below in Cypher: +A type predicate expression serves to validate the type of a variable, literal, property, or another Cypher expression. +It follows the syntax below in Cypher: [source, cypher] ---- IS :: ---- -For example +For example: [source, cypher] ---- movie.title IS :: STRING ---- + == `isType` -Type predicate expressions can be constructed using `Cypher.isType` (distinct from the `.hasType` method in Relationship). The `isType` function takes a xref:variables-and-params/variables.adoc[Cypher variable] and a type specified in `Cypher.TYPE`: +Type predicate expressions can be constructed using `Cypher.isType` (distinct from the `.hasType` method for relationships). +The `isType` function takes a xref:variables-and-params/variables.adoc[Cypher variable] and a type specified in `Cypher.TYPE`: [source, javascript] ---- @@ -47,6 +50,7 @@ WHERE this0.title IS :: STRING RETURN this0 ---- + === Using Union types Union types, for example, `INTEGER | STRING`, can be used by passing an array to `.isType`: @@ -61,6 +65,7 @@ Cypher.isType(new Cypher.Variable(), [Cypher.TYPE.INTEGER, Cypher.TYPE.STRING]); var0 IS :: INTEGER | STRING ---- + === List Types List types, for instance, `LIST`, can be created using `Cypher.TYPES.list()`: @@ -102,9 +107,11 @@ Cypher.isNotType(new Cypher.Variable(), Cypher.TYPE.INTEGER); var0 IS NOT :: INTEGER ---- + == Type predicate expressions for non-nullable types -Type predicate expressions evaluate to `true` in Cypher for `NULL` values unless a `NOT NULL` is appended. In Cypher Builder, this can be achieved using the `.notNull` method: +Type predicate expressions evaluate to `true` in Cypher for `NULL` values unless a `NOT NULL` is appended. +In Cypher Builder, this can be achieved using the `.notNull` method: [source, javascript] ---- @@ -116,7 +123,7 @@ Cypher.isType(new Cypher.Variable(), Cypher.TYPE.INTEGER).notNull(); var0 IS :: INTEGER NOT NULL ---- -Non-nullable types can also be used within a List type: +Non-nullable types can also be used within a list type: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/how-to/update-labels.adoc b/docs/modules/ROOT/pages/how-to/update-labels.adoc index 0c7b86ab..32c30d64 100644 --- a/docs/modules/ROOT/pages/how-to/update-labels.adoc +++ b/docs/modules/ROOT/pages/how-to/update-labels.adoc @@ -4,6 +4,7 @@ To add or remove labels to a node, use `.set` and `.remove` with the node method `.label`. + == Add labels [source, javascript] @@ -12,7 +13,6 @@ const movie = new Cypher.Node(); const clause = new Cypher.Match(new Cypher.Pattern(movie)).set(movie.label("NewLabel"), movie.label("Another label")); ---- - [source, cypher] ---- MATCH (this0) @@ -21,30 +21,28 @@ SET this0:`Another Label` ---- - == Remove labels - [source, javascript] ---- const movie = new Cypher.Node(); const clause = new Cypher.Match(new Cypher.Pattern(movie)).remove(movie.label("NewLabel")); ---- - [source, cypher] ---- MATCH (this0) REMOVE this0:NewLabel ---- + == Set dynamic labels -In some cases, the labels to add or remove need to be defined dynamically, such as a result of an expression. To achieve this, the `.label` methods accepts an expression instead of a string. +In some cases, the labels to add or remove must be defined dynamically, such as the result of an expression. +To achieve this, the `.label` methods accepts an expression instead of a string. For example, to copy all the labels from one node to another, the function `labels()` can be used as the expression to `.label`: - [source, javascript] ---- new Cypher.Match(new Cypher.Pattern(movie)).set(movie.label(Cypher.labels(anotherNode))); diff --git a/docs/modules/ROOT/pages/how-to/use-change-data-capture.adoc b/docs/modules/ROOT/pages/how-to/use-change-data-capture.adoc index aaf0bce4..ff1c5996 100644 --- a/docs/modules/ROOT/pages/how-to/use-change-data-capture.adoc +++ b/docs/modules/ROOT/pages/how-to/use-change-data-capture.adoc @@ -10,14 +10,18 @@ link:https://neo4j.com/docs/cdc/current/[Change Data Capture] (CDC) queries can [WARNING] ==== -Previous to Neo4j version 5.17, the namespace for cdc procedures is `cdc.x` instead of `db.cdc.x`, this namespace is available in Cypher Builder through the deprecated functions `Cypher.cdc.x` +Previous to Neo4j 5.17, the namespace for cdc procedures is `cdc.x` instead of `db.cdc.x`, this namespace is available in Cypher Builder through the deprecated functions `Cypher.cdc.x`. ==== + == Examples + === Acquiring the current change identifier -In order to query changes, you need to acquire a change identifier. This can be done with `cdc.current()` or `cdc.earliest()`. To acquire the latest change identifier, follow these instructions: +In order to query changes, you must acquire a change identifier. +This can be done with `cdc.current()` or `cdc.earliest()`. +To acquire the latest change identifier, follow these instructions: [source, javascript] ---- @@ -25,7 +29,6 @@ const query = Cypher.db.cdc.current().yield("id"); const { cypher } = query.build(); ---- - [source, cypher] ---- CALL db.cdc.current() YIELD id @@ -50,7 +53,7 @@ CALL db.cdc.query("cdc-id", []) === Using query selectors -To use link:https://neo4j.com/docs/cdc/current/selectors/[CDC selectors] you'll need to define a `Map` with the properties of the selector schema for each selector: +To use link:https://neo4j.com/docs/cdc/current/selectors/[CDC selectors] you must define a `Map` with the properties of the selector schema for each selector: [source, javascript] ---- diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 81331ec9..bfa32f8a 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -31,5 +31,5 @@ RETURN this0.title [TIP] ==== -If you are using Java, check link:https://neo4j.github.io/cypher-dsl[Neo4j Cypher-DSL]. +If you are using Java, you can use link:https://neo4j.github.io/cypher-dsl[Neo4j Cypher-DSL] instead. ==== diff --git a/docs/modules/ROOT/pages/migration-guide-2.adoc b/docs/modules/ROOT/pages/migration-guide-2.adoc index eccec4dc..a0267fb4 100644 --- a/docs/modules/ROOT/pages/migration-guide-2.adoc +++ b/docs/modules/ROOT/pages/migration-guide-2.adoc @@ -1,10 +1,11 @@ [[migration]] -:description: This page describes how to migrate to version 2.x +:description: This page describes how to migrate to version 2.x of the Cypher Builder. = Migration to Cypher Builder 2 -This guide describes the changes required to migrate from Cypher Builder 1.x to 2.0, as well as some breaking changes that may affect projects using Cypher Builder. +This page describes necessary steps and things to consider when migrating from Cypher Builder 1.x to 2.0, as well as breaking changes that may affect projects using Cypher Builder. + +The full, up to date changelog can be found in the link:https://github.com/neo4j/cypher-builder/blob/main/CHANGELOG.md[Cypher Builder changelog]. -The full, up to date changelog can be found link:https://github.com/neo4j/cypher-builder/blob/main/CHANGELOG.md[here]. == Patterns @@ -13,7 +14,8 @@ xref:patterns.adoc[Patterns] have been reworked in version 1.x, and the old beha === Node shorthand removed from clauses -Clauses using Patterns no longer accept a `Cypher.Node` as a shorthand. An explicit pattern must be provided: +Clauses using patterns no longer accept a `Cypher.Node` as a shorthand. +An explicit pattern must be provided: Before: @@ -46,21 +48,21 @@ This also affects pattern comprehensions `Cypher.PatternComprehension`. === Patterns no longer create a variable by default -Creating a Pattern without options will no longer add variables to the generated Cypher: +Creating a pattern without options no longer adds variables to the generated Cypher: [source, javascript] ---- const pattern = new Cypher.Pattern() ---- -Before +Before: [source, cypher] ---- (this0) ---- -Now +Now: [source, cypher] ---- @@ -78,7 +80,9 @@ const pattern = new Cypher.Pattern(movieNode) ==== `.getVariables` -The method `.getVariables` has been removed from Patterns, as Patterns no longer create variables, `getVariables` is no longer useful. +The method `.getVariables` has been removed from patterns. +Since patterns no longer create variables, `getVariables` is no longer useful. + === Patterns configuration @@ -94,7 +98,8 @@ The following methods to configure the resulting pattern have been removed from Instead, Patterns are now configured through objects in the constructor, as well as the `related` and `to` methods: -Before +Before: + [source, javascript] ---- const a = new Cypher.Node({ @@ -117,7 +122,7 @@ new Cypher.Pattern(a) .to(b) ---- -Now +Now: [source, javascript] ---- @@ -142,7 +147,8 @@ The generated Cypher: (:Person:Actor { name: $param0, surname: $param1 })-[this1:ACTED_IN]->(this2) ---- -Note that labels and types are now defined in the Pattern, not in the `Node` and `Relationship` classes. +Note that labels and types are now defined in the pattern, not in the `Node` and `Relationship` classes. + === Assign to path variable @@ -168,7 +174,7 @@ const pathVariable = new Cypher.Cypher.PathVariable() new Cypher.Match(pattern.assignTo(pathVariable)).return(pathVariable); ``` -Generates the Cypher: +The generated Cypher: ```cypher MATCH p = ()-[]-() @@ -176,11 +182,13 @@ RETURN p ``` -== Node and Relationship variables +== Node and relationship variables -`Cypher.Node` and `Cypher.Relationship` no longer hold any data about labels, or types. Making them more similar to `Cypher.Variable`. To add labels or types, these need to be passed to the `Cypher.Pattern` instead of relying on `Cypher.Node` and `Cypher.Relationship`. +`Cypher.Node` and `Cypher.Relationship` no longer hold any data about labels, or types, making them more similar to `Cypher.Variable`. +To add labels or types, they must be passed to the `Cypher.Pattern` instead of relying on `Cypher.Node` and `Cypher.Relationship`. + +Before: -Before [source, javascript] ---- const a = new Cypher.Node({ @@ -196,7 +204,7 @@ new Cypher.Pattern(a) .to(b) ---- -Now +Now: [source, javascript] ---- @@ -210,13 +218,16 @@ new Cypher.Pattern(a, { labels: ["Person", "Actor"] }) .to(b) ---- + === Path variables -The variables used for paths `Cypher.Path` and `Cypher.NamedPath` have been removed in favor of the more accurate names: `Cypher.PathVariable` and `Cypher.NamedPathVariable` +The variables used for paths `Cypher.Path` and `Cypher.NamedPath` have been removed in favor of the more accurate names: `Cypher.PathVariable` and `Cypher.NamedPathVariable`: + == Renamed features -The following features where deprecated in favor of a different name with the same functionality. The deprecated features have been removed in version 2.0: +The following features where deprecated in favor of a different name with the same functionality. +The deprecated features have been removed in version 2.0: * `Cypher.concat` in favor of `Cypher.utils.concat` * `pointDistance` in favor of `point.distance` @@ -228,11 +239,13 @@ The following features where deprecated in favor of a different name with the sa ** `db.cdc.query` * `rTrim` and `lTrim` in favor of `rtrim` and `ltrim` respectively + == `.build()` The options for `.build()` are now passed as a single object rather than parameters: Before: + [source, javascript] ---- myClause.build( @@ -244,7 +257,6 @@ myClause.build( ); ---- - Now: [source, javascript] ---- @@ -259,11 +271,14 @@ myClause.build({ All parameters are optional, and `build` can still be called without parameters. + === Remove support for fine-grained prefix -The first parameter "prefix" for the `.build` method in 1.x supports passing an object with the parameters `params` and `variables` for fine grained control of what prefix to use in different kind of variables. This has been removed in 2.x, supporting only a `string` as global prefix: +The first parameter "prefix" for the `.build` method in 1.x supports passing an object with the parameters `params` and `variables` for fine-grained control of what prefix to use in different kinds of variables. +This has been removed in 2.x, supporting only a `string` as global prefix: No longer supported: + [source, javascript] ---- myClause.build({ @@ -272,9 +287,10 @@ myClause.build({ }); ---- -Instead, a single string can be used as prefix for both, variables and params: +Instead, a single string can be used as prefix for both variables and parameters: Now: + [source, javascript] ---- myClause.build({ @@ -282,11 +298,15 @@ myClause.build({ }); ---- + == `With` -The method `.with` no longer adds new columns into the existing clause. It will always create a new `WITH` statement instead. The method `.addColumns` should be used instead to add extra columns. +The method `.with` no longer adds new columns to the existing clause. +It always creates a new `WITH` statement instead. +Use the method `.addColumns` to add extra columns. + +Before: -Before [source, javascript] ---- const withQuery = new Cypher.With(node); @@ -294,7 +314,8 @@ withQuery.with(node); withQuery.with("*"); ---- -Now +Now: + [source, javascript] ---- const withQuery = new Cypher.With(node); @@ -302,7 +323,6 @@ withQuery.with(node) withQuery.addColumns("*"); ---- - The generated Cypher: [source, cypher] @@ -311,16 +331,20 @@ WITH this0 WITH *, this0 ---- + == `RawCypher` `Cypher.RawCypher` has been removed in favor of `Cypher.Raw`. + === Update callback parameter -`Cypher.Raw` no longer exposes a `Cypher.Environment` variable. Instead, it provides an instance of `CypherRawContext` with a `compile` method to compile nested elements in custom cypher. +`Cypher.Raw` no longer exposes a `Cypher.Environment` variable. +Instead, it provides an instance of `CypherRawContext` with a `compile` method to compile nested elements in custom cypher. Before: + [source, typescript] ---- const releasedParam = new Cypher.Param(1999); @@ -334,6 +358,7 @@ const rawCypher = new Cypher.Raw((env: Cypher.Environment) => { ---- Now: + [source, typescript] ---- const releasedParam = new Cypher.Param(1999); @@ -348,41 +373,50 @@ const rawCypher = new Cypher.Raw((ctx: Cypher.RawCypherContext) => { Note that the code itself has not changed, and just the type passed to `Cypher.Raw` callback has been changed from `Cypher.Environment` to `Cypher.RawCypherContext`. -=== Remove `utils.compileCypher` + +=== Removed the `utils.compileCypher` The utility function `compileCypher` has been removed, in favor of using `CypherRawContext.compile`, which offers the same functionality. + == `PatternComprehension` -`PatternComprehension` no longer accept a node as an argument in the constructor, a Pattern must be passed instead: +`PatternComprehension` no longer accept a node as an argument in the constructor. +Instead, use a pattern: + +Before: -Before [source, javascript] ---- const node = new Cypher.Node(); const comprehension = new Cypher.PatternComprehension(node); ---- -Now +Now: + [source, javascript] ---- const node = new Cypher.Node(); const comprehension = new Cypher.PatternComprehension(new Cypher.Pattern(node)); ---- + === `.map` -`PatternComprehension` no longer accepts a second argument for the Map expression. The method `.map` must be used instead: +`PatternComprehension` no longer accepts a second argument for the map expression. +Instead, use the `.map` method: + +Before: -Before [source, javascript] ---- const andExpr = Cypher.eq(node.property("released"), new Cypher.Param(1999)); - +https://github.com/neo4j/cypher-builder/blob/main/CHANGELOG.md const comprehension = new Cypher.PatternComprehension(new Cypher.Pattern(node), andExpr) ---- -Now +Now: + [source, javascript] ---- const andExpr = Cypher.eq(node.property("released"), new Cypher.Param(1999)); @@ -391,9 +425,9 @@ const comprehension = new Cypher.PatternComprehension(new Cypher.Pattern(node)). ---- -== Other Breaking changes +== Other breaking changes -These are breaking changes that do not require changes, but may affect the behaviour of projects updating to Cypher Builder 2.0. +These are breaking changes that may affect the behavior of projects when updating to Cypher Builder 2.0. === Fix TypeScript typings for boolean operators @@ -404,7 +438,7 @@ The typings for the following boolean operators have been fixed to better reflec * `Cypher.or` * `Cypher.xor` -The following: +The following now returns the correct type `Cypher.Predicate | undefined`.: [source, typescript] ---- @@ -412,7 +446,7 @@ const predicates: Cypher.Predicate[] = []; const andPredicate = Cypher.and(...predicates); ---- -Will now return the correct type `Cypher.Predicate | undefined`. This change means that additional checks may be needed when using boolean operators: +This change means that additional checks may be needed when using boolean operators: [source, typescript] ---- @@ -420,28 +454,28 @@ const predicates = [Cypher.true, Cypher.false]; const andPredicate = Cypher.and(...predicates); // type Cypher.Predicate | undefined ---- -Passing parameters without spread will still return a defined type. +Passing parameters without spread still returns a defined type. === Literals escaping -`Cypher.Literal` will now escape strings if these contain invalid characters. This is to avoid code injection. - +`Cypher.Literal` now escapes strings if they contain invalid characters. +This avoids code injection. [source, javascript] ---- new Cypher.Literal(`Hello "World"`); ---- -Would generate the following Cypher: - Before: + [source, cypher] ---- "Hello "World"" ---- Now: + [source, cypher] ---- "Hello \"World\""