One of the most important topics when developing your application is how to
search for the information you need. The PI Web API has the option to search on attributes,
event frames, elements and other objects based on a number of search criteria
natively. Searching and filtering the objects being returned is critical to the performance
of the application as we never want to request more information from the service
than is necessary for application. As doing so will negatively affect the performance.
You can search on most controllers in the PI Web API. These searches take on the form HTTPS colon
slash slash your machine name slash PI Web API slash the controller name. This is going to be
whatever you want to search for: event frames, elements then slash search, a question mark,
database ID equal to the actual database ID that you'll be searching on, ampersand,
query, an equal sign and then your search criteria. The search criteria is available
to be viewed on the help file documentation. This may seem overwhelming at first and will
take some time to get familiar with the range of search options available to you,
though searching in the PI Web API holds a lot of power once the syntax is grasped. So let's
start with a simple example to get our feet wet that works through some of the syntax together.
Let's say we're looking for event frames in our database; to do this we'll need to set up our
URL to be the base URL slash event frames, another slash and then the keyword search.
Next we'll need to know the AF database's web ID that we'll be searching under followed by another
slash. Let's get our database ID using Chrome quickly. Next we'll need some search criteria;
let's say we only want to find event frames based on particular event frame template. If
we take a look at the documentation for the search query syntax we see that we have the
option of specifying a template. To do this we'll need the keyword template followed by
some equal operator and then a string value. Let's take a quick look at the
equal operator in the syntax help page. It looks like from here that in order to do an
equivalency comparison we'll need either a colon or a colon and an equal sign. For the
string value this is what you would expect a string of characters either in single or
double quotes or if there are no spaces then you can just type the string itself.
Let's use this information to build out our search query; remember that we're going to need to use
an ampersand to add our second URL parameter followed by a query equals and then the search
query criteria. For this example I already have an event frame template setup called boiler fuel
over-limit. Let's execute this request. Though dropped in a and database here. If we take a
look at the response, we see that we have event frames based off of this particular template.
We can search based on a number of different criteria as seen in the documentation such as
start and end times that the event frames need to be contained within or whether or
not the event frame is in progress even. If we want to narrow this further we could search on
name or start time but let's do something a little more interesting. Let's search on
the value of an attribute in the event frame for our search criteria. If you'll notice in
the documentation one of our query operations possible is based on attribute value filter.
According to the documentation an attribute value filter consists of an attribute path
followed by some sort of operator and then a string value. According to the documentation
we define an attribute path as a vertical bar followed by the name of the attribute.
In this case since we're using operator instead of equal operator we have the option of using
both what is contained in the equals operator as well as these other possible values: not equals,
less than, greater than or equal to etc. In my case I've been tracking the average, maximum and
final fuel flow rates in these event frames. I'm going to be filtering on the final fuel flow rate
and I'll filter out anything that has a value less than two and a half at the end of the event frame.
In order to add the attribute value filter I'll need to add a space and we'll URL encode that off
the bat with percent 20 then I'll be adding the attribute filter name. Since my attribute-value
name has spaces in it that I've already encoded using the percent 20 we'll also need to wrap
this in single quotes while single quotes are also a URL special character, these can be
encoded using %27. If we execute this request we see that we narrowed our list even further.
We've taken a brief look at the search capabilities in the PI Web API, as well
as how to interpret some of the documentation for it as well. We made a simple request using
a single filter criterion for a template and we made a more complex multi criteria request using
attribute value to filter as well. We've only just scratched the surface of the complexity of the
search functionality in the core PI Web API, but this should be sufficient for you to begin using
the filter criterion to optimize your applications to retrieve only the necessary information.