Filter Expressions

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 single dot ".". Despite the modeled properties, there are always two artificial properties available:

• _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 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

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.

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

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.

Overview of allowed operators, property types and values

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

Example usage within Repository

// Access the repository of the specific root entity and choose 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}"`
);

Example usage with the Filter Factory

The Filter factory provides support to construct the filter string to be used while querying the Datastore Api.

There are 4 methods available in the filter factory:

The filter factory provides type safe guidance to build and use the filter strings to make query to the database instance.

This example shows usage of the filter factory methods:

const condition1 = this.factory.filter.namespace.entity.textProperty1.comparison('=in=', ['text1', 'text2']);
const condition2 = this.factory.filter.namespace.entity.booleanProperty1.comparison('==', true);

const filterExpression = this.factory.filter._and(condition1, condition2);      
// can use OR using similar syntax this.factory.filter._or(cond1, cond2)
// filterExpression string: "((textProperty1=in=['text1', 'text2']) AND (booleanProperty1==true))"

const filteredInstance = await this.factory.namespace.RootEntity1.find({ includeSubEntities: true }, filterExpression);

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"))`
    );

Filter Factory Examples

Basic Implementation

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

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');

onst 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

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