Syntax for PI point searches
- Last UpdatedDec 16, 2024
- 3 minute read
- PI System
- PI Server 2024 R2
- PI Server
Refer to the following sections for details on the syntax for building PI point queries in PI AF and PI Builder. For complete details on PI point query syntax, see “PIPoint Query Syntax Overview” in PI System Explorer Help > AF SDK Reference > Overview, or refer to PI Point Query Syntax Overview.
Condition filters
To build a PI point query, enter one or more AND condition filters that you can also combine with an OR condition as needed. Each AND condition contains one or more queries, separated by a space or AND. A query consists of a query filter name, an operator, and the query filter. This enables you to specify multiple conditions with a single query, as shown in the following example:
(tag:<>sin* AND PointType:Float64) OR (tag:="*Tank*" AND DataType:=Int32)
Note: You can only use parentheses between OR conditions.
You can only reference a filter name once per AND condition of the query string. For example, PointId:>5 AND PointId:<10 generates an error, whereas PointType:=Int32 OR PointType:=Float32 is valid.
For maximum efficiency, build your query so that you eliminate most items from the retrieved results with your first condition filters.
Query filter names
When querying based on PI point attributes, the query filter name is a PI point attribute name or alias. Common aliases are:
|
Alias name |
Attribute name |
|---|---|
|
Name |
Tag |
|
DataType |
PointType |
|
Description |
Descriptor |
|
PointClass |
PtClassName |
Starting in PI AF 2017, you can query based on values, in addition to querying PI points based on attribute. However, you cannot use the OR condition to query a PI point value. For example, you would generate an error if you were to enter the following queries:
-
IsGood:false OR Annotated:true
-
PointType:Float AND Value:>10 because PointType:Float is implicitly translated to 'PointType:=Float16 OR PointType:=Float32 OR PointType:=Float64'
-
PointType:Int AND Value:>10 because PointType:Int is implicitly translated to 'PointType:=Int16 OR PointType:=Int32'
-
sin* AND Value:>10 because sin* is implicitly translated to 'tag:=sin* OR Descriptor:=sin*' if the default filter setting for Include Description in Search is selected. To be valid, you would need to clear the Include Description in Search filter.
Wildcard characters
You can use the following special characters in a PI point query.
|
Special character |
Description |
Example |
|---|---|---|
|
* |
Substitute any number of unspecified characters |
sin* Returns all PI points that have names starting with "sin", for example, sinusoid and sinusoidu. |
|
? |
Substitute a single unspecified character |
CD?158 Returns all PI points that have names starting with "CD", followed by any single character, followed by "158" (for example, CD1158, CDA158, and so on). |
|
: or := |
When searching for all PI points with a specific attribute value (other than name), separates the attribute and the value you are searching for. Note When searching for a PI point name that contains a colon, enclose the name in double quotation marks, or precede the colon with a backslash. |
pointsource:R Returns all PI points that have the pointsource value R. "ba:temp.1" ba\:temp.1 Either of the above examples returns the PI point named ba:temp.1. |
|
'' or "" |
Delimiters for search strings containing spaces or special characters |
'*Owner Change*' or "*Owner Change*" Returns all PI points that have names containing Owner Change. "ba:temp.?" Returns all PI points that have names starting with ba:temp. and ending with any single character. |
Note: Results of the examples above assume you are using the default search option, which searches for PI point names that start with your search string.
Operators
The following table lists the operators that you can use in an 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 |
In PI point value queries with a String data type, you cannot use the following operators: <, <=, >, or >=. Furthermore, when boolean values are expected (as with Substituted, Questionable, Annotated, and IsGood point value queries), you can only use the = and <> operators.
Syntax restrictions
-
You cannot query future point attributes, such as creationdate:>y-1d AND future:true, on Data Archive servers older than 3.4.395.
-
You cannot query security point attributes, such as PtSecurity and DataSecurity, on Data Archive servers older than 3.4.380.