Managing queries

A Query is a mean to create a set of source resources, and potentially explore the relations between this source set and target artifacts that respect certain given properties / relations.

SECollab lets you create queries to analyse your current engineering data:

• To further explore relations between resources
• To enable reporting capabilities

We have 2 types of queries

• Simple Query to get a list of objects
• Join Query to explore relations between resources and get a map of source/target related objects

The result of the execution of a Simple query is a flat list of "artifacts", if any.

The result of the execution of a Join query is a set of "source artifacts" mapped to "target artifacts", if any.

Creating queries

To create Queries, go to the Project Administration's "Queries" section:

• Click the "+ New query" link
• Set a title and a description
• Select the query type between Simple or Join Query
• Complete query settings according mandatory fields

Creating a Simple Query

• Select The Source Type to get an initial set with all compatible resources in the project
• Write an optional query filter allowing to restrict the initial set with a specific condition. The query will return all the resources matching this filter.

Creating a Join Query

• Choose the type of the source artifacts that this query should apply on
• Choose the type of the target artifacts that this query should try to map
• Write the source filter to fetch source artifacts that are of interest to your analysis
• e.g. you selected the source type "requirement", but are only interested in DOORS' and not in Word's
• Specify the join condition that maps source artifacts to target artifacts
• Writing a Free query filter allows you to write a specific condition clause to compute from the filtered source related elements
• e.g. you filtered out DOORS requirements for source, and diagrams for target, and now want to see how those resources are traced through a custom collaborative link that you previously defined
• Setting a Typed query filter allows you to specify an existing collaboration link to compute from the filtered source related target elements
• Note: Typed Query are mandatory to create Matrix Report because we have to point one unique specific collaboration link for the matrix view
• Write the target filter to fetch only target artifacts that are of interest to your analysis
  • e.g. you selected the target type "requirement", but are only interested in DOORS' and not in Word's

A SECollab query (according its type) can then be decomposed from one up to tree separate clauses: source filter, join condition and target filter.

Writing query filters (source & target)

When creating a query, you need to write a clause that fetches relevant resources. Such a query is meant to check if a resource has a given set of properties, or if one of its linked resources has a given set of properties. To access a property, you need to write the namespace prefix and the property name, such as `dcterms:title`. Backquotes are required to express properties. Double quotes (") are used to express strings, and <> are used to express URI.
E.g.:

• to check a title is exactly "hello": `dcterms:title` = "hello"
• to check a title is not "hello": `dcterms:title` != "hello"
• to check a title starts with "hello": `dcterms:title` =~ "hello*"
• to check a title contains "hello": `dcterms:title` =~ "*hello*"
• to check a doors custom property named ieobjecttype contains "REQ" : `doors:ieobjecttype` =~ "*REQ*"
• to check a doors custom property named iepuid is empty (literal value) : `doors:iepuid` != ""
• to check for a URI property, use <> instead of "", like when testing if the design was published by the DOORS publisher: `clm:design`.`clm:tool` = <https://secollab.acme.com:8443/secollab/clm/services/tool/com.sodius.mdw.clm.client.tool.doors>
• to ensure an object value (property pointing a resource and not a literal) exists, use NULL as to confirm there is a description on your resource: `dcterms:description` != NULL
• you can use AND, OR and parenthesis to write your query: (`dcterms:title` =~ "*hello*" OR `dcterms:description` =~ "*hello*") AND `clm:design`.`clm:tool` = <https://secollab.acme.com:8443/secollab/clm/services/tool/com.sodius.mdw.clm.client.tool.doors>

Writing a query filter is the same as writing a resource type's query. Please check Managing resource types for more details.

Writing join condition

A join condition is typically written as a test that a relationship exists.

• to check a collaborative link exists: `clm_custom:myLink` != NULL
• to explore multiple links: `clm_custom:myLink`.`clm_custom:myOtherLink` != NULL
• you may use the OR operator in join queries
• you should not use the AND though, which is not supported

Custom Collaborative links and resource types are always prefixed with clm_custom.