Filter Expressions

Grammar

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 +']';

The basic principle of a filter expression is to define a comparison. A comparison consists of path operator value, where

• path points to a property of the entity. Traversion of the object tree is supported and is indicated by a ., that forms a property path within the entity.
• operator indicates the operation, that is applied to the comparison
• value specifies the value to which the comparsion is applied. It is highly dependent on the type of the property and operation.

A comparison is grouped by parantheses (path operator value).

Comparisonss can be joined using logical operators.

Operators

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

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

Defining the path

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

Traversion within the object tree can be done via concatenating the names of the properties with a .. Despite the modeled properties, there are always two artifical properties avaiable:

• _type The type describes the type of the entity and it's 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 (#amount) value or the currency code currency of the property should be compared. The suffix is concated with #. The suffixes are constant strings.

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

Supported operators per property type

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

Defining Values

For comparing the value of the given property 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.

Overview of Allowed operators, property types and values

Example usage within Repository

// Access the repository of the specific root entity and choose the find
// Find takes an object argument and a filter argument. The filter argument is represented as a string.

const rootEntityInstance = this.repo.nsacrnm.RootEntityIdentifier.find(FindConfigurationObj, Filter);

//Example
const rootEntityInstance = this.repo.nsacrnm.RootEntityIdentifier.find(
    { includeSubentities: true, 
      limit: “2,20”, 
      sortBy: “customerID,DESC” }, 
     `name == "${name}"`
);

Complex examples

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

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

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

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

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

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

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

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