Concept Queries

Advanced custom queries with the WEM Ontology tools

Concept Queries can be used to create custom filtered collections on the Concepts in your Project. This part is quite abstract and can be used in a complex concept-model with custom relations between the concepts and custom concept types. For the basic and more straightforward filtering of concepts, you could do a lot already with the available Concept-Functions in Expressions.

Illustration - preface

For the purposes of understanding this topic a little better, let us consider the following use case.

A Company has a page to add and manage users.
A User has a user name, a role, one or more functions and a location (country). In the screenshots below, you can see the Data Model and the Concepts tree.
Requirements:
- A user with Role = Admin can be assigned one or all of the 4 functions - Add / Modify / Delete / View Users).
- A user with Role = Advanced User can be assigned one or all of only 3 functions - Add / Modify / View Users).
- A user with Role = Regular User can only be assigned one function - View users.

We will now show how the Requirements can be implemented using Concept Relations and Queries.

Concept Queries Designer

A Concept Query is a Definition that will yield a collection of concepts. It can be used in Expressions as being a List of Concepts (similar to a Concept-Set or Multi-Select). Or it can be used as Source for Single/Multi Select Input fields, to present a specifically filtered list of options to choose from. The Concept Query contains of certain Nodes, Annotations/Indicators and Relations to form the Definition by which the Concepts are checked and collected to be presented as the result.

To add a new Concept Query, you need to go to the Concepts and concept queries section of your Project. To add a new Concept Query, right-click on Concept Queries or click on the ... to open the context-menu and click on New concept query from the menu as shown below.

You are then prompted to enter a name for the Concept Query.

Once you name your Concept Query, you are presented with the concept query designer. On the screen, you can see the Concept Query editor menu at the top and more importantly, the concept query nodes at the left. Then you have the canvas where you would drag and drop nodes from the left, just as you would while working on a flowchart, and use the items in the editor at the top. This would create a concept query.

Concept query editor

Concept query nodes

We'll first discuss the (greyish) Literal Nodes, before we get back to the first node (the Unknown Concept).

This node can be used to select one specific single concept item from your Concept tree.

Illustration 1.1:

Let us re-visit the use case that we had above and let's see how we can achieve this requirement using a concept query that uses a single-select literal - "A user with Role = Regular User can only be assigned one functions - View users."

Once you have added a new concept query and given it a name, drag the single-select node on to the canvas. This will bring up a prompt, where you need to select one and only one concept item. In our use case, we want to select 'View Users' under 'Functions'.

Once you do that, you will see something like the below. You may notice the Invalid error on the editor menu (top).

2. The next step would be to click on node and then click on the Include button on the editor menu. This will change the node as you can see below and the Invalid error is no longer there.

3. The last step would be to use this concept query in an interaction node. In this example, we have a conditionals that would allow different configurations for the 'Functions' field, based on the value selected for 'Role'. For now, let us focus on the last one in the screenshot below. We have now applied the concept query to the single-select field 'Functions', if 'Role' = 'Regular User'.

Now, this is what you see as a result. As you can see, the 'Functions' has been filtered on one value that is configured in the ontology query.

Illustration 1.2:

Let's now try the next requirement - "A user with Role = Advanced User can be assigned one or all of only 3 functions - Add / modify / view users".

One of the ways this can be achieved is by using single-select literals as shown below. This illustrates that there can be more than one nodes in a query.

Note: There are better ways of handling this requirement using multi-select literals, which we will see shortly.

Just as the name suggests, this works the same way, except that it there can be multiple concept items assigned to the node.

Illustration 2.1:

Let's go back to the earlier requirement that we had fulfilled in Illustration 1.2 - "A user with Role = Advanced User can be assigned one or all of only 3 functions - Add / modify / view users".

Instead of using 3 single-select literals for 3 individual concept items, we could use one multi-select literal and assign all the 3 concept items for the same result. Notice the values assigned at the right-hand panel.

But there is yet another way of doing this.

Illustration 2.2:

We will learn about the Exclude option in the editor menu now. So, instead of including 3 of the 4 concept items as we did in Illustration 2.1, we could also Include all 4 concept item in one node and the Exclude 1 concept item in another node for the same result.

Note the Include annotation on the first node that is assigned all 4 values and the Exclude annotation on the second node that is assigned one value that we do not need.

This method could get unweildy when the full list of values that need to be included, get longer. We will shortly see yet another way of handling the same scenario.

The Unknown Concept node lets you define in a more dynamic way which concepts are part of this Node as opposed to the static Literal Concept nodes as discussed before. You can easily assign the entire pick-list to this node without having to select individual concept items under the list, just by indicating the Root Concept and the Depth.

Illustration 3.1:

Continuing from Illustration 2.2, we will now see how we could use the unknown concept to simplify the query.

As you can see from the right hand panel, we have assigned All Children of the 'Functions' concept item to the unknown concept node. This will select only the direct children (all concepts of the single level below the chosen root concept). If there are deeper levels under the chosen root concept and you want all those concepts as well, the All Descendants option can be used.

The 'Type'-property in the right-hand panel can be used to filter the children further based on a concept type that exists and is defined on the concepts within the root.

Mind: the chosen root concept (in this case, 'Functions') is NOT part of the result...

While the Single Select literal node holds one specific concept item statically, a Single Select Data Field can be used to get a specific Concept Item that is defined at runtime in the User Session. This can make the Concept Query even more flexible and linked to any situation in Runtime.

Let's build upon the earlier use cases where we used different concept queries to add users to the database. Now, let's shift our focus to the User Summary screen that shows a list of all users. We would like to filter the users list based on a role. This can be achieved by creating a concept query with a single select data field.

Illustration 4.1:

To create this query, we need a single-select data field. Let's use the session data field 'Select user role' for this.

We now create a concept query and drag the node onto the canvas. This immediately prompts us to select a single-select data field. Another option is to directly drag the specific Single Select Data-field from the Data Model tree onto the Concept Query Canvas, and it will create the Single Select Data Field node.

Once that is done and the node annotated with Include, the query is ready.

Next, we create a filter in the 'Users' table as shown below.

This approach does not really need a Concept Query, as you can also directly use the Select User Role data-field (holding the selected concept to filter) in the filter expression. In that case, you can just use [Users.Role] = [SelectUserRole] in your expression, as they are both single select fields holding one specific concept. This is just to illustrate a basic approach to using Concept Queries, which can be made more complex.

This is very similar to the above, except that the data field that is being used here is of multi-select data type. Again, also possible to achieve directly in Expression, but then you'll need something like[Users.Role] in [MultipleSelectedUserRoles] in your expression, to check if the single User Role is part of the selected Roles in the Multi-Select. Using the Concept Query always assumes that the result is a list of concepts, with 0, 1 or more concepts, so in expressions a Concept Query must always be treated as a Concept-List.

Text literal is a way to filter Ontology items (concepts) based on text matching exactly or containing or starting with or ending with a specific text, with an option to indicate whether or not the search should be case sensitive.

Illustration 6.1:

Let's consider a concept item consisting of a list of countries.

Now, say we would like to filter and show only the countries whose names start with 'U'.

We start by creating a new concept query and adding an unknown concept node and assigning it to the concept item 'Countries' and annotating it with Include option.

We then drag the text literal on to the canvas.

As you can see, the right hand panel shows a field where you can enter the text that you would like to search, then the matching options (exact / contains / starts with / ends with) and an option box to indicate whether you want the search to be case sensitive or not. We fill these options as appropriate ( Starts With U, not case-sensitive).

Finally, we need to indicate that the condition that has been set in the literal node has to apply to the unknown concept query node. This is achieved by making a connection as shown below, with an arrow that allows you to select a Relation from the available options, to indicate whether the filter should be performed on:

alternative terms that are added to the Synonyms property in the concept items;
the display name property of the concept (language-sensitive);
the description property of the concept.

The final query in our illustration looks like this.

This can be read as: "Include all child concepts of Countries that have a Display Name that starts with U."

While the text literal that we saw in the previous section is set to a fixed text, we can also use Text Data Field to match with a text value from the User Session in Runtime. This last node allows you to select a Text Data Field from your Data Model to use, while you can also drag a Text Data Field from the Data Model tree directly onto the Concept Query Canvas and that will create the Text Data Field Node.

Now you've seen the basics for Concept Queries. In the next part we'll dive into the Concept Relations, that give even more possibilities to create complex Concept Queries, using pre-defined relations and even with your own Custom Relations between Concepts.