Search Query Syntax (Core Services)

The AFSearch based searches within the AF SDK use a query string to define the objects that will be returned by the search. This provides a flexible way to define the criteria used for the search. The syntax used for this query string is described in the Search Query Syntax section below.

Query Syntax

This is the definition of the syntax used when specifying the search criteria. Search Query syntax described in Extended Backus-Naur Form (EBNF)

Query             = QueryFilter { QueryFilter } ;

QueryFilter       = StringValue   (* Defaults to 'Name:=' ⁽¹⁾ *)
                  | "AllDescendants" EqualOperator BooleanValue
                  | "Analysis" EqualOperator StringValue
                  | "AnalysisName" EqualOperator StringValue
                  | "CanBeAcknowledged" EqualOperator BooleanValue
                  | "Category" EqualOperator StringValue
                  | "CategoryName" EqualOperator StringValue
                  | "Contact" EqualOperator StringValue
                  | "ContactName" EqualOperator StringValue
                  | "CreationDate" Operator TimeValue
                  | "Description" EqualOperator StringValue
                  | "Destination" EqualOperator StringValue
                  | "Duration" Operator TimeSpanValue
                  | "Element" OptionalNestedOrInOperator
                  | "ElementName" EqualOperator StringValue
                  | "ElementReferenceTemplate" EqualOperator StringValue
                  | "End" Operator TimeValue
                  | "EventFrame" NestedQuery
                  | "GroupID" EqualOperator IntegerValue
                  | "ID" EqualOrInOperator
                  | "InProgress" EqualOperator BooleanValue
                  | "IsAcknowledged" EqualOperator BooleanValue
                  | "IsAnnotated" EqualOperator BooleanValue
                  | "IsInternal" EqualOperator BooleanValue
                  | "ModifyDate" Operator TimeValue
                  | "Name" EqualOperator StringValue
                  | "Parent" OptionalNestedQuery
                  | "PlugIn" EqualOperator StringValue
                  | "PlugInName" EqualOperator StringValue
                  | "ReferenceType" EqualOperator StringValue
                  | "Root" EqualOperator StringValue
                  | "Sandbox" EqualOperator BooleanValue
                  | "Severity" Operator SeverityValue
                  | "SortField" Operator SortFieldValue
                  | "SortOrder" Operator SortOrderValue
                  | "Source" EqualOperator StringValue
                  | "Start" Operator TimeValue
                  | "Status" Operator StatusValue
                  | "Target" EqualOperator StringValue
                  | "TargetName" EqualOperator StringValue
                  | "Template" EqualOperator StringValue
                  | "TemplateName" EqualOperator StringValue
                  | "TimeContext" EqualOperator TimeValue
                  | "TimeContextEnd" EqualOperator TimeValue
                  | "Type" EqualOperator StringValue
                  | "Value" EqualOperator AttrValueFilter
                  | AttrValueFilter
                  ;

NestedQuery       = EqualOperator "{" Query "}" ;

OptionalNestedQuery
                  = EqualOperator StringValue
                  | NestedQuery
                  ;

OptionalNestedOrInOperator
                  = OptionalNestedQuery
                  | InOperator
                  ;

AttrValueFilter   = AttrPath Operator StringValue
                  | AttrPath InOperator
                  | AttrPath Operator StringValue AttrValueType
                  ;

AttrPath          = "'|" { QuotedEscapedChar | "''" } "'"
                  | ""|" { QuotedEscapedChar | """" } """
                  | "|" { EscapedChar }
                  ;

AttrValueType     = As Numeric
                  | As String
                  | As Guid
                  | As AFEnumerationSetName
                  ;

Operator          = EqualOperator | ":<>" | ":<" | ":<=" | ":>" | ":>=" ;

EqualOperator     = ":" | ":=" ;

InOperator        = ":IN(" StringValues ")"

EqualOrInOperator = EqualOperator StringValue | InOperator

SeverityValue     = "None"
                  | "Information"
                  | "Warning"
                  | "Minor"
                  | "Major"
                  | "Critical"
                  ;

SortFieldValue    = "ID"
                  | "Name"
                  | "Type"
                  | "StartTime"
                  | "EndTime"
                  ;

SortOrderValue    = "Ascending"
                  | "Asc"
                  | "Descending"
                  | "Desc"
                  ;

StatusValue       = "None"
                  | "NotReady"
                  | "Disabled"
                  | "Enabled"
                  | "Error"
                  ;

TimeValue         = "'" AFTimeString "'"
                  | """ AFTimeString """
                  | AFTimeString
                  ;

TimeSpanValue     = "'" AFTimeSpanString "'"
                  | """ AFTimeSpanString """
                  | AFTimeSpanString
                  ;

BooleanValue      = "'" Boolean "'"
                  | """ Boolean """
                  | Boolean
                  ;

IntegerValue      = "'" Integer "'"
                  | """ Integer """
                  | Integer
                  ;

StringValues      = StringValue { ";" StringValue } ;

StringValue       = "'" { QuotedEscapedChar | "''" } "'"
                  | """ { QuotedEscapedChar | """" } """
                  | { EscapedChar }
                  ;

QuotedEscapedChar = Char
                  | "\""      (* Escaped " character *)
                  | "\'"      (* Escaped ' character *)
                  | "\*"      (* Escaped * character *)
                  | "\?"      (* Escaped ? character *)
                  ;

EscapedChar       = NoWhiteSpaceChar
                  | "\" Char  (* The character is escaped *)
                  ;

Boolean           = "True" | "False" | "1" | "0" ;

Integer           = Digit { Digit } ;

Digit             = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

AFEnumSetName     = ? Any string that matches the name of an AFEnumerationSet ?

AFTimeString      = ? Any string that can be parsed by AFTime.Parse ?

AFTimeSpanString  = ? Any string that can be parsed by AFTimeSpan.Parse ?

NoWhiteSpaceChar  = ? Any printable character except whitespace characters ?

Char              = ? Any printable character ?

⁽¹⁾ If a specific filter name is not specified, then the filter will default to
     "Name" and the operator will be "=". When a filter name is specified, no whitespace
     is allowed between the filter name, the ":" separator, and the optional operator.
     If the operator is not specified, the default operator is "=".

String values for name filters can contain wildcard characters that are described in the Wildcard Characters section below. The Filters section below describes the filters that can be used in the query and the Operators table below describes the operators that can be used in the filter conditions. The Attribute Value Query section provides more information about searching by attribute values.

Time strings are evaluated in the client's local time unless qualified with time zone information. The time string will be parsed using the current culture. If parsing with the current culture fails, then it will attempt to resolve the time string using the invariant culture.

An empty string value should be used when searching for objects with a null value for the specified filter. For example, to find all objects without a template defined use Template:'' in the query.

Wildcard Characters

The string value of a filter can be enclosed in single quotes ('), double quotes ("), or without quotes. The filter string value can include regular characters and wildcard characters. Regular characters must match exactly the characters specified in the filter value. Wildcard characters can be matched with arbitrary fragments of the filter value. Wildcard characters can be escaped using the single backslash (\) character.

When the filter value is specified within either single or double quotes, the single backslash (\) character is treated as a literal character unless followed by a wildcard character, a single quote ('), or a double quote ("). When specified within quotes, two quote characters that match the starting quote character are treated as a single quote character (e.g. '' is treated as a one single quote character ' if the filter value starts with a single quote). When the filter value is specified without quotes, the backslash character is always used to escape the next character. Therefore you must use a double backslash (\\) to match a single backslash when not using quotes around the filter value.

The wildcard characters used in the string value of a filter have the following rules:

If an empty string is specified as part of a Name filter, then everything will be matched. Otherwise, an exact match on empty string or default value for the filter is performed if an empty string is specified.

If no wildcards, then an exact match on the filter string is performed.

Wildcard * can be placed anywhere in the filter string and matches zero or more characters.

Wildcard ? can be placed anywhere in the filter string and matches exactly one character.

One character in a set of characters are matched by placing them within [ ]. For example, a[bc] would match 'ab' or 'ac', but it would not match 'ad' or 'abd'.

One character in a set of characters are not matched by placing them within [! ]. For example, a[!bc] would match 'ad', but it would not match 'ab', 'ac', or 'abd'.

A character in a range of characters from first to last are matched using the following syntax: [first - last]. For example, a[a-c] would match 'aa', 'ab', or 'ac', but it would not match 'ad' or 'abc'.

Filters

Each filter condition is separated by whitespace and will be ANDed together to perform an AFSearch based search query that can be used to search for objects from the AF Server. For more information about the query filters, see the AFSearchFilter topic.

The following chart shows which filters are supported by each search class.

The Sandbox filter is not supported by the AFEventFrameSearch if specified with any of the following filters: Analysis, Element, ElementName, or ElementReferenceTemplate. For an AFElementSearch, the Sandbox filter is not supported if the AllDescendants filter is also enabled. The following table describes the dependencies between search filters.

Filter	Notes	Example
AllDescendants	If this filter is enabled and the Root filter is also specified, then the search will be slower because more than one level of the hierarchy must be checked. This filter is enabled by default, so it is recommended to disable this filter if the Root filter is also specified and you do not need to search the full hierarchy under the specified root object.	Root:Tank101 ReferenceType:TankReference
ReferenceType	Finds objects with the specified reference type between the Root object and the found object. If the Root filter is not specified, then finds objects with the specified reference type between the found object and any parent object including the AFDatabase.	Root:Tank101 ReferenceType:TankReference
Value	When using versions of PI AF Server below PI AF Server 2018 (2.10.0.8268), a value filter requires that a Template filter must first be specified that can be used to find the AFAttributeTemplate specified in the value filter.	Template:MyTemplate#1 |Attr#1|Child#2:<=50

Operators

Search operators specify how the filter value is to be compared with the object's value for the filter. For more information about the search operators, see the AFSearchOperator topic.

The following table lists the operators used in the filter condition.

Operator	Description	Example
=	The Equal operator.	Name:Tank* or Name:=Tank*
<>	The NotEqual operator.	"|Attr#1":<>50
<	The LessThan operator.	"|Attr#1":<50
<=	The LessThanOrEqual operator.	"|Attr#1":<=50
>	The GreaterThan operator.	"|Attr#1":>50
>=	The GreaterThanOrEqual operator.	"|Attr#1":>=50
IN()	The In operator.	"|Attr#1":IN(50;100;150) or Element:IN('Meter'; 'Tank')

Attribute Value Query

On PI AF Server versions below PI AF Server 2018 (2.10.0.8268), an attribute value query requires that a Template filter must first be specified that can be used to find the AFAttributeTemplate specified in the value filter.

When using attribute value queries with a Template filter, search performance can be improved by marking the AFAttributeTemplate as being indexed by setting the IsIndexed property. The Type property of the attribute template determines the type of value to be queried, therefore the type must be defined and not set to a type of object. Any AFAttributeTemplate with a DefaultUOM specified must be of type Single or Double. If a DefaultUOM is not specified in the template for one of these types, then the search will be performed using the specified attribute value as being in the canonical units-of-measure which could cause unexpected results to be returned. The following table shows which AFSearchOperator is supported for each type of value being queried:

Type	Equal	NotEqual	LessThan	LessThanOrEqual	GreaterThan	GreaterThanOrEqual	In
Boolean	Yes	Yes	No	No	No	No	Yes
UInt64	Yes	Yes	No	No	No	No	Yes
String	Yes	Yes	No	No	No	No	Yes
Guid	Yes	Yes	No	No	No	No	Yes
Single	Yes	Yes	Yes	Yes	Yes	Yes	No
Double	Yes	Yes	Yes	Yes	Yes	Yes	No
All Others	Yes	Yes	Yes	Yes	Yes	Yes	Yes

When the Type property of the AFAttributeTemplate is String, then the following restrictions are placed on the string length of the attribute value used in the query:

IsIndexed	Operator	Length Limit
True	Equal or NotEqual	40 characters
True	In	40 characters
False	Equal or NotEqual	No limit
False	In	4096 characters when using PI AF Server 2.6 or greater; otherwise 40 characters

Query Syntax Examples

Below are some example queries:

Get all Event Frames with the name that begins with Tank.

query=Tank*

query=name:Tank*

query=Name:=Tank*

Get all Event Frames with the name that do not begin with Tank and have the Template name of MyTemplate#1. Note URL encoding.

query=Name:<>Tank* Template:MyTemplate%231

Get all Event Frames with the name that do not begin with Tank and no Template.

query=Name:<>Tank* Template:""

Get all Event Frames with the name that do not begin with Tank and have a start time less than 1 week ago and have an end time that is greater or equal to now.

query=Name:<>Tank* End:>=* Start:<*-1w 

Get all Event Frames with the name that have Tank in the name and have a start time greater than or equal to three days ago and that are in progress.

query=Name:="*Tank*" Start:>*-3Days InProgress:True

Search Modes

The various Search Modes can be recreated with the search query syntax as follows:

StartInclusive

query=Start:>=*-1w Start:<*

EndInclusive

query=End:>*-1w End:<=*

Inclusive

query=Start:>=*-1w End:<=*

Overlapped

query=Start:<* End:>*-1w

InProgress

query=Start:>=*-1w Start:<* InProgress:true

The following search modes apply only to event frame searches:

BackwardFromStartTime

query=Start:<*-1w SortField:StartTime SortOrder:DESC

ForwardFromStartTime

query=Start:>=*-1w SortField:StartTime SortOrder:ASC

BackwardFromEndTime

query=End:<=*-1w SortField:EndTime SortOrder:DESC

ForwardFromEndTime

query=End:>=*-1w SortField:EndTime SortOrder:ASC

BackwardInProgress

query=Start:<*-1w InProgress:true SortField:StartTime SortOrder:DESC

ForwardInProgress

query=Start:>=*-1w InProgress:true SortField:StartTime SortOrder:ASC

For More Information

For more information, see the AF SDK Tech Support article on Search Query Syntax