linkBind Parameters

The BindParam class provides utilities for easily creating bind parameter objects to be used in queries. Using the appropriate methods, if a key already exists, a different one will be generated. There is no need to manually ensure uniqueness of keys.

linkCreating a BindParam instance

First of all, a BindParam instance must be created.

1link/* --> creating an empty BindParam instance */

2linkconst bindParam = new BindParam();

3link

4link/* --> creating a BindParam instance with data (using an object) */

5linkconst bindParam = new BindParam({

6link    x: 5,

7link    y: 'bar'

8link});

9link

10link/* --> creating a BindParam instance with data (using many objects) */

11linkconst bindParam = new BindParam(

12link    {

13link        x: 5,

14link        y: 'bar'

15link    },

16link    {

17link        z: true

18link    }

19link);

20link

21link/* --> the following will throw an error since the keys are not unique. To add non-unique keys, the `getUniqueName` method must be used */

22link/* --> this is to prevent unexpected behavior in a case like the following: "n1.x = $x, n2.x = $x", where a different value is intended to be used each time */

23linkconst bindParam = new BindParam(

24link    {

25link        x: 5

26link    },

27link    {

28link        x: true // -> error! key 'x' is not unique

29link    }

30link);

linkGetting the values of a BindParam

Use the get method to retrieve all bind parameter values.

1linkconst bindParam = new BindParam({

2link    x: 5,

3link    y: 'bar'

4link});

5link

6linkconsole.log(bindParam.get()); // { x: 5, y: 'bar' }

linkAdding a value to an existing BindParam instance

Use the add method to add new values. All keys must be unique. To add values with duplicate key names, use the getUniqueName method.

1link/* --> */

2linkconst bindParam = new BindParam({

3link    x: 5

4link});

5link

6link/* --> adding a single object */

7linkbindParam.add({

8link    y: 'bar'

9link});

10link

11linkconsole.log(bindParam.get()); // { x: 5, y: 'bar' }

12link

13link/* --> adding multiple objects */

14linkbindParam.add(

15link    {

16link        z: true,

17link        a: 1

18link    },

19link    {

20link        b: 2

21link    }

22link);

23link

24linkconsole.log(bindParam.get()); // { x: 5, y: 'bar', z: true, a: 1, b: 2 }

25link

26link/* --> adding an existing key will result in an error */

27link

28linkbindParam.add({ x: 4 }); // -> error! key 'x' is not unique

linkGetting a unique name to use

The getUniqueName can be used to generate a key which doesn't already exist in the bind param. This key can be used in your queries.

1linkconst bindParam = new BindParam({

2link    x: 5,

3link    y: 'bar'

4link});

5link/* --> let's suppose you use those keys in a query. The bindParam can be used as a parameter when we run it */

6linklet statement = `MATCH (n) WHERE n.x = $x AND n.y = $y`;

7link

8link/* --> get a unique key based on the 'x' prefix */

9linkconst uniqueName = bindParam.getUniqueName('x');

10linkconsole.log(uniqueName); // x__aaaa

11link

12link/* --> the value for this unique name should be added to the bindParam */

13linkbindParam.add({

14link    [uniqueName]: 4

15link});

16linkconsole.log(bindParam.get()); // { x: 5, y: 'bar', x__aaaa: 4 }

17link

18link/* --> this uniqueName can be used in queries */

19linkstatement += `WITH n MATCH (o) WHERE o.x = $${uniqueName} RETURN n, o`;

20link

21link/* --> we can now run this query */

22linkawait queryRunner.run(statement, bindParam.get());

The getUniqueNameAndAdd can be used to perform the getUniqueName and add methods at once.

1linkconst bindParam = new BindParam({

2link    x: 5,

3link    y: 'bar'

4link});

5link/* --> get a unique key based on the 'x' prefix and add the given value to the bindParam */

6linkconst uniqueName = bindParam.getUniqueNameAndAdd('x', 4);

7link

8linkconsole.log(uniqueName); // x__aaaa

9linkconsole.log(bindParam.get()); // { x: 5, y: 'bar', x__aaaa: 4 }

The getUniqueNameAndAddWithLiteral method can be used for a similar functionality with getUniqueNameAndAdd, but if the given value is an instance of Literal, it returns it as is.

linkCloning a BindParam

A BindParam instance can be cloned, so a new one is returned with the same parameters.

1linkconst oldBindParam = new BindParam({

2link    x: 5,

3link    y: 'bar'

4link});

5linkoldBindParam.add({ z: true });

6link

7linkconsole.log(oldBindParam.get()); // { x: 5, y: 'bar', z: true }

8link

9linkconst newBindParam = oldBindParam.clone();

10linknewBindParam.add({ a: 1 });

11linkoldBindParam.add({ b: 2 });

12link

13linkconsole.log(newBindParam.get()); // { x: 5, y: 'bar', z: true, a: 1 }

14linkconsole.log(oldBindParam.get()); // { x: 5, y: 'bar', z: true, b: 2 }

linkAcquire a BindParam instance

The acquire static can be used to ensure that a BindParam instance is at hand. If one is passed, it will be returned as is. Else, a new one will be created.

1linkconst bindParamFirst = BindParam.acquire(null);

2linkconsole.log(bindParamFirst instanceof BindParam); // true

3link

4linkconst bindParamSecond = BindParam.acquire(bindParamFirst);

5linkconsole.log(bindParamFirst === bindParamSecond); // true

linkRemoving parameters

The remove method can be used to remove keys from the BindParam.

1linkconst bindParam = new BindParam({

2link    x: 5,

3link    y: 'bar'

4link});

5link

6linkconst uniqueName = bindParam.getUniqueNameAndAdd('x', 4);

7link

8linkconsole.log(uniqueName); // x__aaaa

9linkconsole.log(bindParam.get()); // { x: 5, y: 'bar', x__aaaa: 4 }

10link

11linkbindParam.remove([uniqueName, 'y']);

12linkconsole.log(bindParam.get()); // { x: 5 }