Query Guide
In this guide, we build a first query on the Order Management dataset, which returns every order together with the event in which it was paid.
Loading an OCEL
Before using OCPQ, you first need to load an object-centric event log.
OCPQ supports all OCEL 2.0 formats (XML, JSON, and SQLite), as well as CSV and ZIP bundles.
Case-centric event logs in the XES format are also supported, where each case becomes an object of type Case.
To get started, you can download publicly available OCEL 2.0 files from here.
For importing a file, click on the drop zone of the start page 1 or drag the file onto it.
Opening the Query Editor
After the import, OCPQ shows the OCEL Info page, which lists the event and object types of the log and how they are related.
From there, you can open the query editor using Queries in the sidebar 1.
Creating a Query
As long as there are no queries yet, the editor offers to create one 1.
Afterwards, further queries can be added using the New query button on the top right.
A new query starts with one empty box. In the header, you can rename the query 1 and add a description 2. The toolbar of the editor allows adding more boxes 3 and evaluating the query 4.
Shortcuts: Alt+N adds a box, and Ctrl+Enter evaluates the query.
Adding Variables and Filters
Each box has a + button for each of its sections:
- Object variables 1
- Event variables 2
- Filters 3
- Labels 4, covered in the CEL Labels Guide
- Constraints 5, covered in the Constraint Guide
Object Variables
To add an object variable, click on the + next to Object Variables.
In the dialog, you can then set two options:
- The variable name 1, by which filters and constraints refer to the variable.
We keep the suggested name
o1. - The object types the variable can take 2, together with the number of objects of each type in the log.
For our example, we select
orders. If several types are selected, the variable can be bound to an object of any of them.
Finally, Add 3 adds the variable to the box.
Event Variables
Event variables are added in the same way, using the + next to Event Variables.
Here, we keep the name e1 1 and select the type pay order 2.
By default, the list only shows event types that are related to the variables already in the box (here, 4 of the 11 event types).
Below the types, OCPQ suggests how the new variable can be connected to the existing ones 3.
In particular, it offers an event-to-object (E2O) relation between e1 and o1, which can be restricted to one relationship qualifier or kept as Any qualifier.
Add and connect 4 then adds the variable together with the selected connections.
The box now contains both variables as well as an E2O filter between e1 and o1.
As such, only pay order events involving the bound order are considered.
Additionally, the header of the query describes it in a sentence, which is updated as you edit the query:
Filters
Further filters can be added using the + next to Filters.
The dialog lists all filter types 1 (e.g., relations between variables, attribute values, the time between events, or CEL expressions).
Types that cannot be used in the box yet are greyed out.
For example, Time Between Events requires two event variables.
Using the Use as switch 2, the predicate can also be added as a constraint instead of a filter.
Evaluating the Query
To evaluate the query, click on the play button 1 (or press Ctrl+Enter).
Each box then shows its number of bindings 2, here one for each of the 2,000 paid orders.
Clicking on that number opens the bindings as a table in the Inspector on the right 3, where clicking on an ID shows the details of that event or object.
The header shows the share of bindings that violate the constraints of the query 4.
As this query has no constraints, nothing is violated.
