Searching Data

• 1: Data Sources
• 1.1: Lucene Index Data Source
• 1.2: Statistics
• 1.3: Elasticsearch
• 1.4: Internal Data Sources
• 2: Dashboards
• 2.1: Queries
• 2.2: Internal Links
• 2.3: Direct URLs
• 3: Query
• 3.1: Stroom Query Language
• 4: Analytic Rules
• 4.1: Rule Queries
• 4.2: Rule Settings
• 4.3: Rule Execution
• 4.4: Rule Notifications
• 4.5: Detections
• 4.6: Duplicate Management
• 4.7: Streaming Rules
• 4.8: Table Builder Rules
• 5: Reports
• 5.1: Report Settings
• 5.2: Report Delivery
• 6: Search Extraction
• 7: Dictionaries

1 - Data Sources

1.1 - Lucene Index Data Source

Stroom’s primary data source is its internal Lucene based search indexes. For details of how data is indexed see Lucene Indexes.

1.2 - Statistics

1.3 - Elasticsearch

Stroom can integrate with external Elasticsearch indexes to allow querying using Stroom’s various mechanisms for querying data sources. These indexes may have been populated using a Stroom pipeline (See here).

Searching Using a Stroom Dashboard

Searching an Elasticsearch index (or data stream) using a Stroom dashboard is conceptually similar to the process described in Dashboards.

Before you set the dashboard’s data source, you must first create an Elastic Index document to tell Stroom which index (or indices) you wish to query.

Create an Elastic Index Document

1. Right-click a folder in the Stroom Explorer pane ( ).
2. Select:
   
   New

   Elastic Index
3. Enter a name for the index document and click OK .
4. Click next to the Cluster configuration field label.
5. In the dialog that appears, select the Elastic Cluster document where the index exists, and click OK .
6. Enter the name of an index or data stream in Index name or pattern. Data view (formerly known as index pattern) syntax is supported, which enables you to query multiple indices or data streams at once. For example: stroom-events-v1.
7. (Optional) Set Search slices, which is the number of parallel workers that will query the index. For very large indices, increasing this value up to and including the number of shards can increase scroll performance, which will allow you to download results faster.
8. (Optional) Set Search scroll size, which specifies the number of documents to return in each search response. Greater values generally increase efficiency. By default, Elasticsearch limits this number to 10,000.
9. Click Test Connection. A dialog will appear with the result, which will state Connection Success if the connection was successful and the index pattern matched one or more indices.
10. Click .

Set the Elastic Index Document as the Dashboard Data Source

1. Open or create a dashboard.
2. Click in the Query panel.
3. Click next to the Data Source field label.
4. Select the Elastic Index document you created and click OK .
5. Configure the query expression as explained in Dashboards. Note the tips for particular Elasticsearch field mapping data types.
6. Configure the table.

Query Expression Tips

Certain Elasticsearch field mapping types support special syntax when used in a Stroom dashboard query expression.

To identify the field mapping type for a particular field:

1. Click in the Query panel to add a new expression item.
2. Select the Elasticsearch field name in the drop-down list.
3. Note the blue data type indicator to the far right of the row. Common examples are: keyword, text and number.

After you identify the field mapping type, move the mouse cursor over the mapping type indicator. A tooltip appears, explaining various types of queries you can perform against that particular field’s type.

Searching Multiple Indices

Using data view (index pattern) syntax, you can create powerful dashboards that query multiple indices at a time. An example of this is where you have multiple indices covering different types of email systems. Let’s assume these indices are named: stroom-exchange-v1, stroom-domino-v1 and stroom-mailu-v1.

There is a common set of fields across all three indices: @timestamp, Subject, Sender and Recipient. You want to allow search across all indices at once, in effect creating a unified email dashboard.

You can achieve this by creating an Elastic Index document called (for example) Elastic-Email-Combined and setting the property Index name or pattern to: stroom-exchange-v1,stroom-domino-v1,stroom-mailu-v1. Click and re-open the dashboard. You’ll notice that the available fields are a union of the fields across all three indices. You can now search by any of these - in particular, the fields common to all three.

1.4 - Internal Data Sources

Stroom provides a number of built in data sources for querying the inner workings of stroom. These data sources do not have a corresponding Document so do not feature in the explorer tree.

These data sources appear as children of the root folder when selecting a data source in a Dashboard , View . They are also available in the list of data sources when editing a Query .

Analytics

Annotations

Annotations are a means of annotating search results with additional information and for assigning those annotations to users. The Annotations data source allows you to query the annotations that have been created.

Dual

The Dual data source is one with a single field that always returns one row with the same value. This data source can be useful for testing expression functions. It can also be useful when combined with an extraction pipeline that uses the stroom:http-call() XSLT function in order to make a single HTTP call using Dashboard parameter values.

Index Shards

Exposes the details of the index shards that make up Stroom’s Lucene based index. Each index is split up into one or more partitions and each partition is further divided into one or more shards. Each row represents one index shard.

Meta Store

Exposes details of the streams held in Stroom’s Stream (aka meta) store. Each row represents one stream.

Processor Tasks

Exposes details of the tasks spawned by the processor filters. Each row represents one processor task.

Reference Data Store

Reference data is written to a persistent cache on storage local to the node. This data source exposes the data held in the store on the local node only. Given that most Stroom deployments are clustered and the UI nodes are typically not doing processing, this means the UI node will have no reference data.

Task Manager

This data source exposes the background tasks currently running across the Stroom cluster. Each row represents a single background server task.

Requires the Manage Tasks application permission.

2 - Dashboards

2.1 - Queries

Dashboard queries are created with the query expression builder. The expression builder allows for complex boolean logic to be created across multiple index fields. The way in which different index fields may be queried depends on the type of data that the index field contains.

Date Time Fields

Time fields can be queried for times equal, greater than, greater than or equal, less than, less than or equal or between two times.

Times can be specified in two ways:

• Absolute times

• Relative times

Absolute Times

An absolute time is specified in ISO 8601 date time format, e.g. 2016-01-23T12:34:11.844Z

Relative Times

In addition to absolute times it is possible to specify times using expressions. Relative time expressions create a date time that is relative to the execution time of the query. Supported expressions are as follows:

• now() - The current execution time of the query.
• second() - The current execution time of the query rounded down to the nearest second.
• minute() - The current execution time of the query rounded down to the nearest minute.
• hour() - The current execution time of the query rounded down to the nearest hour.
• day() - The current execution time of the query rounded down to the nearest day.
• week() - The current execution time of the query rounded down to the first day of the week (Monday).
• month() - The current execution time of the query rounded down to the start of the current month.
• year() - The current execution time of the query rounded down to the start of the current year.

Adding/Subtracting Durations

With relative times it is possible to add or subtract durations so that queries can be constructed to provide for example, the last week of data, the last hour of data etc.

To add/subtract a duration from a query term the duration is simply appended after the relative time, e.g.

now() + 2d

Multiple durations can be combined in the expression, e.g.

now() + 2d - 10h

now() + 2w - 1d10h

Durations consist of a number and duration unit. Supported duration units are:

• s - Seconds
• m - Minutes
• h - Hours
• d - Days
• w - Weeks
• M - Months
• y - Years

Using these durations a query to get the last week’s data could be as follows:

between now() - 1w and now()

Or midnight a week ago to midnight today:

between day() - 1w and day()

Or if you just wanted data for the week so far:

greater than week()

Or all data for the previous year:

between year() - 1y and year()

Or this year so far:

greater than year()

2.2 - Internal Links

Within Stroom, links can be created in dashboard tables or dashboard text panes that will direct Stroom to display an item in various ways.

Links are inserted in the form:

[Link Text](URL and parameters){Link Type}

In dashboard tables links can be inserted using the link() function or more specialised functions such as data() or stepping().

In dashboard text panes, links can be inserted into the HTML as link attributes on elements.

  <div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" link="[link](uuid=e177cf16-da6c-4c7d-a19c-09a201f5a2da&amp;params=user%3Duser1&amp;title=Details%20For%20user1){dashboard}">Details For user1</span>
  </div>

The link type can be one of the following:

• dialog : Display the content of a link URL within a stroom popup dialog.
• tab : Display the content of a link URL within a stroom tab.
• browser : Display the content of a link URL within a new browser tab.
• dashboard : Used to launch a Stroom dashboard internally with parameters in the URL.
• stepping : Used to launch Stroom stepping internally with parameters in the URL.
• data : Used to show Stroom data internally with parameters in the URL.
• annotation : Used to show a Stroom annotation internally with parameters in the URL.

Dialog

Dialog links are used to embed any referenced URL in a Stroom popup Dialog. Dialog links look something like this in HTML:

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[Show](https://www.somehost.com/somepath){dialog|Embedded In Stroom}">
        Show In Stroom Dialog
    </span>
</div>

{dialog|Embedded In Stroom}

Tab

Tab links are similar to dialog links are used to embed any referenced URL in a Stroom tab. Tab links look something like this in HTML:

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[Show](https://www.somehost.com/somepath){tab|Embedded In Stroom}">
        Show In Stroom Tab
    </span>
</div>

{tab|Embedded In Stroom}

Browser

Browser links are used to open any referenced URL in a new browser tab. In most cases this is easily accomplished via a normal hyperlink but Stroom also provides a mechanism to do this as a link event so that dashboard tables are also able to open new browser tabs. This can be accomplished by using the link() table function. In a dashboard text pane the HTML could look like this:

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[Show](https://www.somehost.com/somepath){browser}">
        Show In Browser Tab
    </span>
</div>

Dashboard

In addition to viewing/embedding external URLs, Stroom links can be used to direct Stroom to show an internal item or feature. The dashboard link type allows Stroom to open a new tab and show a dashboard with the specified parameters.

The format for a dashboard link is as follows:

[Link Text](uuid=<UUID>&params=<PARAMS>&title=<CUSTOM_TITLE>){dashboard}

The parameters for dashboard links are:

• uuid - The UUID of the dashboard to open.
• params - A URL encoded list of params to supply to the dashboard, e.g. params=user%3Duser1.
• title - An optional URL encoded title to better identify the specific instance of the dashboard, e.g. title=Details%20For%20user1.

An example of this type of link in HTML:

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[link](uuid=e177cf16-da6c-4c7d-a19c-09a201f5a2da&amp;params=user%3Duser1&amp;title=Details%20For%20user1){dashboard}">
        Details For user1
    </span>
</div>

Data

A link can be created to open a sub-set of a source of data (i.e. part of a stream) for viewing. The data can either be opened in a popup dialog (dialog) or in another stroom tab (tab). It can also be display in preview form (with formatting and syntax highlighting) or unaltered source form.

The format for a data link is as follows:

[Link Text](id=<STREAM_ID>&partNo=<PART_NO>&recordNo=<RECORD_NO>&lineFrom=<LINE_FROM>&colFrom=<COL_FROM>&lineTo=<LINE_TO>&colTo=<COL_TO>&viewType=<VIEW_TYPE>&displayType=<DISPLAY_TYPE>){data}

Stroom deals in two main types of stream, segmented and non-segmented (see Streams). Data in a non-segmented (i.e. raw) stream is identified by an id, a partNo and optionally line and column positions to define the sub-set of that stream part to display. Data in a segmented (i.e. cooked) stream is identified by an id, a recordNo and optionally line and column positions to define the sub-set of that record (i.e. event) within that stream.

The parameters for data links are:

• id - The stream ID.
• partNo - The part number of the stream (one based). Always 1 for segmented (cooked) streams.
• recordNo - The record number within a segmented stream (optional). Not applicable for non-segmented streams so use null() instead.
• lineFrom - The line number of the start of the sub-set of data (optional, one based).
• colFrom - The column number of the start of the sub-set of data (optional, one based).
• lineTo - The line number of the end of the sub-set of data (optional, one based).
• colTo - The column number of the end of the sub-set of data (optional, one based).
• viewType - The type of view of the data (optional, defaults to preview):
  • preview : Display the data as a formatted preview of a limited portion of the data.
  • source : Display the un-formatted data in its original form with the ability to navigate around all of the data source.
• displayType - The way of displaying the data (optional, defaults to dialog):
  • dialog : Open as a modal popup dialog.
  • tab : Open as a top level tab within the Stroom browser tab.

In preview mode the line and column positions will limit the data displayed to the specified selection. In source mode the line and column positions define a highlight block of text within the part/record.

An example of this type of link in HTML:

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[link](id=1822&amp;partNo=1&amp;recordNo=1){data}">
        Show Source</span>
</div>

View Type

The additional parameter viewType can be used to switch the data view mode from preview (default) to source.

In preview mode the optional parameters lineFrom, colFrom, lineTo, colTo can be used to limit the portion of the data that is displayed.

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[link](id=1822&amp;partNo=1&amp;recordNo=1&amp;viewType=preview&amp;lineFrom=1&amp;colFrom=1&amp;lineTo=10&amp;colTo=8){data}">
        Show Source Preview
    </span>
</div>

In source mode the optional parameters lineFrom, colFrom, lineTo, colTo can be used to highlight a portion of the data that is displayed.

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[link](id=1822&amp;partNo=1&amp;recordNo=1&amp;viewType=source&amp;lineFrom=1&amp;colFrom=1&amp;lineTo=10&amp;colTo=8){data}">
        Show Source
    </span>
</div>

Display Type

Choose whether to display data in a dialog (default) or a Stroom tab.

Stepping

A stepping link can be used to launch the data stepping feature with the specified data. The format for a stepping link is as follows:

[Link Text](id=<STREAM_ID>&partNo=<PART_NO>&recordNo=<RECORD_NO>){stepping}

The parameters for stepping links are as follows:

• id - The id of the stream to step.
• partNo - The sub part no within the stream to step (usually 1).
• recordNo - The record or event number within the stream to step.

An example of this type of link in HTML:

<div style="padding: 5px;">
    <span style="text-decoration:underline;color:blue;cursor:pointer" 
          link="[link](id=1822&amp;partNo=1&amp;recordNo=1){stepping}">
        Step Source</span>
</div>

Annotation

A link can be used to edit or create annotations. To view or edit an existing annotation the id must be known or one can be found using a stream and event id. If all parameters are specified an annotation will either be created or edited depending on whether it exists or not. The format for an annotation link is as follows:

[Link Text](annotationId=<ANNOTATION_ID>&streamId=<STREAM_ID>&eventId=<EVENT_ID>&title=<TITLE>&subject=<SUBJECT>&status=<STATUS>&assignedTo=<ASSIGNED_TO>&comment=<COMMENT>){annotation}

The parameters for annotation links are as follows:

• annotationId - The optional existing id of an annotation if one already exists.
• streamId - An optional stream id to link to a newly created annotation, or used to lookup an existing annotation if no annotation id is provided.
• eventId - An optional event id to link to a newly created annotation, or used to lookup an existing annotation if no annotation id is provided.
• title - An optional default title to give the annotation if a new one is created.
• subject - An optional default subject to give the annotation if a new one is created.
• status - An optional default status to give the annotation if a new one is created.
• assignedTo - An optional initial assignedTo value to give the annotation if a new one is created.
• comment - An optional initial comment to give the annotation if a new one is created.

2.3 - Direct URLs

It is possible to navigate directly to a specific Stroom dashboard using a direct URL. This can be useful when you have a dashboard that needs to be viewed by users that would otherwise not be using the Stroom user interface.

URL Format

The format for the URL is as follows:

https://<HOST>/stroom/dashboard?type=Dashboard&uuid=<DASHBOARD UUID>[&title=<DASHBOARD TITLE>][&params=<DASHBOARD PARAMETERS>]

Example:

https://localhost/stroom/dashboard?type=Dashboard&uuid=c7c6b03c-5d47-4b8b-b84e-e4dfc6c84a09&title=My%20Dash&params=userId%3DFred%20Bloggs

Host and Path

The host and path are typically https://<HOST>/stroom/dashboard where <HOST> is the hostname/IP for Stroom.

type

type is a required parameter and must always be Dashboard since we are opening a dashboard.

uuid

uuid is a required parameter where <DASHBOARD UUID> is the UUID for the dashboard you want a direct URL to, e.g. uuid=c7c6b03c-5d47-4b8b-b84e-e4dfc6c84a09

The UUID for the dashboard that you want to link to can be found by right clicking on the dashboard icon in the explorer tree and selecting Info.

The Info dialog will display something like this and the UUID can be copied from it:

DB ID: 4
UUID: c7c6b03c-5d47-4b8b-b84e-e4dfc6c84a09
Type: Dashboard
Name: Stroom Family App Events Dashboard
Created By: INTERNAL
Created On: 2018-12-10T06:33:03.275Z
Updated By: admin
Updated On: 2018-12-10T07:47:06.841Z

title (Optional)

title is an optional URL parameter where <DASHBOARD TITLE> allows the specification of a specific title for the opened dashboard instead of the default dashboard name.

The inclusion of ${name} in the title allows the default dashboard name to be used and appended with other values, e.g. 'title=${name}%20-%20' + param.name

params (Optional)

params is an optional URL parameter where <DASHBOARD PARAMETERS> includes any parameters that have been defined for the dashboard in any of the expressions, e.g. params=userId%3DFred%20Bloggs

Permissions

In order for a user to view a dashboard they will need the necessary permission on the various entities that make up the dashboard.

For a Lucene index query and associated table the following permissions will be required:

• Read permission on the Dashboard entity.
• Use permission on any Index entities being queried in the dashboard.
• Use permission on any Pipeline entities set as search extraction Pipelines in any of the dashboard’s tables.
• Use permission on any XSLT entities used by the above search extraction Pipeline entities.
• Use permission on any ancestor pipelines of any of the above search extraction Pipeline entities (if applicable).
• Use permission on any Feed entities that you want the user to be able to see data for.

For a SQL Statistics query and associated table the following permissions will be required:

• Read permission on the Dashboard entity.
• Use permission on the StatisticStore entity being queried.

For a visualisation the following permissions will be required:

• Read permission on any Visualisation entities used in the dashboard.
• Read permission on any Script entities used by the above Visualisation entities.
• Read permission on any Script entities used by the above Script entities.

3 - Query

3.1 - Stroom Query Language

Query Format

Stroom Query Language (StroomQL) is a text based replacement for the existing Dashboard query builder and allows you to express the same queries in text form as well as providing additional functionality. It is currently used on the Query entity as the means of defining a query.

The following shows the supported syntax for a StroomQL query.

from <DATA_SOURCE>
where <FIELD> <CONDITION> <VALUE> [and|or|not]
[and|or|not]
[window] <TIME_FIELD> by <WINDOW_SIZE> [advance <ADVANCE_WINDOW_SIZE>]
[filter] <FIELD> <CONDITION> <VALUE> [and|or|not]
[and|or|not]
[eval...] <FIELD> = <EXPRESSION>
[having] <FIELD> <CONDITION> <VALUE> [and|or|not]
[group by] <FIELD>
[sort by] <FIELD> [desc|asc] // asc by default
[limit] <MAX_ROWS> 
select <FIELD> [as <COLUMN NAME>], ...
[show as] <VIS_NAME> (<VIS_CONTROL_ID_1> = <COLUMN_1>, <VIS_CONTROL_ID_2> = <COLUMN_2>)

Fields

Fields are the fields in a data source. Fields are case-sensitive.

If the field name contains white space then it must be surround by braces and preceded by a dollar sign, e.g ${Create Time}.

If the field name does not contain spaces it can be written with or without the braces, e.g. Status or ${Status}.

Fields can added to the query text in one of three ways:

• Directly typing the field name (with braces as required).
• Double clicking the field name in the Field picker in the left hand pane. Field names with spaces will be pasted in with braces.
• Using code completion. In the query editor hit Ctrl ^ + Space ␣ to bring up a list of context aware completion terms, e.g. field names, then hit tab to insert it. You could also type a few characters from the name before hitting Ctrl ^ + Space ␣ to pre-filter the list. Field names with spaces will be pasted in with braces.

Keywords

Keywords are the reserved words that define the structure of the query, e.g. from, select, where. Unlike fields, they are case-insensitive.

From

The first part of a StroomQL expression is the from clause that defines the single data source to query. All queries must include the from clause.

Select the data source to query, e.g.

from my_source

If the name of the data source contains white space then it must be quoted using " double quotes, e.g.

from "my source"

Where

Use where to construct query criteria, e.g.

where feed = "my feed"

Add boolean logic with and, or and not to build complex criteria, e.g.

where feed = "my feed"
or feed = "other feed"

Use brackets to group logical sub expressions, e.g.

where user = "bob"
and (feed = "my feed" or feed = "other feed")

Conditions

Supported conditions are:

• = - Equals.
• != - Not equals.
• > - Greater than.
• >= - Greater than or equal to.
• < - Less than.
• <= - Less than or equal to.
• is null - The value is null.
• is not null - The value is not null.
• in - The value is in a list of allowed values.
  e.g. StreamId in (1001, 1002, 2009)
  or Feed in ("FEED_X", "FEED_Y").
• in dictionary - The value is in a list of allowed values that are contained in a Dictionary .
  e.g. Feed in dictionary "My Dict" (using the dictionary’s unique name)
  or Feed in dictionary "fb7a8cea-e6b4-4d94-8f7e-47ff3b3c7711" (using the dictionary’s UUID ).

And|Or|Not

Logical operators to add to where and filter clauses.

Bracket Groups

You can force evaluation of items in a specific order using bracketed groups.

and X = 5 OR (name = foo and surname = bar)

Window

window <TIME_FIELD> by <WINDOW_SIZE> [advance <ADVANCE_WINDOW_SIZE>]

Windowing groups data by a specified window size applied to a time field. A window inserts additional rows for future periods so that rows for future periods contain count columns for previous periods.

Specify the field to window by and a duration. Durations are specified in simple terms e.g. 1d, 2w etc.

By default, a window will insert a count into the next period row. This is because by default we advance by the specified window size. If you wish to advance by a different duration you can specify the advance amount which will insert counts into multiple future rows.

Filter

Use filter to filter values that have not been indexed during search retrieval. This is used the same way as the where clause but applies to data after being retrieved from the index, e.g.

filter obscure_field = "some value"

Add boolean logic with and, or and not to build complex criteria as supported by the where clause. Use brackets to group logical sub expressions as supported by the where clause.

Eval

Use eval to assign the value returned from an Expression Function to a named variable, e.g.

eval my_count = count()

Here the result of the count() function is being stored in a variable called my_count. Functions can be nested and applied to variables, e.g.

eval new_name = concat(
  substring(name, 3, 5),
  substring(name, 8, 9))

Note that all fields in the data source selected using from will be available as variables by default.

Multiple eval statements can also be used to breakup complex function expressions and make it easier to comment out individual evaluations, e.g.

eval name_prefix = substring(name, 3, 5)
eval name_suffix = substring(name, 8, 9)
eval new_name = concat(
  name_prefix,
  name_suffix)

Variables can be reused, e.g.

eval name_prefix = substring(name, 3, 5)
eval new_name = substring(name, 8, 9)
eval new_name = concat(
  name_prefix,
  new_name)

In this example, the second assignment of new_name will override the value initially assigned to it. Note that when reusing a variable name, the assignment can depend on the previous value assigned to that variable.

Add boolean logic with and, or and not to build complex criteria, e.g.

where feed = "my feed" or feed = "other feed"

Use brackets to group logical sub expressions, e.g.

where user = "bob" and (feed = "my feed" or feed = "other feed")

Having

A post aggregate filter that is applied at query time to return only rows that match the having conditions.

having count > 3

Group By

Use to group by columns, e.g.

group by feed

You can group across multiple columns, e.g.

group by feed, name

You can create nested groups, e.g.

group by feed
group by name

Sort By

Use to sort by columns, e.g.

sort by feed

You can sort across multiple columns, e.g.

sort by feed, name

You can change the sort direction, e.g.

sort by feed asc

Or

sort by feed desc

Limit

Limit the number of results, e.g.

limit 10

Select

The select keyword is used to define the fields that will be selected out of the data source (and any eval’d fields) for display in the table output.

select feed, name

You can optionally rename the fields so that they appear in the table with more human friendly names.

select feed as 'my feed column',
  name as 'my name column'

Show

The show keyword is used to tell StroomQL how to show the data resulting from the select. A Stroom visualisation can be specified and then passed column values from the select for the visualisation control properties.

show LineChart(x = EventTime, y = count)
show Doughnut(names = Feed, values = count)

For visualisations that contain spaces in their names it is necessary to use quotes, e.g.

show "My Visualisation" (x = EventTime, y = count)

Comments

Single Line

StroomQL supports single line comments using //. For example:

from "index_view" // view
where EventTime > now() - 1227d
// and StreamId = 1210
select StreamId as "Stream Id", EventTime as "Event Time"

Multi Line

Multiple lines can be commented by surrounding sections with /* and */. For example:

from "index_view" // view
where EventTime > now() - 1227d
/*
eval FirstName = lowerCase(substringBefore(UserId, '.'))
eval FirstName = any(FirstName)
*/
select StreamId as "Stream Id", EventTime as "Event Time"

Examples

The following are various example queries.

// add a where
from "index_view" // view
where EventTime > now() - 1227d
// and StreamId = 1210
eval UserId = any(upperCase(UserId))
eval FirstName = lowerCase(substringBefore(UserId, '.'))
eval FirstName = any(FirstName)
eval Sl = stringLength(FirstName)
eval count = count()
group by StreamId
sort by Sl desc
select Sl, StreamId as "Stream Id", EventId as "Event Id", EventTime as "Event Time", UserId as "User Id", FirstName, count
limit 10

from "index_view" // view
// add a where
where EventTime > now() - 1227d
// and StreamId = 1210
eval UserId = any(upperCase(UserId))
eval FirstName = lowerCase(substringBefore(UserId, '.'))
eval FirstName = any(FirstName)
eval Sl = stringLength(FirstName)
eval count = count()
group by StreamId
sort by Sl desc
select Sl, StreamId as "Stream Id", EventId as "Event Id", EventTime as "Event Time", UserId as "User Id", FirstName, count
limit 10

from "index_view" // view
// add a where
where EventTime > now() - 1227d
// and StreamId = 1210
eval UserId = any(upperCase(UserId))
eval FirstName = lowerCase(substringBefore(UserId, '.'))
eval FirstName = any(FirstName)
eval Sl = stringLength(FirstName)
// eval count = count()
// group by StreamId
// sort by Sl desc
select StreamId as "Stream Id", EventId as "Event Id"
// limit 10

from "index_view" // view
// add a where
where EventTime > now() - 1227d
// and StreamId = 1210
eval UserId = any(upperCase(UserId))
eval FirstName = lowerCase(substringBefore(UserId, '.'))
eval FirstName = any(FirstName)
eval Sl = stringLength(FirstName)
eval count = count()
group by StreamId
sort by Sl desc
select Sl, StreamId as "Stream Id", EventId as "Event Id", EventTime as "Event Time", UserId as "User Id", FirstName, count
limit 10

Help Pane

The left hand pane of the Query editor provides help for building a StroomQL query. It contains the following items:

• Data Sources - The list of data sources (visible to the user) that can be queried.
• Structure - The list of keywords available to use, e.g. select.
• Annotation Fields - The list of special fields for accessing data from Annotations linked to the data being queried. The fields list will only be available once a complete from ... clause has been added that uses a data source that supports Annotations, e.g. an Index.
• Fields - The list of fields that can be used in the Query. The fields list will only be available once a complete from ... clause has been added.
• Functions - The list of Expression Functions that can be used.
• Visualisations - The list of Visualisation documents that can be included in the Query .
• Dictionaries - The list of Dictionary documents that can be used in in dictionary terms.

Clicking on an item will show some detailed help about that item in the bottom of the pane.

Double clicking on the item will insert it into the query editor. It will be inserted with double quotes or braces as appropriate to the item being inserted.

Code Completion

The StroomQL editor benefits from code completion to speed up the writing of queries.

Pressing Ctrl ^ , Space ␣ in the query editor will bring up a context aware context menu listing items that can be inserted into the query, e.g. fields, functions, keywords, dictionaries, data sources, etc.

If you type some letters of the item you want, e.g. sub then Ctrl ^ , Space ␣ , it will bring up a list of items that contain the letters sub in that order, e.g. substring(..), isDouble(..), etc.

You can either use the cursor keys to scroll up/down the list or continue typing letters to further refine the filtering of the list. Hit Enter ↵ or Tab ↹ to insert the item into the editor.

The context menu also includes completion snippets.

The context menu also shows some more detailed help, e.g. to describe the argument to functions.

Functions

Expression Functions are inserted with tab stops to enable fast population of the function arguments. For example:

1. Type sub then hit Ctrl ^ , Space ␣ .
2. Select substring(..) from the list and hit Tab ↹ .
   substring(input, startIndex, endIndex) is inserted, with input highlighted.
3. Type Feed to replace input with Feed, then hit Tab ↹ .
   substring(Feed, startIndex, endIndex) is displayed, with startIndex highlighted.
4. Type 0 to replace startIndex with 0, then hit Tab ↹ .
   substring(Feed, 0, endIndex) is displayed, with endIndex highlighted.
5. Type 5 to replace endIndex with 5, then hit Tab ↹ .
   substring(Feed, 0, 5) is displayed, with the cursor now positioned after the closing bracket.

4 - Analytic Rules

An Analytic Rule runs a query over your data and turns each row the query returns into a detection. Detections are then delivered to one or more destinations, either written to a Feed as XML or sent to people by email.

A rule is the combination of four things, each of which has its own tab on the rule.

• The query that decides what counts as a detection.
• The processing type, which decides when and how the query is run.
• The execution settings, which for a scheduled rule decide when it runs and over what period.
• The notifications, which decide where detections are delivered.

If you want to run a query on a schedule and send the results to someone as a file rather than as detections, use a Report instead. Reports and Analytic Rules share most of their configuration, so much of this section applies to both.

Processing Types

The Processing Type is set on the rule’s Execution tab and decides how the query is run. It is the most significant choice you make about a rule, because it determines what the rest of the rule’s configuration means.

Changing the processing type changes which tabs the rule shows, because some settings only apply to one type.

Scheduled Query

A Scheduled Query rule runs its query on a schedule, for example every hour or at 03:00 each day. Each run covers a window of data, and the rule keeps track of which windows it has already covered so that it can work through history without gaps or repeats.

This is the type to use for most rules. It is also the only type available to Reports.

Streaming

A Streaming rule is run by a Processor filter , in the same way as a translation pipeline. Each stream that matches the filter is passed through the rule as it is processed, so detections are raised without waiting for a schedule to come round.

Table Builder

Table Builder is an experimental feature and should not be used.

Anatomy of a Rule

The tabs shown on an Analytic Rule depend on its processing type.

The content of the Documentation tab is not just for readers. It is also used as the detailedDescription of the detections the rule raises, so it is worth writing something that will make sense to whoever receives the detection. This can be turned off per rule with Include Rule Documentation on the Settings tab.

Jobs

Analytic Rules are run by background jobs, all of which are disabled by default. A newly created rule will do nothing at all until the job for its processing type has been enabled in

Streaming rules are run by the normal stream processing jobs rather than by a job of their own.

The job frequency controls how often Stroom looks for schedules that are due, not how often a rule runs. A rule scheduled to run every ten minutes will not do so if the job that looks for due schedules only runs hourly.

Configuration

Some rule behaviour is set by system properties rather than on the rule itself.

4.1 - Rule Queries

The Query tab holds the StroomQl query that defines the rule. It is the same query editor used by the Query document, so you can write a query, run it and inspect the results while you are developing the rule.

Every row the query returns becomes one detection. This is the single most important thing to understand about a rule. A query that returns a million rows will raise a million detections, so it is worth running the query and looking at the row count before enabling the rule.

Choosing a Data Source

A rule query can use any data source that a Query document can use, but the choice interacts with the processing type.

• A Scheduled Query rule can query anything, including Searchables and Lucene indexes.
• A Streaming rule must query a View , because the View’s filter is what decides which streams are fed through the rule.

Time Ranges and Relative Times

A rule that is going to run repeatedly should express its time range relative to when it runs, not as absolute dates.

When a scheduled rule runs, Stroom sets the reference time for the query to the rule’s effective execution time rather than to the current clock time. Every relative date expression in the query and in the time range is then resolved against that effective time.

This is what makes it possible for a rule to work through history. A rule whose query says where EventTime >= day() - 1d will, when it runs for an effective time of last Tuesday, select last Monday’s data. The same query run for an effective time of today selects yesterday’s data.

Columns

The columns your query selects become the content of each detection.

Every column is added to the detection as a name/value pair, using the column’s name as the key, and is available to email templates through the values dictionary. Two column names are treated specially.

Including StreamId and EventId in the query is what allows a detection to link back to the Event that caused it. Without them the detection still carries all its other values, but there is nothing to click through to.

Table Preferences

Some things about a result table cannot be expressed in StroomQl , such as which columns are hidden, how values are formatted and how rows are sorted. These are set by interacting with the results table in the UI and are stored on the rule alongside the query.

For an Analytic Rule these preferences affect only what you see while developing the query. For a Report they also affect the file that is produced, because the report is written from the same table.

Parameters

A rule can define parameters in the same way as a Query document, and refer to them in the query. Parameters are stored on the rule, so a scheduled rule always runs with the values held against it.

4.2 - Rule Settings

The Settings tab holds the settings that describe the rule itself, rather than its query, its schedule or the notifications it sends.

Level and Status

Neither is mandatory. A rule that sets neither produces detections without them, which is how every rule created before these settings existed behaves.

Both are written to every detection the rule produces, whatever its processing type, and both are available to notification email templates as {{ level }} and {{ status }}.

Level describes how urgent a detection from this rule is, so that whoever receives it can prioritise.

Status describes how much the rule can be trusted, which tells an analyst how much weight to give a detection and how many false positives to expect.

Include Rule Documentation

The content of the rule’s Documentation tab is written to each detection as detailedDescription, which means it leaves Stroom with the detection, for example by email. Untick this where the documentation is for whoever maintains the rule rather than for whoever receives its detections.

Feed for Errors

Reports

A Report has a Settings tab of its own, holding Feed For Errors along with the settings that decide what kind of file it produces.

A report has no Level, Status or Include Rule Documentation, because it delivers a file rather than detections.

4.3 - Rule Execution

The Execution tab sets the rule’s processing type, and for a Scheduled Query rule it is where you define when the rule runs.

A scheduled rule does not have a single schedule field. Instead it has a list of execution schedules, each of which runs the rule independently. The tab is split, with the schedules in the upper pane and the history of what those schedules have done in the lower one.

Everything on this page applies equally to Reports , which use the same execution machinery.

Execution Schedules

Use the button above the schedule list to add a schedule.

Having more than one schedule on a rule is useful when you want the same query run over different periods. A common pattern is a frequent schedule that keeps up with new data, plus a second schedule with a start and end time that is used once to work back over history.

Run as User

The query runs with the permissions of the Run As User, not those of whoever created the rule. If that user cannot see some of the data, the rule will silently detect nothing in it.

How Time Works

Each run of a schedule has two different times associated with it, and telling them apart is the key to understanding scheduled rules.

For a rule that is keeping up with new data the two are almost the same. They diverge whenever a rule is catching up, because a rule that is behind will run now for an effective time in the past.

The effective time of the first run comes from the schedule’s Start Time, or from the next occurrence of the schedule if no start time is set. After each successful run Stroom records where it has got to, and the next run picks up from there.

Contiguous Execution

Whether a schedule catches up or skips ahead is decided by whether it is contiguous.

• A contiguous schedule takes its next effective time from the last effective time. If the rule has not run for a week, it will work forward through that week one run at a time until it catches up. No window of data is missed.
• A non-contiguous schedule takes its next effective time from the current time. If the rule has not run for a week, that week is skipped.

Contiguous execution is what you want for a rule that must not miss anything. Be aware that it means a rule which has been disabled for a long time, or whose start time is set well in the past, will have a lot of catching up to do when it is enabled.

Replaying an Execution

Selecting a row in the execution history and clicking Replay Execution sets up a re-run of that one execution.

Replaying does not run anything immediately. It adds a new execution schedule, named after the original with (replay) appended, whose start and end times are both the effective execution time of the row you selected. The new schedule is created disabled, so nothing happens until you enable it.

This is deliberate, as it gives you the chance to check the bounds before the rule runs again. Once enabled, the schedule runs the rule once for that effective time and then has nothing further to do.

Replay works on a single history row at a time. To re-run a range of executions, add an ordinary schedule with the start and end times you want instead.

Execution History

The lower pane lists what each schedule has done.

History is kept for the period set by the stroom.analytics.executionHistoryRetention property and is deleted by the Analytic Execution History Retention job.

The Execution Schedule Manager

The rule’s Execution tab only shows that rule’s schedules.

The list identifies each schedule by the document it belongs to as well as by its own name, and can be filtered.

Run Schedules Now and Batch Edit Schedules can be applied either to the schedules you have selected or to everything matching the current filter.

Error Feed

Errors raised while a rule is running are written as Error streams to the rule’s error feed.

The feed is set by Feed For Errors on the Settings tab rather than on this one. Where the rule does not name one, the feed configured in stroom.ui.analyticUiDefaultConfig.defaultErrorFeed is used, and a run for which neither is set fails.

A run can fail before there is anywhere to write to, for example when neither the rule nor the system configuration names an error feed. Failures of that kind are recorded against the execution history instead, which is why it is worth looking at both.

4.4 - Rule Notifications

The Notifications tab decides what happens to the detections a rule raises. Settings that describe the rule as a whole, such as what its detections contain, are on the Settings tab instead.

The tab is a list of notifications. A rule can have any number of notifications and each one is delivered independently. A rule that both writes detections to a feed for later analysis and emails a few people about them has two notifications, not one.

Everything on this page applies to Reports as well, except that a report delivers a file rather than a detection. The differences are covered in Report Delivery.

Stream Destinations

A Stream notification writes detections into a Feed as XML conforming to the detection:1 XML Schema . This is the right choice when detections are themselves data, to be indexed, searched, or fed into another rule.

Use Source Feed If Possible is useful for a streaming rule that runs across many feeds and whose detections are best kept alongside the data that produced them.

Email Destinations

An Email notification sends each detection to people as an email.

Each field accepts more than one address.

Templates

The subject and body are Jinja templates rather than fixed text, so that each email can describe the detection that triggered it.

The values from the detection are put into the template context before the template is rendered, so {{ detectTime }} renders when the detection happened and values.SourceIp renders the value of the query’s SourceIp column.

If the rendered body looks like HTML it is sent as an HTML email, otherwise it is sent as plain text.

Testing

Two buttons let you check a template without waiting for a real detection.

• Test Template renders the template against an example detection and shows you the result, including any errors in the template.
• Send Test Email sends that example detection to the configured recipients, which also proves the SMTP configuration works.

Limiting Notifications

A rule that suddenly matches far more data than expected can send a very large number of emails. The limit settings exist to bound that.

Once Maximum Notifications have been sent the notification switches itself off and nothing further is delivered through it. It comes back on when Resume Notifications After has elapsed since the last notification was sent, at which point the count starts again from zero.

The count is held per notification and is not persisted, so restarting the node resets it.

4.5 - Detections

A detection is what an Analytic Rule produces. One is raised for each row the rule’s query returns, and it is the detection, rather than the row, that is delivered to the rule’s notifications.

Detections written to a Feed are XML in the detection:1 namespace, so they can be indexed and searched like any other data in Stroom. Detections sent by email are rendered through a template that has access to the same fields.

How a Detection is Built

Most of a detection is filled in for you from the rule and from the run that raised it.

Because detailedDescription comes from the rule’s documentation, what you write there is delivered with the detections the rule raises. It is worth writing it for whoever receives the detection rather than for whoever maintains the rule.

Whether it is included is controlled by Include Rule Documentation on the Settings tab, which applies to every processing type. Where it is unticked, detailedDescription is left empty.

Values

Every column the query selects becomes an entry in values, keyed by the column name. In a feed these appear as <value name="..."> elements, and in an email template they are reachable through the values dictionary.

The two exceptions are StreamId and EventId. Rather than appearing in values, they are used to build a linked event, which records the Stream and Event the detection relates to. A detection whose query selects neither will have no linked events.

Fields a Rule Does Not Set

The detection:1 schema has several fields that an Analytic Rule never populates, because they only make sense for a detector that revises its own findings over time.

These exist because the same schema is used by detections produced outside Stroom, for example by an XSLT in a translation pipeline or by an external processing framework, which can set them.

Detections as a Data Source

Writing detections to a feed means they can be treated as data in their own right. Once indexed they can be searched from a Dashboard or Query, reported on, and used as the input to further rules.

A rule whose query runs over a feed of detections is a common way of spotting a pattern across detections that no single detection shows on its own.

4.6 - Duplicate Management

Some rules will detect the same thing over and over. A rule that runs hourly and looks for a misconfigured device will find that device every hour until someone fixes it, and nobody needs telling twenty four times a day.

Duplicate Management suppresses detections that match ones the rule has already raised. The tab is only shown for Scheduled Query rules.

This is different from limiting notifications, which bounds how many notifications a rule may send regardless of what they say. Duplicate management suppresses repeats while still delivering anything new.

Settings

The two switches are independent, and the store is used if either of them is set.

Setting Remember Notifications on its own is a useful way to see what a rule would suppress before committing to suppressing it.

The lower part of the tab lists what the rule has stored, which is how you check why something was or was not suppressed. It also lets you clear the store.

Choosing Columns

Where Choose Columns is not set, the columns used depend on whether the query groups its results.

• A query with grouped columns uses those grouped columns, and ignores the rest.
• A query with no grouping uses every column.

Using every column is often too strict, because a column that changes on every run will make every detection unique. A rule whose query selects a timestamp, or a count, or an event id, will never suppress anything unless the columns are narrowed down to the ones that identify the thing being detected.

Choose Columns is how you narrow them. For the misconfigured device example, choosing just the device name means the rule tells you about that device once rather than hourly, however much the other columns change.

Column names are case sensitive and must match the names in the query.

The Duplicate Check Store

Each rule has its own store, held on the processing node and configured by the stroom.analytics.duplicateCheckStore property.

The store is keyed on the rule, so it survives the rule being edited. It is deleted when the rule is deleted.

4.7 - Streaming Rules

A Streaming rule is run by a Processor filter rather than by a schedule. Each Stream that matches the filter is passed through the rule as it is processed, so a detection is raised without waiting for the next scheduled run.

Use this type where the delay imposed by a schedule is unacceptable. For most rules a Scheduled Query is the better choice, because it can look across a window of data rather than at one stream at a time.

Data Source

A streaming rule must query a View , and that View must specify an extraction pipeline.

The View is what makes streaming possible. Its filter determines which streams are selected for processing, and its extraction pipeline determines the fields the rule’s query can use.

A rule whose query names anything other than a View, or whose View has no pipeline, fails when it is processed rather than when it is saved. The error is reported against the rule, so a streaming rule that raises nothing at all is worth checking here first.

Processing

The Execution tab of a streaming rule shows the rule’s processors and filters, in the same form as the Processors tab of a pipeline.

When a filter is created for the rule, its expression is defaulted from the filter on the View the query uses. You can then narrow it further, for example to a subset of feeds or a range of stream creation times.

Because streaming rules use the normal stream processing machinery, they behave like any other processing task.

• They are picked up by the standard stream processor jobs, not by the Analytic Executor jobs.
• Their progress can be tracked, and they can be reprocessed, from the Processors screen.
• Their priority competes with other processing on the node.

Differences from a Scheduled Rule

A streaming rule has no execution schedules, and consequently no execution history, no effective execution time and no catch up behaviour. Relative date expressions in the query resolve against the time of processing.

It also has no Duplicate Management tab, so repeated detections must be controlled by limiting notifications instead.

Streaming rules are the only type that can use Use Source Feed If Possible on a stream notification, which writes each detection to the feed the source data came from rather than to the destination feed, see Stream Destinations.

4.8 - Table Builder Rules

A Table Builder rule builds and maintains its own table of data from the streams it processes, and raises detections from that table. The table is held in shards on the processing node, separately from the rest of Stroom’s data.

The rule’s Shards tab, which is only shown for this processing type, lists those shards and lets you look at what they contain.

Settings

5 - Reports

A Report runs a query on a schedule and turns the results into a file, which is then delivered to the people or the Feed you nominate.

Where an Analytic Rule turns each row of its query into a separate detection, a Report turns the whole result table into a single document. Use a Report when somebody wants a periodic summary of what the data shows, and an Analytic Rule when somebody needs telling about individual things as they are found.

How a Report Relates to an Analytic Rule

Reports and Analytic Rules are built on the same machinery and share most of their configuration. Anything documented for Analytic Rules applies to Reports unless stated otherwise here.

The Processing Type on a Report’s Execution tab offers only Scheduled Query. Reports are always run on a schedule, so there is no streaming or table builder equivalent. They also have no Duplicate Management tab, because a report is a periodic summary and is expected to repeat.

The Query

The Query tab works as it does on an Analytic Rule, with one important difference.

The table preferences you set by interacting with the results, such as hidden columns, value formats and sort order, are stored on the report and applied when the report is generated. What you see in the results table while developing the query is therefore what the recipient will get.

Relative date expressions resolve against the report’s effective execution time rather than the current clock time, which is what allows a report for last month to be produced correctly today.

Jobs

Reports are run by the Reports job, which is disabled by default. A report will not run until that job has been enabled in

The job controls how often Stroom looks for report schedules that are due, not how often a report is produced.

Configuration

Reports use the same stroom.analytics configuration as Analytic Rules, including the SMTP settings that email delivery depends on, see Email Setup.

The defaults offered in the UI for the processing node, error feed and destination feed come from stroom.ui.reportUiDefaultConfig rather than from the equivalent analytics property.

5.1 - Report Settings

The Settings tab controls what kind of file the report produces and what goes in it, and holds the feed that execution errors are written to.

An Analytic Rule has a Settings tab of its own, holding what the rule declares about itself. A report has none of those settings, because it delivers a file rather than detections.

File Type

Four formats are available.

Choose Excel or Markdown where a person will read the report, and CSV or TSV where something else will consume it. The Excel Info sheet is worth knowing about, because it is where the recipient can see which period the report actually covers.

Send Empty Reports

There is a real choice here. Delivering empty reports means the recipient knows the report ran and there was nothing to say, rather than being left to wonder whether it failed. Suppressing them avoids a stream of empty files for a report that is usually quiet.

Only emptiness suppresses delivery. A report that returned rows is always delivered however this is set, and a report that is suppressed is still recorded in the execution history as having run.

AI Summary

A report can ask a model to summarise the data it produced and deliver that summary with the report.

Where the summary ends up depends on the file type, since CSV and TSV cannot carry prose without breaking them for whatever reads them.

The summary is also available to email templates as aiSummary and is recorded as a ReportAiSummary entry in the stream meta where the report is delivered to a feed.

Feed for Errors

5.2 - Report Delivery

The Notifications tab of a Report works in the same way as it does for an Analytic Rule, with the same two destination types and the same limit settings. The difference is what gets delivered. A rule delivers a detection, whereas a report delivers the file it produced.

A report can have several notifications, so the same report can be emailed to a distribution list and written to a feed for retention at the same time.

Email Delivery

The report is sent as an attachment, with the subject and body rendered from the notification’s templates.

Where the report is a CSV or TSV and an AI summary was produced, the summary is attached as a second file rather than being packed into an archive, so the recipient does not have to unpack anything.

The file name is derived from the report name and the effective execution time, so a recipient who keeps several editions can tell them apart.

Template Context

Report email templates use the same Jinja syntax as rule detection templates but have a completely different set of variables available, because a report is not a detection.

aiSummary is always present so that a template using it renders whether or not a summary was produced.

Feed Delivery

A Stream notification writes the report into a Feed as a stream of type Report.

The stream carries the report file itself, unchanged, so anything already reading those streams is unaffected by settings such as the AI summary. The following entries are written to the stream Metadata .

Writing reports to a feed is how you retain a record of what was reported and when, independently of whoever received the email.

Limiting

The Limit Notifications, Maximum Notifications and Resume Notifications After settings behave exactly as they do for an Analytic Rule.

They are far less likely to matter for a report, because a report produces one file per run rather than one notification per matching row.

6 - Search Extraction

When indexing data it is possible to store (see Stored Fields all data in the index. This comes with a storage cost as the data is then held in two places; the event; and the index document.

Stroom has the capability of doing Search Extraction at query time. This involves combining the data stored in the index document with data extracted using a search extraction pipeline. Extracting data in this way is slower but reduces the data stored in the index, so it is a trade off between performance and storage space consumed.

Search Extraction relies on the StreamId and EventId being stored in the Index. Stroom can then use these two fields to locate the event in the stream store and process it with the search extraction pipeline.

7 - Dictionaries

Creating

Right click on a folder in the explorer tree that you want to create a dictionary in. Choose ‘New/Dictionary’ from the popup menu:

Call the dictionary something like ‘My Dictionary’ and click OK .

Now just add any search terms you want to the newly created dictionary and click .

You can add multiple terms.

• Terms on separate lines act as if they are part of an ‘OR’ expression when used in a search.

  apple
  banana
  orange
  

• Terms on a single line separated by spaces act as if they are part of an ‘AND’ expression when used in a search.

  apple,banana,orange
  

Using the Dictionary

To perform a search using your dictionary, just choose the newly created dictionary as part of your search expression:

TODO: Fix image