linkWhere Parameters

An instance of the Where class can be used to easily create a statement and a bind parameter to be used in a query.

linkCreating a Where instance and getting its values

Creating a Where instance with values for the identifier n

1linkconst where = new Where({

2link    /* --> the node identifier is the key */

3link    n: {

4link        /* --> the per-identifier where values are used */

5link        x: 5,

6link        y: 'bar'

7link    }

8link});

9link

10link/* --> a statement can be generated to be used in the query */

11linkconsole.log(where.getStatement('text')); // "n.x = $x AND n.y = $y"

12link/* --> the "bindParam" property has a BindParam instance whose values can be used in the query */

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

Creating a Where instance with values for the identifiers n and o

1linkconst where = new Where({

2link    n: {

3link        x: 5,

4link        y: 'bar'

5link    },

6link    o: {

7link        z: true,

8link    }

9link});

10link

11linkconsole.log(where.getStatement('text')); // "n.x = $x AND n.y = $y AND o.z = $z"

12linkconsole.log(where.bindParam.get()); // { x: 5, y: 'bar', z: true }

Since Where uses a BindParam, non-unique keys can be used which will be automatically associated with a unique key

1linkconst where = new Where({

2link    n: {

3link        x: 5,

4link        y: 'bar'

5link    },

6link    o: {

7link        /* --> since it's for a different identifier, we can use any key we want, even if it's used in another identifier */

8link        x: true,

9link    }

10link});

11link

12linkconsole.log(where.getStatement('text')); // "n.x = $x AND n.y = $y AND o.x = $x__aaaa"

13linkconsole.log(where.bindParam.get()); // { x: 5, y: 'bar', x_aaaa: true }

An existing BindParam instance can be used, to ensure unique keys. The same instance will be used in the Where instance, so it will be mutated.

1linkconst existingBindParam = new BindParam({

2link    x: 4,

3link});

4link

5linkconst where = new Where(

6link    {

7link        n: {

8link            /* --> the same key as in the bind param can be used */

9link            x: 5,

10link            y: 'bar'

11link        }

12link    },

13link    existingBindParam

14link);

15link

16link/* --> the "x" key already exists in the bind param, so a new one is used */

17linkconsole.log(where.getStatement('text')); // "n.x = $x__aaaa AND n.y = $y"

18linkconsole.log(where.bindParam.get()); // { x: 4, x_aaaa: 5, y: 'bar' }

19linkconsole.log(where.bindParam === existingBindParam); // true

An existing Where instance can be used. In this case, the parameters of it will be merged with the one that's being created. The existing Where instance won't be mutated at all.

1linkconst existingWhere = new Where(

2link    {

3link        n: {

4link            x: 4

5link        },

6link        o: {

7link            z: true

8link        }

9link    }

10link);

11link

12linkconsole.log(existingWhere.getStatement('text')); // "n.x = $x AND o.z = $z"

13linkconsole.log(existingWhere.bindParam.get()); // { x: 4, z: true }

14link

15linkconst newWhere = new Where(

16link    {

17link        n: {

18link            y: 'bar'

19link        },

20link        m: {

21link            z: 'foo'

22link        }

23link    },

24link    existingWhere

25link);

26link

27linkconsole.log(newWhere.getStatement('text')); // "n.x = $x AND n.y = $y AND o.z = $z AND m.z = $z__aaaa"

28linkconsole.log(newWhere.bindParam.get()); // { x: 4, y: 'bar', z: true, z__aaaa: 'foo' }

linkAdding parameters to an existing Where instance

Similarilly to creating a new Where instance, parameters can be added to an existing instance.

1linkconst where = new Where({

2link    n: {

3link        x: 5,

4link        y: 'bar'

5link    }

6link});

7link

8linkwhere.addParams({

9link    n: {

10link        z: true

11link    },

12link    o: {

13link        x: 4

14link    }

15link});

16link

17linkconsole.log(where.getStatement('text')); // "n.x = $x AND n.y = $y AND n.z = $z AND o.x = $x__aaaa"

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

linkGetting the statement of a Where instance

A Where instance can easily be used in a query using its statement and bindParam properties

linkText form

This is how the statement can be used in a "text" form

1linkconst where = new Where({

2link    n: {

3link        x: 5,

4link        y: 'bar'

5link    },

6link    o: {

7link        z: true,

8link    }

9link});

10link

11linkconst textStatement = where.getStatement('text'); // n.x = $x AND n.y = $y AND o.z = $z

12linkconst bindParamProperties = where.bindParam.get(); // { x: 5, y: 'bar', z: true }

13link

14linkawait queryRunner.run(

15link    `MATCH (n), (o) WHERE ${textStatement} RETURN n, o`,

16link    bindParamProperties

17link);

linkObject form

This is how the statement can be used in an "object" form

1linkconst where = new Where({

2link    n: {

3link        x: 5,

4link        y: 'bar'

5link    },

6link});

7link

8linkconst objectStatement = where.getStatement('object'); // { x: $x, y: $y }

9linkconst bindParamProperties = where.bindParam.get(); // { x: 5, y: 'bar' }

10link

11linkawait queryRunner.run(

12link    `MATCH (n ${objectStatement}) RETURN n`,

13link    bindParamProperties

14link);

This ignores the identifier, and is only available for the "equals" operator. So, it's recommended that it's used with only 1 identifier.

linkWhere operators

While some of the operators can be used with plain objects, some others need to use the exported Op variable. It contains symbols for the operators.

linkEquals

A direct object value corresponds to equality.

1linkconst where = new Where({

2link    n: {

3link        x: 5

4link    },

5link});

6link

7linkconsole.log(where.getStatement('text')); // n.x = $x

8linkconsole.log(where.getStatement('object')); // { x: $x }

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

Alternatively, the operator "eq" can be used.

1linkconst where = new Where({

2link    n: {

3link        x: {

4link            [Op.eq]: 5,

5link        }

6link    },

7link});

8link

9linkconsole.log(where.getStatement('text')); // n.x = $x

10linkconsole.log(where.getStatement('object')); // { x: $x }

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

linkAnd

The values of the parameters object are separated by an "and" operator

1linkconst where = new Where({

2link    n: {

3link        x: 5,

4link        y: 'bar'

5link    },

6link});

7link

8linkconsole.log(where.getStatement('text')); // n.x = $x AND n.y = $y

9linkconsole.log(where.getStatement('object')); // { x: $x, y: $y }

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

linkIn

1linkconst where = new Where({

2link    n: {

3link        x: { 

4link            [Op.in]: [1, 2, 3],

5link        },

6link        y: 2

7link    },

8link    o: {

9link        z: {

10link            [Op.in]: [4, 5, 6],

11link        }

12link    }

13link});

14link

15linkconsole.log(where.getStatement('text')); // n.x IN $x AND n.y = $y AND o.z IN $z

16link// "object" statement not available

17linkconsole.log(where.bindParam.get()); // { x: [1, 2, 3], y: 2, z: [4, 5, 6] }

In case the given param needs to be IN the properties, the _in operator can be used:

1linkconst where = new Where({

2link    n: {

3link        x: { 

4link            [Op._in]: 1,

5link        },

6link        y: 2

7link    },

8link    o: {

9link        z: {

10link            [Op._in]: 2,

11link        }

12link    }

13link});

14link

15linkconsole.log(where.getStatement('text')); // $x IN n.x AND n.y = $y AND $z IN o.z

16link// "object" statement not available

17linkconsole.log(where.bindParam.get()); // { x: 1, y: 2, z: 2 }

linkComparison

The following operators are available:

linkContains

1linkconst where = new Where({

2link    n: {

3link        x: { 

4link            [Op.contains]: 'xyz',

5link        },

6link    },

7link});

8link

9linkconsole.log(where.getStatement('text')); // n.x CONTAINS $x

10link// "object" statement not available

11linkconsole.log(where.bindParam.get()); // { x: 'xyz' }

linkUsing a literal string

The class Literal can be used to use any given string in a Where condition.

1linkconst where = new Where({

2link    n: {

3link        x: 2,

4link        y: new Literal('n.x')

5link    },

6link    o: {

7link        z: {

8link            [Op.gt]: new Literal('n.y'),

9link        }

10link    }

11link});

12link

13linkconsole.log(where.getStatement('text')); // n.x = $x AND n.y = n.x AND o.z >= n.y

14link// "object" statement not available

15linkconsole.log(where.bindParam.get()); // { x: 2 }

linkAcquire a Where instance

The acquire static can be used to ensure that a Where instance is at hand. If one is passed, it will be returned as is. If an object with where parameters is passed, a new Where instance will be created with them. Else, a new one will be created.

1linkconst whereFirst = Where.acquire(null);

2linkconsole.log(whereFirst instanceof Where); // true

3link

4linkconst whereSecond = Where.acquire(whereFirst);

5linkconsole.log(whereFirst === whereSecond); // true

6link

7link/* --> an object with where parameters can be used */

8linkconst whereWithPlainParams = Where.acquire({

9link    n: {

10link        x: 5

11link    }

12link});

13linkconsole.log(whereWithPlainParams instanceof Where); // true

14link

15link/* --> a BindParam instance can be passed to be used */

16linkconst existingBindParam = new BindParam({ x: 4 });

17linkconst whereWithBindParams = Where.acquire(

18link    {

19link        n: {

20link            x: 5

21link        }

22link    },

23link    existingBindParam

24link);

25link

26linkconsole.log(whereWithBindParams instanceof Where); // true

27linkconsole.log(whereWithBindParams.statement); // "n.x = $x__aaaa"

28linkconsole.log(whereWithBindParams.bindParam.get()); // { x: 4, x__aaaa: 5 }