Filter expressions

Filter expressions are used to find data objects in the database. Their basic principle is to define a comparison. A comparison consists of a path, an operator and a value, where

• path: points to a property of the entity. Traversing of the object tree is supported and is indicated by a single dot "." (e.g. customer.name).
• operator: indicates the operation that is applied to the comparison.
• value: specifies the value to which the comparison is applied. It is highly dependent on the type of the property and operation.

In general, the path to an object is always relative to the Entity which is going to be queried.

Traversing within the object tree can be done via concatenating the names of the properties with a single dot ".". Despite the modelled properties, there are always two artificial properties available:

• _type: The type describes the type of the entity. Its value is given as fully qualified entity name, e.g. core: MyEntity.
• _id: The id describes the internal id of the entity.

For the property type Currency there are also two suffixes available (amount, currency), which allow the specification whether the amount value or the currency code of the property should be compared. The suffix is concatenated with #. The suffixes are constant strings.

For the property type Localized Text, there is also a suffix available. This value is concatenated by using # followed by a string, that points out to the locale value, that should be compared. Example: #en

Operators can be expressed through their symbols as well as through their alias.

For combining different filter criteria, the logical operators AND and OR can be used.

According to the type of the property, that is denoted in the path of a comparison node, there are different operators, that are supported.

To compare a given property's value via some operator, a value must be specified. According to the operator and the type of the property, different types of supplying values are allowed.

• String-Value: A simple string, that may contain arbitrary characters. The value needs to be quoted by double quotes ". For passing the character " to the value, this character needs to be escaped by putting a backslash "" in front of the character. For passing the character \ to the value, this character needs to be written as \. Example: " my simple arbitrary string value, that even contains a " special escaped char."
• String-Array-Value: List of strings in array-notation separated by a comma ",". Example:
• Number-Value: A number that may be prefixed by a signum and also contain a decimal value, which is denoted by a single dot. Also, the scientific representation of numbers via e is allowed. Example: -23.14
• Boolean-Value: A boolean value that can be true or false
• Null-Value: Filtering for properties with no value is indicated by the (not quoted) keyword null
• Location-Radius-Value: The value is a combination of the decimals: latitude, longitude and range. It will be accepted in the following format: . If the range is negative, this means that it is considered as a minimum distance. All three elements must be given. The range is the radius in meter around the given geoPoint in which the result must be
  • Example: // all elements within a range of 5000 m of the point
  • Example: // invalid value since longitude cannot be negative
  • Example: // minimum distance of 300 m of the given point

Please find below a formal (simplified) description of the grammar, that is used for filters.

ROOT: NODE | '(' NODE ')';

NODE: LOGICAL | COMPARISON;
NODE_IN_BRACKET: LOGICAL_IN_BRACKET | COMPARISON_IN_BRACKET;

COMPARISON: COMPARISON_IN_BRACKET | COMPARISON_PLAIN;
COMPARISON_IN_BRACKET: '(' COMPARISON_PLAIN ')';
COMPARISON_PLAIN: PATH OPERATOR VALUE;

LOGICAL: LOGICAL_IN_BRACKET | LOGICAL_PLAIN;
LOGICAL_IN_BRACKET: '(' LOGICAL_PLAIN ')';
LOGICAL_PLAIN: NODE_IN_BRACKET LOGICAL_OPERATOR NODE_IN_BRACKET;

LOGICAL_OPERATOR: 'AND' | 'OR';
OPERATOR: '==' | '=eq=' | '!=' | '=neq=' | '<' | '=lt=' | '<=' | '=lte=' | '>=' | '=gt=' | '>' | '=gte=' | '=*' | '=sc=' | '=in=' | '=nb=' |'=co=' ;

PATH: PROPERTY_NAME_SUFFIX | PROPERTY_NAME_ARTPROP| PROPERTY_NAME_PATH | PROPERTY_ART_PROP;
PROPERTY_NAME_SIMPLE: [a-z]+ (_[A-Za-z0-9])+;
PROPERTY_NAME_PATH: PROPERTY_NAME_SIMPLE ('.' + PROPERTY_NAME_SIMPLE)*;
PROPERTY_NAME_ARTPROP: PROPERTY_NAME_PATH '.' PROPERTY_ART_PROP;
PROPERTY_NAME_SUFFIX: PROPERTY_NAME_PATH '#' PROPERTY_SUFFIX;
PROPERTY_SUFFIX: 'amount' | 'currency' | LOCALE;
PROPERTY_ART_PROP: '_id' | '_type';
LOCALE: [a-z][a-z] ('_' [A-Z][A-Z])?;

VALUE: STRINGVALUE | NUMBERVALUE | BOOLEANVALUE | NULLVALUE | NODEVALUE | GEOVALUE | STRINGARRAYVALUE;

STRINGVALUE: STRING_TOKEN;
STRING_TOKEN: '"' STRING_PRIMITIVE '"';
STRING_PRIMITIVE: CHAR_PRIMITIVE*;
CHAR_PRIMITIVE: CHAR_ESCAPE | CHAR_NORMAL;
CHAR_ESCAPE: '\"' | '\\';
CHAR_NORMAL: [^\"][^\\];

STRINGARRAYVALUE: '[' STRINGARRAYVALUE_ELEMENTS ']'
STRINGARRAYVALUE_ELEMENTS: STRING_TOKEN (',' STRING_TOKEN)*

NUMBERVALUE: NUMBER_PRIMITIVE;
NUMBER_PRIMITIVE: ('-')? [0-9]+ ('.' [0-9]+)? (('e'|'E')['+'|'-'](0-9)+)?

BOOLEANVALUE: 'true' | 'false';
NULLVALUE: 'null';

NODEVALUE: NODE_IN_BRACKET
GEOVALUE: '[' + NUMBER_PRIMITIVE + ',' + NUMBER_PRIMITIVE + ';' + NUMBER_PRIMITIVE +']';

Modelled entities:

cc:CreditCard <<root entity>>
- cardText: text
- cardType: selection element [MASTER, VISA, AMEX]
- owner: external reference to cc:Customer
- transactions: list of local entites of type cc:Transaction

  cc:Transaction <<abstract entity>>
- transactionName: localized text
- transactionTimestamp: timestamp

  cc:DefaultTransaction extends cc:Transaction
- details: text

  cc:GoldTransaction extends cc:Transaction
- rating: selection element

  cc:Customer <<external entity>>
- custName: text
- custNumber: integer

Query for credit cards with cardType MASTER or VISA:

const cards = await this.repo.cc.CreditCard.find(
    { includeSubEntities: true },
        `(cardType=in=["MASTER", "VISA"])`
);

Query for credit cards that belong to owner with custNumber 167671:

const custNumber = 167671;
const cards = await this.repo.cc.CreditCard.find(
    { includeSubEntities: false },
    `owner.custNumber == "${custNumber}"`
);

Query for credit cards, which do not have a cardText or which type is not AMEX:

const cards = await this.repo.cc.CreditCard.find(
    { includeSubEntities: true },
    `((cardText == null) OR (cardType != "AMEX"))`
);

Query for credit cards, which do have a transaction within the last 10 days:

const deadline = new Date();
deadline.setUTCDate(deadline.getUTCDate() - 10);
const cards = await this.repo.cc.CreditCard.find(
    { includeSubEntities: true },
    `(transactions =co= (transactionTimestamp >= ${deadline.toISOString()}))`
);

Query for credit card with the internal id 5b87e25d-035d-40aa-9209-b0c04b004686:

const card = await this.repo.cc.CreditCard.find(
    { includeSubEntities: true },
    `_id == "5b87e25d-035d-40aa-9209-b0c04b004686"`
);

Query for credit cards which have one transaction that contains "abc" (english) as transactionName and where the owner is "Black Cat":

const cards = await this.repo.cc.CreditCard.find(
    { includeSubEntities: true },
    `((owner.custName == "Black Cat") AND (transactions =co= (transactionName#en =tco= "abc")))`
);

Query for credit cards which have a transaction that is subclass of GoldTransaction:

const cards = await this.repo.cc.CreditCard.find(
    { includeSubEntities: true },
    `(transactions =co= (_type =sc= "cc:GoldTransaction"))`
);

Basic Implementation:

const filter1 = this.factory.filter.cc.CreditCard.cardName.comparison('=co=', ['James']);
const filter2 = this.factory.filter.cc.CreditCard.cardActiveFlag.comparison('==', true);

_id &_type as property of Credit Card:

const filter3 = this.factory.filter.cc.CreditCard._id.comparison('==', '18fecac3-9044-4e8b-a767-f427c3901e55');
const filter4 = this.factory.filter.cc.CreditCard._type.comparison('==', 'cc_CreditCard');

For currency property type:

const filter5 = this.factory.filter.cc.CreditCard.currency1.amount.comparison('==', '100');
const filter6 = this.factory.filter.cc.CreditCard.currency1.currency.comparison('==', 'USD');

For localized texts, here description property is of type localized text:

const filter7 = this.factory.filter.cc.CreditCard.description.comparison('ca_FR', '==', 'Canada');

Address as local Entity(single) or reference (single) or external reference (single):

const filter8 = this.factory.filter.cc.CreditCard.address.pincode.comparison('==', '93051');

Transactions as local entity List or reference list or external reference list:

The method contains which represents =co= operator is only available for these type of properties

const filter9 = this.factory.filter.cc.CreditCard.transactions.contains.transactionTimestamp.comparison('>=', new Date());
// resulting filter string: (transactions =co= (transactions.transactionTimestamp >= new Date()))