QueryUtils

namespace QueryUtils

import var { Utils: { QueryUtils } } = require('mythix-orm');

QueryUtils provide utility functions for creating and interacting with queries (QueryEngine).

function generateQueryFromFilter(
    connection: Connection,
    Model: class Model,
    filter: object | Array,
): QueryEngine 📜

Take a "query object" and convert it into Mythix ORM query.

"query objects" are objects with a simple structure and convention to build complex queries.

Fields inside these objects can have operators, which are postfixed to the field name. For example, you could create a filter to find a user by name with the following query object: { "firstName=": "John", "lastName!=": "Bob" } which would find all users with the first name of "John", and any last name except "Bob".

AND and OR conditions are also supported. These work based of the structure of the object itself. If an array is used, then OR is in effect. If an object is used, then AND is in effect. For example, the following query object: [ { firstName: "John", lastName: "Brown" }, { firstName: "Mary", lastName: "Smith" } ] would result in the following SQL query: WHERE ((firstName = 'John' AND lastName = 'Brown') OR (firstName = 'Mary' AND lastName = 'Smith')), finding either user John Brown, or Mary Smith.

IN and NOT IN operators are handled automatically when the operator is either = or !=, and the provided value is an array. For example: { firstName: [ 'John', 'Bob', 'Mary' ] } would result in the following SQL query: WHERE firstName IN ('John', 'Bob', 'Mary').

Operators that can be postfixed to field names in the provided filter object are as follows:

Operator	Description
=	Equality operator. If an Array of values is provided, then this will turn into a IN operation in the underlying database.
!=	Inverse (not) equality operator. If an Array of values is provided, then this will turn into a NOT IN operation in the underlying database.
>	Greater than operator.
>=	Greater than or equal to operator.
<	Less than operator.
<=	Less than or equal to operator.
><	Between operator. This operator requires that the provided value be an array with exactly two elements: [ min, max ].
<>	Inverse (not) between operator. This operator requires that the provided value be an array with exactly two elements: [ min, max ].
*	A LIKE wildcard matching operator. The provided value should use % for "zero or more" matches, and _ for "any single character" match.
!*	A NOT LIKE wildcard matching operator. The provided value should use % for "zero or more" matches, and _ for "any single character" match.

Notes:

• This is a simple interface to take an "object" and turn it into a QueryEngine. It doesn't allow multiple models to be defined at once (table-joins), nor other complex operations. If you need more complex operations on your query, you will need to manually create your query... though this method can be used as a starting point.

Arguments:

• connection: Connection

  The connection used to create the QueryEngine.

• Model: class Model

  The model the query is being generated for. The specified fields provided via the filter argument should all be from this model.

• filter: object | Array

  An object or an array of objects to build a query from. Any object will have all its properties ANDed together... whereas any array will have its sub-objects ORed together. i.e. [ { prop1 AND prop2 AND prop3 } OR { prop1 AND prop2 AND prop3 } ].

Return value: QueryEngine

The new query for the Model provided, generated from the provided filter argument.

function mergeFields(
    queryEngine: QueryEngine,
    currentFields: Map<string, object>,
    incomingFields: Array<string | Literal | Model | Field>,
    extraData?: object,
    options?: object,
) 📜

Merge fields for a PROJECT, ORDER, or GROUP_BY QueryEngine operation.

See ModelScope.mergeFields for a more detailed description of what this method does and how it is used.

Arguments:

• queryEngine: QueryEngine

  The QueryEngine instance that the PROJECT, ORDER, or GROUP_BY operation is being applied to.

• currentFields: Map<string, object>

  A map of the current fields that have been applied to the given operation.

• incomingFields: Array<string | Literal | Model | Field>

  A list of all the incoming fields that are supplied to the PROJECT, ORDER, or GROUP_BY operation that is being carried out. This will either merge will currentFields, or replace the currentFields, depending on the content of this argument.

• extraData?: object

  If supplied, then merge these extra properties into each field being added to the list of fields. This is used for example by the ORDER operation to define the direction property for each field added.

• options?: object

  Options for the operation. These are only used when stringifying literals that are being added to the field list. See LiteralBase.toString for more information.

See also: ModelScope.mergeFields

function parseFilterFieldAndOperator(
    fieldName: string,
): { field: string; operator: string; } 📜

Take the provided fieldName, which might include an operator as a postfix, and return the operator and fieldName found. If no operator postfix is present, then the default = operator is returned.

Refer to QueryUtils.generateQueryFromFilter for a better understanding of what this does and why it is needed.

Arguments:

• fieldName: string

  The field name to parse, with an optional operator postfix added.

Return value: { field: string; operator: string; }

Return the parsed field, and the parsed operator. If no operator postfix is on the field, then the default is the = operator.

See also: QueryUtils.generateQueryFromFilter