Click or drag to resize
OSIsoft, LLC

PIPoint Query Syntax Overview

This topic describes the syntax used when parsing PIPoint query strings within the AF SDK.

This topic contains the following sections:

A PIPoint query string is used as a parameter to the PIPointFindPIPoints(PIServer, String, Boolean, IEnumerableString, AFSearchTextOption) method to build a query to find the desired PIPoint objects. The query is one or more AND condition filters that are ORed together. Each AND condition contains one or more query items. A query item consists of a query filter name, an operator, and the query filter. This allows multiple conditions to be specified with a single query.

AF supports querying PIPoint based on PIPoint attribute, and starting in AF 2017, it also supports querying based on PIPoint value. However, OR condition is not supported if querying based on PIPoint value.

Syntax

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 ?



⁽¹⁾ 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 "=".
⁽²⁾ If the type of a PIPOINTATTRIBUTE is DateTime, then the "TimeValue"
     format is supported for the filter value.

Description

Each AND condition filter will be ORed together to perform the query for PIPoint objects by the PIPointFindPIPoints(PIServer, String, Boolean, IEnumerableString, AFSearchTextOption) method. Each QueryFilter within the AND condition is separated by the AND keyword or whitespace.

When querying based on PIPoint attributes, the query filter name is a PIPoint attribute name. The PICommonPointAttributes class contains the names of common attribute names. The Alias Attribute Names section below lists the supported alias names for PIPoint attribute names.

Use the PIPointValueFilter when querying based on a PIPoint value. Note that OR condition is not supported if querying based on PIPoint value, where it would cause an error.

The Operators table below describes the operators that can be used in the AND condition. It is best to construct the query so that the most items will be eliminated from the returned results with the first conditions.

The query string values can contain wildcard characters and are described in the Wildcard Characters section below.

The searchNameAndDescriptor parameter of the PIPointFindPIPoints(PIServer, String, Boolean, IEnumerableString, AFSearchTextOption) method is effective if there is a query filter without a name, and the "Tag" attribute filter name as well as the "Descriptor" attribute filter name are not specified. Otherwise, this parameter will be ignored. If , then both "Tag" and "Descriptor" attributes will be searched using the query value without a name. If , then only "Tag" attribute will be searched using the query value without a name.

Caution note Caution

A PIPointValueFilter "Value" query is not supported for PIPoint with Blob type. In this case, the filter evaluation would not be properly done, hence the corresponding PIPoint not returned in the query result. The only exception is if the PIPoint value is a PI System Digital State where filter evaluation will be performed.

Caution note Caution

A filter name may only be referenced one time per AND condition of the query string. This example would cause an error: PointId:>5 AND PointId:<10. This example would be valid: PointType:=Int32 OR PointType:=Float32.

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.

Alias Attribute Names

The following table lists the supported aliases for common PIPoint attribute names. These aliases can be used instead of the actual attribute name. The PICommonPointAttributes class contains the names of the common PIPoint attribute names.

Alias Name

Attribute Name

Name

Tag

DataType

PointType

Description

Descriptor

PointClass

PtClassName

Operators

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

Operator

Description

Example

=

The EQUALS operator.

Tag:Tank* or Tag:=Tank*

<>

The NOT EQUALS operator.

PointType:<>Int32

<

The LESS THAN operator.

Descriptor:<M

<=

The LESS THAN OR EQUAL operator.

Tag:<=Tank

>

The GREATER THAN operator.

Tag:>Tank

>=

The GREATER THAN OR EQUAL operator.

Tag:>=Tank

Caution note Caution

The following AFSearchOperator are not supported in a PIPointValueFilter "Value" query if the PIPoint being queried is String type: LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, where filter evaluation would not be properly done, hence the corresponding PIPoint not returned in the query result.

For the case of PIPointValueFilter query with BooleanValue (i.e "Substituted", "Questionable", "Annotated", "IsGood"), only Equal and NotEqual are supported, while the other operators would cause an error.

The In operator is not supported. It will be implicitly translated as a filter value.

  • Description:"IN("abc", "def")"

    This is implicitly translated to 'Description:="IN("abc", "def")"'

  • Name:"IN("abc", "def")"

    This is implicitly translated to 'Tag:="IN("abc", "def")*"'

  • Value:"IN(0, 1)"

    This is implicitly translated to 'Value:="IN(0, 1)"'

  • TimeStamp:"IN(y, t)"

    This is implicitly translated to 'TimeStamp:="IN(y, t)"', where it would cause an error due to AFTime parsing failure.

  • IsGood:"IN(0, 1)"

    This is implicitly translated to 'IsGood:="IN(0, 1)"', where it would cause an error due to Boolean parsing failure.

Examples

Below are some example of PIPoint attribute queries:

  • sin*

  • name:sin*

  • 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:<*

Caution note Caution

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

The following would cause an error:

See Also
Enabling Operational Intelligence