Unwind create

.changeset/cypher-builder-patch.md

@@ -0,0 +1,6 @@
+---
+"@neo4j/cypher-builder": patch
+---
+
+Included List, date, localtime, localdatetime, time, randomUUID.
+It's possible now to set edge properties from the Merge clause.

.changeset/unwind-create.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/graphql": minor
+---
+
+Added the unwind-create optimization, when possible, to improve performance when a large numbers of nodes are built in single mutation

docs/modules/ROOT/content-nav.adoc

@@ -88,6 +88,7 @@
 ** xref:troubleshooting/index.adoc[]
 *** xref:troubleshooting/faqs.adoc[]
 *** xref:troubleshooting/security.adoc[]
+*** xref:troubleshooting/bulk-create.adoc[]
 ** xref:appendix/index.adoc[]
 *** xref:appendix/preventing-overfetching.adoc[]
 ** xref:deprecations.adoc[Deprecations]

docs/modules/ROOT/pages/troubleshooting/bulk-create.adoc

@@ -0,0 +1,27 @@
+[[bulk-create]]
+= Bulk create
+
+It's possible using the Neo4jGraphQL library to create several nodes and relationships in a single mutation, however,
+it's well known that performance issues are present in performing this task.
+Solutions for this issue are already implemented without any input from the user, see https://github.com/neo4j/graphql/blob/dev/docs/rfcs/rfc-024-unwind-create.md.
+However, there are still several situations where this kind of optimization is not achievable.
+
+== Subscriptions enabled
+
+No optimizations are available if a Subscription plugin it's being used.
+
+== @populated_by
+
+No optimizations are available if a Node affected by the mutation has a field with the directive @populated_by.
+
+== @auth
+
+No optimizations are available if a Node or Field affected by the mutation is secured with the directive @auth.
+
+== Connect/ConnectOrCreate operation
+
+No optimizations are available if the GraphQL input contains the connect/connectOrCreate operation.
+
+== @auth
+
+No optimizations are available if a Node or Field affected by the mutation is secured with the directive @auth.

packages/cypher-builder/src/Cypher.ts

@@ -22,6 +22,7 @@ export { Match, OptionalMatch } from "./clauses/Match";
 export { Create } from "./clauses/Create";
 export { Merge } from "./clauses/Merge";
 export { Call } from "./clauses/Call";
+export { ProcedureCall } from "./clauses/ProcedureCall";
 export { Return } from "./clauses/Return";
 export { RawCypher } from "./clauses/RawCypher";
 export { With } from "./clauses/With";
@@ -49,6 +50,7 @@ export * as apoc from "./expressions/procedures/apoc/apoc";
 // --Lists
 export { ListComprehension } from "./expressions/list/ListComprehension";
 export { PatternComprehension } from "./expressions/list/PatternComprehension";
+export { ListExpr as List } from "./expressions/list/ListExpr";
 
 // --Map
 export { MapExpr as Map } from "./expressions/map/MapExpr";
@@ -79,12 +81,17 @@ export {
     distance,
     pointDistance,
     cypherDatetime as datetime,
+    cypherDate as date,
+    cypherLocalTime as localtime,
+    cypherLocalDatetime as localdatetime,
+    cypherTime as time,
     labels,
     count,
     min,
     max,
     avg,
     sum,
+    randomUUID
 } from "./expressions/functions/CypherFunction";
 export * from "./expressions/functions/ListFunctions";
 export { any, all, exists, single } from "./expressions/functions/PredicateFunctions";
@@ -107,7 +114,9 @@ export type { CompositeClause } from "./clauses/utils/concat";
 
 // utils
 import { escapeLabel } from "./utils/escape-label";
+import { compileCypherIfExists } from "./utils/compile-cypher-if-exists";
 
 export const utils = {
     escapeLabel,
+    compileCypherIfExists
 };

packages/cypher-builder/src/clauses/Merge.ts

@@ -25,11 +25,13 @@ import { Clause } from "./Clause";
 import { OnCreate, OnCreateParam } from "./sub-clauses/OnCreate";
 import { WithReturn } from "./mixins/WithReturn";
 import { mixin } from "./utils/mixin";
+import { WithSet } from "./mixins/WithSet";
+import { compileCypherIfExists } from "../utils/compile-cypher-if-exists";
+import { SetClause } from "./sub-clauses/Set";
 
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface Merge extends WithReturn {}
+export interface Merge extends WithReturn, WithSet {}
 
-@mixin(WithReturn)
+@mixin(WithReturn, WithSet)
 export class Merge<T extends NodeRef | RelationshipRef = any> extends Clause {
     private pattern: Pattern<T>;
     private onCreateClause: OnCreate;
@@ -44,6 +46,7 @@ export class Merge<T extends NodeRef | RelationshipRef = any> extends Clause {
             target: addLabelsOption,
         }).withParams(params);
         this.onCreateClause = new OnCreate(this);
+        this.setSubClause = new SetClause(this);
     }
 
     public onCreate(...onCreateParams: OnCreateParam[]): this {
@@ -54,6 +57,7 @@ export class Merge<T extends NodeRef | RelationshipRef = any> extends Clause {
 
     public getCypher(env: CypherEnvironment): string {
         const mergeStr = `MERGE ${this.pattern.getCypher(env)}`;
+        const setCypher = compileCypherIfExists(this.setSubClause, env, { prefix: "\n" });
         const onCreateStatement = this.onCreateClause.getCypher(env);
         const separator = onCreateStatement ? "\n" : "";
 
@@ -62,6 +66,6 @@ export class Merge<T extends NodeRef | RelationshipRef = any> extends Clause {
             returnCypher = `\n${this.returnStatement.getCypher(env)}`;
         }
 
-        return `${mergeStr}${separator}${onCreateStatement}${returnCypher}`;
+        return `${mergeStr}${separator}${setCypher}${onCreateStatement}${returnCypher}`;
     }
 }

packages/cypher-builder/src/clauses/ProcedureCall.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { CypherEnvironment } from "../Environment";
+import { Clause } from "./Clause";
+import type { Procedure } from "../types";
+
+export class ProcedureCall extends Clause {
+    private procedure: Procedure;
+
+    constructor(procedure: Procedure) {
+        super();
+        this.procedure = procedure;
+    }
+
+    public getCypher(env: CypherEnvironment): string {
+        const procedureCypher = this.procedure.getCypher(env);
+        return `CALL ${procedureCypher}`;
+    }
+}

packages/cypher-builder/src/clauses/Unwind.test.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as Cypher from "../Cypher";
+
+describe("CypherBuilder UNWIND", () => {
+    test("UNWIND Movies", () => {
+        const matrix = new Cypher.Map({ title: new Cypher.Literal("Matrix") });
+        const matrix2 = new Cypher.Map({ title: new Cypher.Literal("Matrix 2") });
+        const moviesList = new Cypher.List([matrix, matrix2]);
+        const unwindQuery = new Cypher.Unwind([moviesList, "batch"]);
+        const queryResult = unwindQuery.build();
+        expect(queryResult.cypher).toMatchInlineSnapshot(
+            `"UNWIND [ { title: \\"Matrix\\" }, { title: \\"Matrix 2\\" } ] AS batch"`
+        );
+        expect(queryResult.params).toMatchInlineSnapshot(`Object {}`);
+    });
+});

packages/cypher-builder/src/expressions/functions/CypherFunction.ts

@@ -68,6 +68,22 @@ export function cypherDatetime(): CypherFunction {
     return new CypherFunction("datetime");
 }
 
+export function cypherDate(): CypherFunction {
+    return new CypherFunction("date");
+}
+
+export function cypherLocalDatetime(): CypherFunction {
+    return new CypherFunction("localdatetime");
+}
+
+export function cypherLocalTime(): CypherFunction {
+    return new CypherFunction("localtime");
+}
+
+export function cypherTime(): CypherFunction {
+    return new CypherFunction("time");
+}
+
 export function count(expr: Expr): CypherFunction {
     return new CypherFunction("count", [expr]);
 }
@@ -87,3 +103,9 @@ export function avg(expr: Expr): CypherFunction {
 export function sum(expr: Expr): CypherFunction {
     return new CypherFunction("sum", [expr]);
 }
+
+export function randomUUID(): CypherFunction {
+    return new CypherFunction("randomUUID");
+}
+
+

packages/cypher-builder/src/expressions/list/ListExpr.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { CypherEnvironment } from "../../Environment";
+import type { CypherCompilable, Expr } from "../../types";
+
+import { serializeList } from "../../utils/serialize-list";
+
+/** Represents a List */
+export class ListExpr implements CypherCompilable {
+    private value: Expr[];
+
+    constructor(value: Expr[]) {
+        this.value = value;
+    }
+
+    public getCypher(env: CypherEnvironment): string {
+        return serializeList(env, this.value);
+    }
+}

packages/cypher-builder/src/expressions/map/MapProjection.test.ts

@@ -31,20 +31,6 @@ describe("Map Projection", () => {
         expect(queryResult.params).toMatchInlineSnapshot(`Object {}`);
     });
 
-    test("Project map with variables and nodes in projection", () => {
-        const var1 = new Cypher.Variable();
-        const var2 = new Cypher.NamedVariable("NamedVar");
-        const node = new Cypher.Node({});
-
-        const mapProjection = new Cypher.MapProjection(new Cypher.Variable(), [var1, var2, node]);
-
-        const queryResult = new TestClause(mapProjection).build();
-
-        expect(queryResult.cypher).toMatchInlineSnapshot(`"var0 { .var1, .NamedVar, .this2 }"`);
-
-        expect(queryResult.params).toMatchInlineSnapshot(`Object {}`);
-    });
-
     test("Project map with extra values only", () => {
         const var1 = new Cypher.Variable();
         const var2 = new Cypher.NamedVariable("NamedVar");
@@ -61,35 +47,31 @@ describe("Map Projection", () => {
         expect(queryResult.params).toMatchInlineSnapshot(`Object {}`);
     });
 
-    test("Project map with variables in projection and extra values", () => {
-        const var1 = new Cypher.Variable();
-        const var2 = new Cypher.NamedVariable("NamedVar");
+    test("Project map with properties in projection and extra values", () => {
         const node = new Cypher.Node({});
 
-        const mapProjection = new Cypher.MapProjection(new Cypher.Variable(), [var1, var2], {
+        const mapProjection = new Cypher.MapProjection(new Cypher.Variable(), [".title", ".name"], {
             namedValue: Cypher.count(node),
         });
         const queryResult = new TestClause(mapProjection).build();
 
-        expect(queryResult.cypher).toMatchInlineSnapshot(`"var0 { .var2, .NamedVar, namedValue: count(this1) }"`);
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"var0 { .title, .name, namedValue: count(this1) }"`);
 
         expect(queryResult.params).toMatchInlineSnapshot(`Object {}`);
     });
 
     test("Map Projection in return", () => {
         const mapVar = new Cypher.Variable();
-        const var1 = new Cypher.Variable();
-        const var2 = new Cypher.NamedVariable("NamedVar");
         const node = new Cypher.Node({});
 
-        const mapProjection = new Cypher.MapProjection(mapVar, [var1, var2], {
+        const mapProjection = new Cypher.MapProjection(mapVar, [".title", ".name"], {
             namedValue: Cypher.count(node),
         });
 
         const queryResult = new Cypher.Return([mapProjection, mapVar]).build();
 
         expect(queryResult.cypher).toMatchInlineSnapshot(
-            `"RETURN var0 { .var2, .NamedVar, namedValue: count(this1) } AS var0"`
+            `"RETURN var0 { .title, .name, namedValue: count(this1) } AS var0"`
         );
 
         expect(queryResult.params).toMatchInlineSnapshot(`Object {}`);

packages/cypher-builder/src/expressions/map/MapProjection.ts

@@ -19,34 +19,34 @@
 
 import type { CypherEnvironment } from "../../Environment";
 import type { CypherCompilable, Expr } from "../../types";
+import type { Variable } from "../../variables/Variable";
 import { serializeMap } from "../../utils/serialize-map";
-import { Variable } from "../../variables/Variable";
 
 /** Represents a Map projection https://neo4j.com/docs/cypher-manual/current/syntax/maps/#cypher-map-projection */
 export class MapProjection implements CypherCompilable {
     private extraValues: Record<string, Expr>;
     private variable: Variable;
-    private projection: Array<Variable>;
+    private projection: string[];
 
-    constructor(variable: Variable, projection: Array<Variable>, extraValues: Record<string, Expr> = {}) {
+    constructor(variable: Variable, projection: string[], extraValues: Record<string, Expr> = {}) {
         this.variable = variable;
         this.projection = projection;
         this.extraValues = extraValues;
     }
 
-    public set(values: Record<string, Expr> | Variable): void {
-        if (values instanceof Variable) {
-            this.projection.push(values);
+    public set(values: Record<string, Expr> | string): void {
+        if (values instanceof String) {
+            this.projection.push(values as string);
         } else {
-            this.extraValues = { ...this.extraValues, ...values };
+            this.extraValues = { ...this.extraValues, ...values as Record<string, Expr> };
         }
     }
 
     public getCypher(env: CypherEnvironment): string {
         const variableStr = this.variable.getCypher(env);
         const extraValuesStr = serializeMap(env, this.extraValues, true);
 
-        const projectionStr = this.projection.map((v) => `.${v.getCypher(env)}`).join(", ");
+        const projectionStr = this.projection.join(", ");
 
         const commaStr = extraValuesStr && projectionStr ? ", " : "";