linkBind Parameters

The BindPara class provides utilities of easily creating a bind parameters object to be used in a query. Using the appropriate methods, if a key already exists in the parameter, a different one will be used. So, there is no need of manually ensuring 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

The get method can be used

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

The add method can be used, however the added keys must be unique. To add non-unique keys, the getUniqueName method must be used.

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 }