Search Queries (PI Web API Indexed Search)
Query the crawled data by keyword(s).
Terminology
- field - a parameter to the q URL parameter that is set to a value. This value is then used to search the indexed objects for scored results.
- value - an alphanumeric set of characters used for setting the q URL parameter fields as a means of modifying the query to the indexed objects.
- scope - A URL parameter used to declare which source scored results should be returned from to reduce the number of search results.
Example:
In the following query, the field is name, the value is Sinusoid, and the
scope is set to a PI Server called PiServer01.
https://MyServer/piwebapi/search/query?q=name:Sinusoid&scope=pi:PiServer01
General Notes on Querying
- Note that the inclusion of additional URL parameters uses the ampersand (\&)as a sperator between them. This should not be confused with the q URL parameter that can use the AND operator for parsing search results.
- PI Web API Indexed Search uses the Lucene software library for storing, parsing, and querying. For more information on query logic refer to their online documentation.
- Quotation marks are not necessary for defining values when querying.
- You can either use spaces or the URL escape character %20. For example,
the following queries are sytactically identical to the PI Web API Indexed
Search plugin:
https://MyServer/piwebapi/search/query?q=name:vibration OR name:pump
https://MyServer/piwebapi/search/query?q=name:vibration%20OR%20name:pump - Parenthesis are often useful for breaking down a complex conditional statement into logical sequences.
- The list of special characters are:
+ - && || ! ( ) { } [ ] ^ " ~ * ? : \. If you wish to use any of those characters in a query you will need to escape it first with a backslash (\\). For instance the following query looks for objects with the name "sine+cos": https://MyServer/piwebapi/search/query?q=name:sine\+cosExample
The following two queries would return drastically different results.
This first query returns the union of objects named vibration* that are float32 or objects of AF Element Template type pump of any data type.
https://MyServer/piwebapi/search/query?q=(name:vibration* AND datatype:float32) OR afelementtemplate:pumpThis next query returns the union of objects named vibration* or objects of AF Element Template type pump all of which must be of data type float32.
https://MyServer/piwebapi/search/query?q=name:vibration* AND datatype:float32 OR afelementtemplate:pump
Querying Examples
Basic Querying With the Name Field
Using the q parameter you can specify a PI Point explicitly by name using the
form:
https://MyServer/piwebapi/search/query?q=[*field*:*value*]
Note that the query values are not case sensitive. Therefore the same results are
returned for both of the following queries:
https://MyServer/piwebapi/search/query?q=name:sinusoid
https://MyServer/piwebapi/search/query?q=name:SINUSOID
Note: If you exclude the name field then the returned results will include
results from all default fields that contain the value specified. For example, the
following would return results that contain the word sinusoid in any field.
https://MyServer/piwebapi/search/query?q=SINUSOID
Modifying the Number of Results Returned Per Page
Results are broken down into groupings of 10 by default. This can be
modified by the count.
10 results per page:
https://MyServer/piwebapi/search/query?q=SINUSOID*&count=10
100 results per page.
https://MyServer/piwebapi/search/query?q=SINUSOID*&count=100
Note: Lower counts will typically resolve faster and can be parsed using the start field to jump to immediate pages of results.
You can also tell the query where to start your results by setting the URL
parameter start to a positive integer. For example the following query
returns with the default 10 results per page starting with the 90th result, or
on the 9th page of results.
https://MyServer/piwebapi/search/query?q=SIN*&start=90
Conditional Operators in Queries
Queries can also be created using conditional operators AND, OR, and NOT
and must be capitalized. For example, the following query will only return results
that have the words sinusoid and minutes in their name seperated by spaces:
https://MyServer/piwebapi/search/query?q=name:sinusoid\: AND name:minutes
This example will return results that have either the word sinusoid or minutes
in their name seperated by spaces:
https://MyServer/piwebapi/search/query?q=name:sinusoid OR name:CDT158
You do not need to use the conditional operators only on matching fields. For
example, the following query will return results that have either the word
sinusoid in their name or pressure in their description.
https://MyServer/piwebapi/search/query?q=name:sinusoid OR description:pressure
Wildcard Characters and Search Results
Wildcards can be used for more generic responses. * will match any number of
characters in the pattern, including 0 while ? will match only one wild character.
The following example will return results for 3 PI Points: sin_15minutes,
sin_20minutes, and sin_30minutes.
https://MyServer/piwebapi/search/query?q=name:sin_*minutes
The following two queries will return the same results, the PI Point sin_20minutes.
https://MyServer/piwebapi/search/query?q=name:sin_2*minutes
https://MyServer/piwebapi/search/query?q=name:sin_2?minutes
Similar techniques can be used for other fields. For example the following will
return results for all entries whose description contains the characters "sin".
https://MyServer/piwebapi/search/query?q=description:\*sin\*
Note that if you have a PI Point named "sinusoid with spaces" and query it using "q=name:sinusoid*test" you will get results for both sinusoid* and *test as they are seen as two sperate query conditions for the * operator.
Range Queries
Range Queries are used to obtain search results whose value falls between the lower bound and upper bound of a provided range. Range queries can be inclusive or exclusive of the boundaries. Inclusive range queries are denoted by square brackets '['. Exclusive range queries are denoted by curly brackets '{'.
The following example query will return results for names that lie within sinusoid and z, and includes sinusoid.
https://MyServer/piwebapi/search/query?q=name:[sinusoid TO z]
The following example query, by using curly brackets, will not return sinusoid as the boundaries are exclusive (but will still return sinusoidu).
https://MyServer/piwebapi/search/query?q=name:{sinusoid TO z}
Wildcards are allowed for boundary values to create half-open ranges. For example, the following example query will return results for anything after (i.e. greater than) sinusoid.
https://MyServer/piwebapi/search/query?q=name:{sinusoid TO *}
In these examples the query attempts to match documents within an exclusive range of terms. Since the query is matching on a term to be within a range, the following query matches on PI Point search results whose name value consists of multiple terms. The indexed names of "sinusoid 01" and "02 sinusoid" both return as search results for this example query.
https://MyServer/piwebapi/search/query?q=name:{sinusoid TO *}
Numeric Range Queries
The previous examples were Range Queries against string fields. Numeric values can also be searched for with Range Queries.
The only fields that are indexed as numeric fields are the CreationDate and ChangeDate fields for the respective PI Point attributes. To index these fields add them to the list of PI Point Attributes. This configuration may be viewed or modified on the Settings page.
These date time values are indexed as numeric values via a conversion: Dates are converted to milliseconds elapsed since 12:00:00 midnight, January 1, 0001 (0:00:00 UTC on Jan 1, 0001, in the Gregorian calendar).
The following example query is a request for last changed date equal to or greater than February 26th 2018, 22:16:50.000 (This is Universal Time). Using C#, the following code can be used to get the numeric value:
DateTime.Parse("Feb-26-2018 22:16:50").Ticks / 10000
If you have to work with Unix epoch time, i.e. seconds since 00:00:00 UTC Jan 1 1970, you can add 62135596800 to the value in seconds returned by, e.g. in the Bash shell
date --utc --date "Feb-26-2018 22:16:50.0" +%s
which is 1519683410 seconds Unix epoch time. Following either of the aforementioned conversions, our example time would be represented as numeric value: 63655280210000. Therefore the query submitted is:
https://MyServer/piwebapi/search/query?q=changedate:[63655280210000 TO *]
Using Scope to Limit Search Results
You can specify a specific source for your query by using the scope field. For
example the following example shows how to limit a query an object named
attribute1 from a PI AF database called \sadf1\test.
https://MyServer/piwebapi/search/query?q=name:attribute1&scope=af:\\sdaf1\test
You can also search an AF element in the same manner:
https://MyServer/piwebapi/search/query?q=name:attribute1&scope=af:\\sdaf1\test\TestElement
A similiar query with a PI Server named SiteServer01 would be represented as
follows:
https://MyServer/piwebapi/search/query?q=name:attribute1&scope=pi:SiteServer1
Note that scope is an additional URL paramater and as such the syntax requires that an & needs to be appended to the scope parameter.
Result Rankings and Boosting
Results from a query are typically heavily weighted toward name field matches
when multiple fields contain a match. When you want to prioritize other fields
over name in your search results you can boost other fields with the ^symbol
followed by a value. For example, the following query utilizes boosting to
increase the score for matches in the field description and decreases matches
for the field name:
https://searchdemo2.osisoft.int/piwebapi/search/query?q=name:sinusoid^0
OR description:sinusoid^8
Note that higher numbers imply a higher boost to ranking score than lower numbers.
Example of Building a Query for Refining a Search
Using the examples above we can build complex queries to refine a search for
a given indexed object.
For instance you might start with a search for an object for a tank that you
think is called tank1 so you start with a query as follows:
https://MyServer/piwebapi/search/query?q=name:tank1
Reviewing the results you realize you aren't sure it was tank 1 anymore, so
you expand the search to include all tanks'
https://MyServer/piwebapi/search/query?q=name:tank*
This gives you a large number of results so you decide to try and refine based
on location as per the description:
https://MyServer/piwebapi/search/query?q=name:tank* AND description:
Philadelphia
These results reminds you that you are certain the object you are looking for
is on the PI AF server so you add the scope value:
https://MyServer/piwebapi/search/query?q=name:tank* AND
description:Philadelphia&scope=af:\\PhlServer01\tanks
Note how the search is refined by improving the query and once it is found you can save the address for future quick reference.
