Structure of highlight queries

The aim of highlight queries is to provide users with relevant information about the records that are associated with the current subject of their investigation. The structure of the queries that you create reflects the idea of starting from the subject and finding records that are one, two, or more links away.

When a user examines records of the same type, they expect to be able to compare them in a consistent way. Highlight queries are grouped by type in the configuration file, and records of a particular type are always displayed with the same set of highlight panes for the same user.

Highlight queries themselves use the idea of a path to describe how the results of the query are related to the subject. The path is made up of segments that take the results one step further from the subject, like this:

At a minimum, each segment in a highlight query specifies the link type and the entity type of the records that match it. For example, a highlight query for finding people who live at the same address as the subject person might have two segments:

• A link of type 'Lives At' and an entity of type 'Address'. If this segment was the last one in the path, the results would be of type Address, and users might see a list of past and current addresses for the subject.

• A link of type 'Lives At' and an entity of type 'Person'. The records found in the first segment are used as inputs to the second segment, so the full query returns a list of all the people who are known to have lived at the same addresses as the subject.

You can further constrain the results of a highlight query by placing conditions on the link and entity records in the Information Store that each segment matches. Depending on the schema, you might decide that you are only interested in addresses that the subject has 'Lived At' in the last three years, or when the 'Address' is in a particular city or country. Similarly, you might only want to find people who are female (or, alternatively, male).

As well as controlling which records you want to find with a highlight query, you can control how users see the query results in highlight panes. Every query has a name and a description that users can read to understand what the results in front of them mean. For the results themselves, you can specify how to sort them, and what values to display in the limited space that highlight panes provide.

The values that users see in highlight panes do not have to come from the records that form the results of the query. In each segment of a highlight query, you can export values from the link and entity records that form part of a found path. For example, imagine a highlight query for bank account records whose single segment finds other accounts that are connected through transaction links. You can export the value of the largest transaction from the segment, and then set it as one of the outputs from the path.

Finally, as well as exporting property values from the segments of a highlight query, you can export (and subsequently output) the counts of the records that the highlight query finds at each point on the path.

In the diagram, the five records on the right are results of a highlight query whose subject was the single record on the left. When you present the results to users, you can output or sort by the counts of records along their paths. The meanings of the counts, and whether they are useful, vary according to the specifics of the highlight query.