Skip to content

Prepared queries

Usage

A prepared query is a common, potentially complex, query that can be performed on the knowledge graph.

Prepared queries can be used in multiple different contexts:

  • Directly called from a visible entity in the explorer view of admin GUI
  • Exposed as a simple page, with the right input fields, and displaying a table with the results
  • Accessed through the REST API, returning results either as a graph or as a table
  • Used in assertion subjects (more information here)

Like most CogTL configuration elements, it has a name and an informative description. A prepared query also can also have a short name, which will be used in URLs when you publish this prepared query as a public query or when you want to use this prepared query through the OpenAPI. This attribute is optional, but if you don't define it the accessibility of the prepared query could be limited.

Two checkboxes also alter the accessibility of this prepared query:

  • Include in public queries view : if checked, this prepared query will be published in the Queries view.
  • Include in explorer navigation : if checked, this prepared query will be accessible in entities popup menu in the Explorer view.

A prepared query can be based on navigations, or on a CoQL query.

Prepared queries based on navigations

A prepared query based on navigations allows to define "paths" to follow on the knowledge graph to obtain results. It requires Roots (the starting points for the navigations), and Navigations (the "rules" to follow to navigate on the graph).

Roots

Roots are entities of a specific entity type. If the prepared query is going to be used in another way than the explorer view, you have to define a data type (belonging to the selected entity type), an optional label, and whether you want to perform exact queries of free text queries on this data type.

The entity type specified will condition the display of this prepared query on the popup menu of entities in the explorer view.

Navigations teach CogTL how to navigate on the knowledge graph. Navigations will start from a root that has been found/selected. More help about navigations can be found here.

When a navigation has successfully reached an entity at the end of a path, this last entity can be given a variable name, so that it can be re-used as the starting point for another navigation, or included in tabular results.

By default, the whole path from the origin of the navigation to the destination entity will be included in the result, but if the details are not necessary, you can specify an output relation type that will be used to virtually link the origin to the destination without including all intermediate entities and relations.

If no existing relation type is applicable, you can also specify a transient relation type, which is a simple name that will be used to label the relation between the origin to the destination.

It is also possible that this intermediate entity is not required in the result graph (for example, if the navigation is only an intermediate step in a more complex query). You can then check Don't include in result to avoid it to be returned.

Finally, it is also possible that you want to draw the resulting relation starting from another origin that the current root. Again, this is generally used in a complex prepared query with multiple navigations, when some navigations are just intermediary steps.

By default, only one successful navigation can produce a result of the prepared query. If all navigations must have a result, All navigations must have a result should be checked.

Finally, you can select what variables must be included in the final paths.

Prepared queries based on a CoQL query

CoQL queries are also a simple an efficient way of performing knowledge queries. When navigation queries are rather used to start from specific roots and search around those identified entities, CoQL queries allows to have a more "random" access to the whole knowledge graph, and find a restricted set of entities more efficiently.

Prepared queries based on a CoQL query cannot be used from the Explorer view of admin GUI, as they don't have a root. However, they can be used from the query GUI and REST API with or without parameters also. To define one or more parameters in the query, use the input("Variable") syntax. This value will be replaced by the value of the parameter whose name is the string given, i.e. Variable in this example.

Example: 

name=input("EmployeeName") .type="Person" -(is member of)-> #SensitiveTeam

The query above would use the parameter EmployeeName, perform an exact search of this value on the name attribute of all entities of type Person, that are member of another entity tagged as #SensitiveTeam.

More information about the syntax of CoQL queries can be found here.

Presentation

The presentation part allows you to define how CogTL will transform the query results (that are natively under the form of a graph) to a table.

By default, all data types of the entities identified by a variable will be included, in columns named as <variable>.<datatype>. As this is sometimes not really used friendly, you can specify alternate column names for the columns that you want to see in the result. You just have to write the list under the form:

P.name=Person
T.name=Team
T.responsible=Responsible

In the example above, every result would have three columns: Person, Team and Responsible. The rest of the entities data is not included in the result.

If the prepared query is based on a CoQL query, then you don't have variable names, however you can still refer to the entities found by using the pseudo-variable @, or @2..@n for subsequent "conditioned" entities.

For example, if you have written a CoQL query like the following:

.type="Person" #withThisFlag

... you will be able to refer to the name of the Person by using the column name @.name.

For a more complex CoQL query like this one:

.type="Person" -(is managed by)-> .type="Person" #withThisFlag

... you will be able to refer to the managed person (left side) with @ like before, but also to the manager (right side) with @2. Thus to get the name of the manager, you can use the column name @2.name.

It is also possible to use expressions to format or compute columns value, using the syntax exp:<expression>. For example, you can write the following:

exp:factor(P, "confidentiality risk")=Confidentiality

... to create a column Confidentiality containing the value of the factor confidentiality risk for the entity represented as P. You can also obviously use all possibilities of expressions to combine, concatenate, calculate or transform values.

If multiple paths are found from the same origins to the same results, you can opt in to merge the similar rows generated by checking Merge lines with similar results.