CogTL Query language (CoQL)

Simple entities queries

CoQL is a way to find atomic entities or patterns of interconnected entities.

The easiest query type is a free-text, unrestricted query:

text

... will try to find text in any data value of any entity of any type. The kind of search will be a full text search, meaning that every word will be searched on its own, and similar phonemes are grouped (e.g. if you search for bar, you will also find the plural noun bars).

An exact search can be performed by using double quotes:

"text"

... will find all entities that have the exact value text in any data type. An entity that has a value like texts won't be retrieved by this exact search.

For a contains search, use the tilde symbol before quotes:

~"text"

... will match all entities containing the string text in a data value. "texts" will match, "a text" will match.

To restrict the query to certain data types, you can use data exact, contains or regex search :

name = "James"
name ~= "text"
name ~ ".*ext"

Comparison or negation operators (>, <, >=, <= or !=) are also available for string, or numeric data types (numeric values can be given unquoted):

age <= 30
name > "Leon"
title != "Mr"

... will match entities having a value for the datatype age less than or equal to 30, or a value for name alphabetically greater than "Leon", or a value for the datatype title that is not equal to "Mr".

Scoping

You can find entities that are flagged with a specific tag:

#MyTag
name="John" #Flagged

... will only find entities that match all the conditions (having the name John and being tagged with the #Flagged tag).

You can also negate this tag, by using the ! symbol:

name="John" !#Flagged

... will find entities that have the name John but DON'T have the tag #Flagged.

You can restrict the scope of research by specifying specific an entity type:

.type=="Server"
name~="Alan" .type="Person"

Note that a double equals sign (==) can be used or a single sign (=). If a double equals is used, the query will be restricted to the exact specified entity type only. If a single equals sign (=) is used, the query will be restricted to the specified type and all of its descendants (see Entity types configuration for more information).

You can also restrict the scope of the research by specifying entities known by a specific knowledge source:

.source="Clients data"

It is also possible to limit the entities retrieved by using the value of a specific factor:

.factor("Level of risk")>2.5

Relation queries

You can find interconnected entities by using queries on relations. A basic relation search is written as follows:

-(is member of)->

... will find all relations of type is member of. Note that if the value specified can be either the name of a relation type or the name of a relation feature.

The standard usage of relations search is to specify constraints on the source and target entities:

.type="Person" role="MANAGER" -(is the manager of)-> contract="PART-TIME"

Will typically output all persons that manage a part-time employee.

By default, a relation search only search for an unique relation between the source an target specified, but you can specify a cardinality, optionally with minimum and maximum bounds (the star symbol (*) meaning any):

name="Bob" -(knowledge:*)-> name="Alice"
role="MANAGER" -(manages:2-3)-> .type="EMPLOYEE"

In the first example, any path between Bob and Alice will be found. In the second example, all managers having two or three hierarchical levels below them will be found.

Specific tags can also be searched on the relations:

-(knowledge #important)->

... will output all relations with the feature knowledge that are tagged as #important.

Again, tags can also be negated, to be able to find relation that DON'T have a specific tag:

-(knowledge !#important)->

When looking for tagged relations, you can even omit the relation type name (but the query will naturally be slower to execute):

-(#important)-> 
-(!#important)->

For readability, the relations can also be written in the opposite direction:

name="Alice" <-(knowledge)- name="Bob"

And all this can be chained to detect specific patterns :

name="Bob" -(knowledge:*)-> .type="Person" <-(knowledge:*)- name="Alice"

... would find all people known both by Alice and Bob.

Miscellaneous

Anywhere in the CoQL query, you can refer to a global variable, by using the syntax ${variable}. For example:

name="${variableName}"

... would find all entities with a datatype name having the value of the variable variableName.