Query language

Card key

docs_33

Status

Ready

Card type

base/cardTypes/page

Labels

Owner

N/A

Information classification

public

This page introduces the Cyberismo query language.

Basic example

Let’s get started with Cyberismo queries by a simple example that returns the title of all cards of the card type base/page in alphabetical order:

select("title"). (1)
result(Card) :- card(Card), field(Card, "cardType", "base/cardTypes/page"). (2)
orderBy("title", "ASC"). (3)
1 Return the title field. Notice the period at the end of each line.
2 Include Card in the results if the card type field equals base/page
3 Sort the results by the title field in an ascending order.

Selecting the fields and other properties of the results

The results of the queries are identified by a key, which is typically a card key. To return selected attributes of a key, use the select or selectAll term.

For example, to include the fields title and workflowState, you can use:

select("title";"workflowState").

Which is equivalent to:

select("title").
select("workflowState").

To select all fields in the results, use:

selectAll.

The following special cases are supported:

Select term Meaning

select("labels").

Include labels in the results

select("links").

Include links in the results

select("policyChecks").

Include information about successful and failed policy checks in the results

select("deniedOperations").

Include information about denied operations such as denied workflow transitions, denied moving etc.

Selecting the results

The result(X) term denotes that X will be included in the results of the query. The following query returns all fields of entity (most likely a card) that has the key docs_33:

selectAll.
result(docs_33).

Logic program rules are used to select results that match a condition. For example, the following query returns all cards that are in the workflow state Open.

selectAll.
result(Card) :- card(Card), field(Card, "workflowState", "Open").

The card(Card) term is included to make sure that all returned entities are cards.

Conjunction (logical and)

A logic program rule can include several conditions that are separated by a comma. Such a rule is a conjunction, as it requires all conditions to be true, so it corresponds to the logical and operator. For example, the following query returns all cards that are of the card type base/page and have the workflow state Open.

selectAll.
result(Card) :-
    card(Card),
    field(Card, "cardType", "base/cardTypes/page",
    field(Card, "workflowState", "Open").

Disjunction (logical or)

To implement a disjunction, which returns results for which at least one of the conditions is true, use multiple rules. The following query returns all cards that are either of the card type base/page or have the workflow state Open, corresponding to the logical or operator.

selectAll.
result(Card) :-
    card(Card),
    field(Card, "cardType", "base/cardTypes/page".
result(Card) :-
    card(Card),
    field(Card, "workflowState", "Open").

Ordering the results

The results of the query can be ordered by one or more fields in an ascending or descending order.

There is no default order, but the Cyberismo query language requires you to explicitly include either the ascending ("ASC") or descending ("DESC") direction.

To order by one, two or three fields, you can use the orderBy term. For example:

orderBy("title", "ASC").

Or:

orderBy("workflowState", "ASC", "title", "DESC").

Or:

orderBy(
    "workflowState", "DESC",
    "rank", "ASC",
    "title", "ASC").

If you need to order by more than three fields, then use the order term. The previous example can be written equivalently with three order terms as follows:

order(1, 1, "workflowState", "DESC").
order(1, 2, "rank", "ASC").
order(1, 3, "title", "ASC").

The parameters of the order term are:

  1. The level of hierarchy of the results that will be sorted. When the query is not hierarchical, this is 1.

  2. The index of the field by which to sort. For example, the index 1 means that you should first order by the field given in this occurrence of the order term.

  3. The field by which the results should be ordered

  4. Either "ASC" or "DESC".

Summary queries

The key of the results does not always have to be a card key. For example, the following summary query works similarly to an SQL query that uses "GROUP BY", as it returns the different workflow states of the cards that are descendants of docs_9, and for each workflow state, it calculates a count attribute that contains the number of cards in the given state. Notice that it is this query that introduces the count attribute, rather than selecting a pre-existing attribute.

selectAll.
result(State) :-
    ancestor(Card, docs_9),
    field(Card, "workflowState", State).

field(State, "count", Count) :-
    result(State),
    Count = #count { card(X) :
        ancestor(X, docs_9),
        field(X, "workflowState", State)
    }.

Hierarchical queries

So far, the results of our queries have formed a flat list. A hierarchical query returns a tree structure: each result may have list of child results, which in turn may have child results.

For example, say we would like to query the children and grandchildren of docs_9 according to the the card tree hierarchy. We would like the direct children to form the first level of hierarchy, and each child would have their children as child results. This can be done with the following query:

select("title"). (1)
result(Card) :- parent(Card, docs_9).
childResult(Child, Grandchild) :- parent(Grandchild, Child), result(Child). (2)
orderBy("title", "ASC"). (3)
1 select with just one parameter and selectAll without parameters refer to all levels of hierarchy.
2 Child results are returned with the childResult term
3 When orderBy has an even number of parameters, it refers to the results on all levels of hierarchy

What if you want to select different fields on different levels of hierarchy, or order the results differently on different levels of hierarchy? In these cases, you can include the level of hierarchy (1, 2, etc.) as the first parameter to select, selectAll, or orderBy:

select(2,  "title"). (1)
orderBy(2, "title", "ASC"). (2)
1 the first parameter indicates the level of hierarchy and the second parameter indicates, which field to select on the given level.
2 When orderBy has an odd number of parameters, the first parameter denotes the level of hierarchy.