PIPoint Search Query Syntax (Core Services)

PIPoint Search searches within data servers using 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 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               = AndCondition { "OR" AndCondition } ;

AndCondition        = QueryFilter { AndOperator QueryFilter }
                    | "(" QueryFilter { AndOperator QueryFilter } ")"
                    ;

QueryFilter         = StringValue    (* Defaults to 'Tag:=' ⁽¹⁾ *)
                    | PIPOINTATTRIBUTE Operator StringValue ⁽²⁾
                    | PIPointValueFilter
                    ;

PIPointValueFilter  = "Value" Operator StringValue
                    | "TimeStamp" Operator TimeValue
                    | "Substituted" EqualOperator BooleanValue
                    | "Questionable" EqualOperator BooleanValue
                    | "Annotated" EqualOperator BooleanValue
                    | "IsGood" EqualOperator BooleanValue
                    ;

AndOperator         = "AND" | WHITESPACE ;

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

EqualOperator       = ":" | ":=" ;

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

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

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

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

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

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

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

NoWhiteSpaceChar    = ? Any printable character except whitespace characters ?

Char                = ? Any printable character ?



1.) If a specific filter name is not specified, then the filter will default to the
     "Tag" filter 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 "=".
2.) If the type of a PIPOINTATTRIBUTE is DateTime, then the "TimeValue"
     format is supported for the filter value.

Wildcard Characters

The string value of a filter can be enclosed in single quotes ('), double quotes ("), or without quotes. Quotations are required if non-escaped white space or quotation marks are desired within the filter string. 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.

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 supported wild card characters are "*" to match any zero or more characters and "?" to match a single character. These characters cannot be escaped using the backslash ("\") character and will always be used as wild card characters within the query value.

Operators

Search operators specify how the filter value is to be compared with the point'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 AND condition.

Operator	Description	Example
=	The Equal operator.	Tag:Tank* or Tag:=Tank*
<>	The NotEqual operator.	PointType:<>Int32
<	The LessThan operator.	Value:<100
<=	The LessThanOrEqual operator.	Tag:<=Tank
>	The GreaterThan operator.	Tag:>Tank
>=	The GreaterThanOrEqual operator.	Tag:>=Tank

Caution

Queries with OR condition are not supported for PIPoint value query.

Query Syntax Examples

Below are some example PIPoint queries:

query=sin*

query=name:sin*

query=tag:=sin*

tag:<>sin* DataType:Float

tag:<>sin* AND PointType:Float

step:0 AND PointSource:L

(tag:<>sin* AND PointType:Float64) OR (tag:="*Tank*" AND DataType:=Int32)

Below are some example of PIPoint value queries, where they can be combined with attribute queries:

Value:=1

This filter would apply to PIPoint value of Numeric, String, and Digital types.

Value:=Auto

This filter would apply to PIPoint value of String and Digital types.

Value:=abc*

This filter would apply to PIPoint value of String type.

Value:="Pt Created"

This filter would apply to PIPoint value of String and PI System Digital State types.

Value:=253 AND IsGood:false

This filter is an alternative to filtering PIPoint value of "Pt Created" PI System Digital State.

Value:=t

This filter would apply to PIPoint value of String and Timestamp types.

tag:sin* AND Value:>10

PointType:Int32 AND Value:>10

PointType:Float32 AND Value:>10

DataType:Float64 AND Value:>1.5

PointType:Blob AND Questionable:true AND TimeStamp:<*

PointType:Blob AND Value:="Pt Created"

PointType:Blob AND Value:=253 AND IsGood:false

PointSource:L AND Annotated:1 AND TimeStamp:t

IsGood:false AND TimeStamp:<"1/5/2017 1:00:00 AM"

ChangeDate:>"2/5/2017 2:00:00 AM" AND Step:0 AND IsGood:1

CreationDate:>y-1d AND Future:true AND TimeStamp:<*

Warnings

Depending on the complexity of the query and the attributes being queried, the action may experience slowness.

The action may cause a decrease in performance for other Data Archive users as well as server-side (Bulk Query limit exceeded) errors, which could impact other user's operations.

For More Information

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