You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
EXISTS
This function determines whether an instance of a specified entity exists, optionally meeting certain criteria.
Syntax
EXISTS instances [ WHERE ( condition ) ]
- instances - Instances to search.
- condition - boolean expression that represents the criterion the instance has to meet.
Return type
- boolean
Examples
Suppose the following data model.
Person.name | Person.gender | Person.age |
---|---|---|
“Kim” | ? | 23 |
“Rick” | “m” | 35 |
“Bob” | “m” | 42 |
“John” | “m” | 19 |
“Mary” | “f” | 33 |
Expression | Result | Type |
---|---|---|
EXISTS Person | TRUE | Boolean |
EXISTS Person WHERE ( Person.age < 18 ) | FALSE | Boolean |
EXISTS Person WHERE ( Person.gender = "m" AND Person.age > 35 ) | TRUE | Boolean |
EXISTS Person WHERE ( Person.gender = "f" AND Person.age < 25 ) | UNKNOWN | Boolean |
EXISTS Person WHERE ( Person.gender = ? ) | TRUE | Boolean |
Please note that you can use a COLLECT expression as well for collecting instances for which the EACH should hold. E.g., EXISTS (COLLECT Person FROM ALL Person WHERE (Person.gender = "f")) WHERE ( Person.age < 25 ). In case that the list of instances for which the EACH should hold is an EMPTY list, then the EACH expression returns FALSE.
EACH
This function determines whether all instances of a specified entity meet a certain criteria
Syntax
EACH instances WHERE ( condition )
- instances - A collection of instances to search.
- condition - Boolean expression that represents the criterion the instance has to meet.
Return type
- boolean
Examples
Suppose the following data model.
Person.name | Person.gender | Person.age |
---|---|---|
“Kim” | ? | 23 |
“Rick” | “m” | 35 |
“Bob” | “m” | 42 |
“John” | “m” | 19 |
Expression | Result | Type |
---|---|---|
EACH Person WHERE ( Person.age < 18 ) | FALSE | Boolean |
EACH Person WHERE ( Person.age > 18 ) | TRUE | Boolean |
EACH Person WHERE ( Person.age < 20 ) | FALSE | Boolean |
EACH Person WHERE ( Person.gender = "m" OR Person.age > 35 ) | UNKNOWN | Boolean |
EACH Person WHERE ( Person.gender = "m" OR Person.age > 20 ) | TRUE | Boolean |
ALL
Use this function to create a collection of all instances of a specified entity.
Syntax
ALL entity
- entity - Entity of which to collect all its instances.
Return type
- collection of entity instances
Examples
Suppose the following data model. The Parent
and Child
entities both have Person
as base entity.
Parent instance | Child instance |
---|---|
Parent_1 | Child_1 |
Parent_1 | Child_2 |
Parent_1 | Child_3 |
Parent_2 | Child_4 |
Expression | Result | Type |
---|---|---|
ALL Parent | [ Parent_1 , Parent_2 ] | Collection of Parent instances |
ALL Child | [ Child_1 , Child_2 , Child_3 , Child_4 ] | Collection of Child instances |
ALL Person | [ Parent_1 , Parent_2 , Child_1 , Child_2 , Child_3 , Child_4 ] | Collection of Person instances |
COLLECT FROM [WHERE]
Use this function to create a collection of entity or attribute instances (meeting certain criteria).
Syntax
COLLECT entity | attribute FROM collection [ WHERE ( expression ) ]
- entity or attribute - Entity or attribute to collect.
- collection - A collection of entity instances.
- expression - Boolean expression that represents the criterion the instance has to meet.
Return type
- collection of entity instances
- collection of attribute values
A collections contains no duplicates. Intermediary COLLECT
expressions can contain duplicates however, please see the note on collections and duplicates.
Examples
Suppose the following model. Entity Teacher
has a multivalued relation with entity Child
via the relation Teacher.teaches_Children
.
Teacher instance | Child instance | Child.name | Child.hobbies |
---|---|---|---|
Teacher_1 | Child_1 | “Kim” | “Reading”, “Dancing” |
Teacher_1 | Child_2 | “Rick” | “Tennis”, “Dancing” |
Teacher_1 | Child_3 | “Bob” | “Painting”, “Basketball”, “Reading” |
Teacher_2 | Child_1 | “Kim” | “Reading”, “Dancing” |
Teacher_2 | Child_3 | “Bob” | “Painting”, “Basketball”, “Reading” |
Teacher_2 | Child_4 | “Mary” | “Football” |
Expression | Result | Type |
---|---|---|
COLLECT Child.name FROM ALL Child | [ “Kim”, “Rick”, “Bob”, “Mary” ] | String (multivalued) |
COLLECT Child FROM Teacher[Teacher_2].teaches_Children | [ Child_1, Child_3, Child_4 ] | Collection of Child instances |
COLLECT Child.hobbies FROM Teacher[Teacher_1].teaches_Children | [ “Reading”, “Dancing”, “Tennis”, “Painting”, “Basketball” ] | String (multivalued) |
COLLECT Child.name FROM ALL Child | [ “Kim”, “Bob” ] | String (multivalued) |
COLLECT Child.hobbies FROM ALL Child WHERE ( Child.name = "Mary" ) | [ “Football” ] | String (multivalued) |
COLLECT FROM NAMED [WHERE]
Use this version of the COLLECT FROM [WHERE] function for complex nested selections in which it is necessary to use an alias.
Syntax
COLLECT entity | attribute FROM collection NAMED alias [ WHERE ( expression ) ]
- entity or attribute - Entity or attribute to collect. This should contain the alias, e.g. alias.Name.
- collection - A collection of entity instances.
- alias - A name for the collection.
- expression - Boolean expression that represents the criterion the instance has to meet.
Return type
- collection of entity instances
- collection of attribute values
A collections contains no duplicates. Intermediary COLLECT
expressions can contain duplicates however, please see the note on collections and duplicates.
Examples
Suppose the following model with only instances of entity Person
. Person.hasChildren
is a relation from Person to Person.
Person instance | Person.Name | Person.Age | Person.hasChildren |
---|---|---|---|
Person_1 | “Kim” | 16 | |
Person_2 | “Rick” | 38 | Person_3, Person_5 |
Person_3 | “Bob” | 8 | |
Person_4 | “Julia” | 42 | Person_1 |
Person_5 | “Sam” | 3 | |
Person_6 | “Joan” | 34 | Person_3, Person_5 |
To retrieve all the parent names, we use this expression:
COLLECT Parent.name FROM COLLECT Person FROM ALL Person WHERE ( Person.hasChildren != ? ) NAMED Parent
This expression results in “Rick”, “Julia” and “Joan”.
To retrieve all children names, we use this expression:
COLLECT Child FROM ( COLLECT Person.hasChildren FROM ALL Person WHERE ( Person.hasChildren != ? ) ) NAMED Child
This expression results in a collection of three instances of Person
(i.e Person_1
, Person_3
and Person_5
, with names Kim, Bob and Sam).
To retrieve all children younger than 15, we use this expression:
COLLECT Child FROM ( COLLECT Person.hasChildren FROM ALL Person WHERE ( Person.hasChildren != ? ) ) NAMED Child WHERE ( Child.Age < 15 )
This expression results in a collection of two instances of Person
(i.e Person_3
and Person_5
, with names Bob and Sam).
To retrieve the children’s names with a parent older than 40 years:
COLLECT Child.Name FROM ( COLLECT Person.hasChildren FROM ALL Person WHERE ( Person.hasChildren != ? AND Person.Age > 40 ) ) NAMED Child
This expression results in a collection with only the name “Kim”.
You can make it as complex as you like, for example:
COLLECT Child.Name FROM ( COLLECT Parent.hasChildren FROM ( COLLECT Person FROM ALL Person WHERE ( Person.hasChildren != ? ) ) NAMED Parent WHERE ( Parent.Age > 40 ) ) NAMED Child WHERE ( Child.Age < 18 )
This expression results also in a collection with only the name “Kim”.
In some occasions, a local variable could be a good alternative for using an alias. E.g. if you want a collection of all persons except the person that is currently active, this would be simple and transparent:
thisPerson := Person ; COLLECT Person FROM ALL Person WHERE ( Person != thisPerson )
UNPACK
Use this function to extract the value from a single valued collection or list. It is the inverse of the LIST function.
Syntax
UNPACK ( collection/list )
- collection/list - A collection or list of one entity or attribute instance.
Return type
- entity instance
- attribute value of any type
Examples
Suppose the following data model.
Person.name | Person.SequenceNumber |
---|---|
“Bob” | 654 |
“Jane” | 523 |
“Mary” | 667 |
“Rick” | 500 |
“Ron” | 490 |
“Jenny” | 765 |
UNPACK ( COLLECT Person.name FROM ALL Person WHERE ( Person.SequenceNumber = MIN ( COLLECT Person.SequenceNumber FROM ALL Person ) ) )
= “Ron”- In case a second entry "Ron","490" exists, the expression
UNPACK ( COLLECT Person.name FROM ALL Person WHERE ( Person.SequenceNumber = MIN ( COLLECT Person.SequenceNumber FROM ALL Person ) ) )
will fail, because theUNPACK
cannot resolve a list with two elements. To solve this theUNIQUE
function has to be used:UNPACK ( UNIQUE ( COLLECT Person.name FROM ALL Person WHERE ( Person.SequenceNumber = MIN ( COLLECT Person.SequenceNumber FROM ALL Person ) ) ) )
= "Ron". UNPACK ( COLLECT Person.name FROM ALL Person WHERE ( Person.SequenceNumber = MAX ( COLLECT Person.SequenceNumber FROM ALL Person ) ) )
= “Jenny”
LIST
Use this function to create a list based on a value. It is the inverse of the UNPACK function.
Syntax
LIST ( attribute/collection )
- attribute - An attribute of any data type.
- collection/list - A collection or list of values.
Return type
- a multivalued list with entries of any type
Examples
Expression | Result | Type |
---|---|---|
LIST ( "Blueriq" ) | [ "Blueriq" ] | String (multivalued) |
LIST ( 5 ) | [ 5 ] | Integer (multivalued) |
LIST ( ? ) | [] | Any (multivalued) |
Suppose the following data model.
Person.name | Person.SequenceNumber |
---|---|
“Bob” | 654 |
“Jane” | 523 |
“Mary” | 667 |
“Rick” | 500 |
“Ron” | 490 |
“Jenny” | ? |
LIST ( COLLECT Person.name FROM ALL Person ) = [ "Bob" , "Jane" , "Mary" , "Rick" , "Ron" , "Jenny" ]
- In this example the
LIST
function adds no value, as the result of theCOLLECT
is already a list.
- In this example the
LIST ( COLLECT Person.SequenceNumber FROM ALL Person ) = []
- As Jenny has an unknown sequence number, the result of the
COLLECT
expression is?
. TheLIST
function creates an empty list in case the parameter has?
value.
- As Jenny has an unknown sequence number, the result of the
SIZE
This function determines the size of a collection.
Syntax
SIZE ( collection )
- collection - A collection of attribute or entity instances. This can be an expression or a relation attribute for instance.
Return type
- integer
Example
Suppose you have a Parent
and a Child
entity, where Parent
has a multivalued relation with Child
via the relation Parent.has_Children
. With this model the following instances are created:
Parent instance | Child instance | Child.name | Child.hobbies |
---|---|---|---|
Parent_1 | Child_1 | “Kim” | “Reading”, “Dancing” |
Parent_1 | Child_2 | “Rick” | “Tennis”, “Dancing” |
Parent_1 | Child_3 | “Bob” | “Painting”, “Basketball”, “Reading” |
Parent_2 | Child_4 | “Mary” | “Football” |
Then:
Active instance | Expression | Result | Type |
---|---|---|---|
Parent_1 | SIZE ( Parent.has_Children ) | 3 | Integer |
Parent_2 | SIZE ( Parent.has_Children ) | 1 | Integer |
none | SIZE ( Parent.has_Children ) | Error | |
Child_1 | SIZE ( Child.hobbies ) | 2 | Integer |
Child_3 | SIZE ( Child.hobbies ) | 3 | Integer |
Child_4 | SIZE ( Child.hobbies ) | 1 | Integer |
SIZE( ? ) | 0 | Integer |
SIZE and COUNT are similar except for ?:
SIZE ( ? ) results in 0, while COUNT ( ? ) results in ?
UNIQUE
The UNIQUE
function filters duplicate items from a collection. An expression resulting in a collection, never contains duplicate values. A subexpression with the COLLECT
statement however, can contain duplicates. See the note on collections and duplicates for more info.
Syntax
UNIQUE ( collection )
- collection - A collection of attribute or entity instances.
Examples
Suppose the following model.
Person instance | Person.name |
---|---|
Person_1 | “Kim” |
Person_2 | “Rick” |
Person_3 | “Bob” |
Person_4 | “Rick” |
Expression | Result | Type | Note |
---|---|---|---|
COLLECT Person.name FROM ALL Person | [ "Kim" , "Rick" , "Bob" ] | String (multivalued) | A result never contains duplicate values |
SIZE ( COLLECT Person.name FROM ALL Person ) | 4 | Integer | A subexpression can contain duplicate values |
SIZE ( UNIQUE ( COLLECT Person.name FROM ALL Person ) ) | 3 | Integer | The collection holds three unique values |
SUBSET OF
This function returns TRUE
if the items in a collection are all present in another collection.
Syntax
collection1 SUBSET OF collection2
- collection1 - The collection that is tested to be a subset of the second collection.
- collection2 - The collection that is tested to hold all the items in the first collection.
Return type
- boolean
Diagram
Examples
Expression | Result | Type | Note |
---|---|---|---|
( 'a' , 'b' , 'c' ) SUBSET OF ( 'a' , 'b' , 'c' , 'd' ) | TRUE | Boolean | |
( 'a' , 'b' , 'c' , 'd' ) SUBSET OF ( 'a' , 'b' , 'c' ) | FALSE | Boolean | |
Person.hobbies SUBSET OF [ "Tennis" , "Soccer" , "Music" ] Given Person.hobbies = [ "Tennis" , "Soccer" ] | TRUE | Boolean | |
Person.hobbies SUBSET OF [ "Tennis" , "Soccer" , "Music" ] Given Person.hobbies = [ ? ] | ? | Boolean | |
Person.hobbies SUBSET OF [ "Tennis" , "Soccer" , ? ] Given Person.hobbies = [ "Tennis" , "Soccer" ] | FALSE | Boolean | [ "Tennis" , "Soccer" , ? ] evaluates to [ ? ] Person.hobbies SUBSET OF [ ? ] = FALSE |
( 'a' , 'b' , 'c' ) SUBSET OF ( [ 'a' , 'b' , 'c' , 'd' ] ) | Error |
UNION
Adds two collections of the same base type to a new collection.
Syntax
UNION ( collection1 , collection2 )
- collection1 - First collection to be added to the new collection.
- collection2 - Second collection to be added to the new collection.
Return type
- collection
Diagram
Examples
Suppose you have a Parent
and a Child
entity, where Parent
has a multivalued relation with Child
via the relation Parent.has_Children
. With this model the following instances are created:
Parent instance | Child instance | Child.name | Child.hobbies |
---|---|---|---|
Parent_1 | Child_1 | “Kim” | “Reading”, “Dancing” |
Parent_1 | Child_2 | “Rick” | “Tennis”, “Dancing” |
Parent_1 | Child_3 | “Bob” | “Painting”, “Basketball”, “Reading” |
Parent_2 | Child_4 | “Mary” | “Football” |
Expression | Result | Type |
---|---|---|
UNION ( Parent[Parent_1].has_Children , Parent[Parent_2].Has_Children ) | [ Child_1, Child_2 , Child_3, Child_4 ] | Collection of Child instances |
UNION ( Parent[Parent_1].has_Children.name , Parent[Parent_2].Has_Children.name ) | [ “Kim”, “Rick”, “Bob”, “Mary” ] | String (multivalued) |
UNION ( Child[Child_2].hobbies , "Reading" ) | [ “Tennis”, “Dancing”, “Reading” ] | String (multivalued) |
UNION ( Child[Child_1].hobbies , Child[Child_2].hobbies ) | [ “Reading”, “Dancing”, “Tennis” ] | String (multivalued) |
INTERSECTION
This function determines the intersection of two collections. It returns a collection containing the items that are present in both specified collections.
Syntax
INTERSECTION ( collection1 , collection2 )
- collection1, collection2 - Collections to be intersected. These collections must be of the same base type.
Return type
- collection
Diagram
Examples
Suppose the following model. Entity Teacher
has a multivalued relation with entity Child
via the relation Teacher.teaches_Children
.
Teacher instance | Child instance | Child.name | Child.hobbies |
---|---|---|---|
Teacher_1 | Child_1 | “Kim” | “Reading”, “Dancing” |
Teacher_1 | Child_2 | “Rick” | “Tennis”, “Dancing” |
Teacher_1 | Child_3 | “Bob” | “Painting”, “Basketball”, “Reading” |
Teacher_2 | Child_1 | “Kim” | “Reading”, “Dancing” |
Teacher_2 | Child_3 | “Bob” | “Painting”, “Basketball”, “Reading” |
Teacher_2 | Child_4 | “Mary” | “Football” |
Expression | Result | Type |
---|---|---|
INTERSECTION ( Teacher[Teacher_1].teaches_Children , Teacher[Teacher_2].teaches_Children ) | [ Child_1 , Child_3 ] | Collection of Child instances |
INTERSECTION ( Teacher[Teacher_1].teaches_Children.name , Teacher[Teacher_2].teaches_Children.name ) | [ "Kim" , "Bob" ] | String (multivalued) |
INTERSECTION ( Child[Child_1].hobbies , Child[Child_3].hobbies ) | [ "Reading" ] | String (multivalued) |
INTERSECTION ( Child[Child_2].hobbies , Child[Child_3].hobbies ) | [ ] | String (multivalued) |
DIFFERENCE
This function returns a collection containing all the items from collection1 that are not present in collection2.
Syntax
DIFFERENCE ( collection1 , collection2 )
- collection1, collection2 - Collections to be compared. These collections must be of the same base type.
Return type
- collection
Diagram
Examples
Expression | Result | Type |
---|---|---|
DIFFERENCE ( [ "a", "b", "c"] , [ "c", "d", "e" ] ) | [ "a" , "b" ] | String (multivalued) |
DIFFERENCE ( [ "nv" , "bv" ] , [ "NV" ] ) | [ "bv" ] | String (multivalued) |
DIFFERENCE ( 1 , 1 ) | [ ] | Integer (multivalued) |
SYMMETRIC DIFFERENCE
This function determines the symmetric difference between two collections. It returns a collection with the elements of the provided collections which are in either one of the collections, but not in both.
Syntax
SYMMETRIC_DIFFERENCE ( collection1 , collection2 )
- collection1, collection2 - Collections to be compared. These collections must be of the same base type.
Return type
- collection
Diagram
Examples
Expression | Result | Type |
---|---|---|
SYMMETRIC_DIFFERENCE ( [ "a" , "b" , "c" ] , [ "c" , "d" , "e" ] ) | [ "a", "b", "d", "e" ] | String (multivalued) |
SYMMETRIC_DIFFERENCE ( [ "nv" , "bv" ] , [ "NV" ] ) | [ "bv" ] | String (multivalued) |
SYMMETRIC_DIFFERENCE ( 1 , 1 ) | [ ] | Integer (multivalued) |
A note on collections and duplicates
An expression resulting in a collection does not contain duplicates. Please be aware however, that intermediary results of a COLLECT
statement can contain duplicates. You have to be aware of this when using the SIZE
or UNPACK
function, or when using TSL.
This is best illustrated with the following examples.
Person instance | Person.Name | Person.Age |
---|---|---|
Person_1 | Kim | 24 |
Person_2 | Rick | 25 |
Person_3 | Bob | 25 |
Expression | Result | Type | Note |
---|---|---|---|
COLLECT Person.Age FROM ALL Person | [ 24 , 25 ] | String (multivalued) | |
SIZE ( COLLECT Person.Age FROM ALL Person ) | 3 | Integer | The intermediary collection is [ 24, 25, 25 ] |
TSL: The ages present are: [[[ COLLECT Person.Age FROM ALL Person ]]]. | The ages present are: 24, 25, 25. | String | The intermediary collection is [ 24, 25, 25 ] |
SIZE ( UNIQUE ( COLLECT Person.Age FROM ALL Person ) ) | 2 | Integer | The duplicates in the intermediary collection are filtered by the UNIQUE function |
Now an example with the UNPACK function. We leave out the first instance from the previous example.
Person instance | Person.Name | Person.Age |
---|---|---|
Person_2 | Rick | 25 |
Person_3 | Bob | 25 |
Expression | Result | Type | Note |
---|---|---|---|
COLLECT Person.Age FROM ALL Person | [ 25 ] | Integer (multivalued) | |
UNPACK ( COLLECT Person.Age FROM ALL Person ) | Error | The collection contains 2 elements [ 25 , 25 ] | |
UNPACK ( UNIQUE ( COLLECT Person.Age FROM ALL Person ) ) | 25 |
Only the intermediary results of a COLLECT
statement can contain duplicates. The functions UNIQUE
, UNION
, INTERSECTION
, DIFFERENCE
and SYMMETRIC_DIFFERENCE
always return collections without duplicates.