Returning attribute WebIDs in the results is an enhancement request that is in our backlog. It will be included in the upcoming release.
In order to support searching multiple object types and standard search engine features like paging and relevance sorting, Search was designed to support PI points and AF elements as top-level search results for this release.
You could include matchedfields instead of attributes to get back only what has matched, in you case the attributename "KPI"
As for the documentation, we will make it more consistent.
Thanks for the feedback. Please let us know if you have any more questions.
As Divya suggested, we can add matchedfields to the URL fields list as follows:
This will add a MatchedFields array to each search result which can contain any field in the object that the search string matched on. In this case since the search was bound to only search attributename that will be the only field returned for results in this array. Note that this array is unordered. Also note * below regarding WebID.
Also to extend upon the example given, if you are searching for a exact phrase to match, say an exact attribute name with multiple words like "Fuel Gas Flow", it's not currently possible. However you can use ANDs between search terms to find results with a field that at least matches all the containing words.
I also agree the documentation could be improved.
*My understanding of the next release is that the attribute WebID will only be present in the attributes object, so you will still receive all the attributes of a result object which you will then have to search for the attribute name of interest to find the WebID to use to access the data. Perhaps this makes the matchedfields suggestion not as useful to reduce the quantity of attributes that need to be processed and filtered for each search result but that may be negligible to the time gained by having immediate access to the attribute WebID and avoiding an additional GET per result.
Many thanks for your replies! Really like having WebIDs for the attributes! Good start of the day Good to mention the matchedfields searchresult field, which will be soon have some description in the documentation.. I guessed the implicit wildcard behaviour of the search would imply we have all results that contain non-exact phrases, but there's nothing that AF attribute categories won't solve (pun intended).
And of course, this is all due to the fact that the REST concept does not fit AF very well. So no blame there. But in general, customers like the PI Web API due to it's simplicity, so using it in scenarios that are not in line with REST are quite obvious. And to be true, you need a first release to know what direction to take based on feedback, and in all the PI Web API is great to have!