The following requests use the $filter function. It is a powerful tool to query only what you are looking for. Below are the operators you can define with the filter function.
Operator |
Description |
Comment |
---|---|---|
eq |
Equal |
Performs an exact match on that field |
ne |
Not equal |
Matches on non-matching values |
gt |
Greater than |
Matches when the field is greater than the value |
ge |
Greater or equal |
Matches when the field is greater than or equal to the value |
lt |
Less than |
Matches when the field is less than the value |
le |
Less or equal |
Matches when the field is less than or equal to the value |
and |
Logical and |
|
or |
Logical or |
|
contains |
Matches anything that contains the value |
|
startswith |
Matches on anything that starts with the value |
|
endswith |
Matches on anything that ends with the value |
Get $filter Instrument eq '101-FT -100'
The following request filters for a specific InstrumentName, eq '101-FT -100', and additionally queries the number of Instruments with that name, using the $count operator.
-
Select the 04.01 $filter Instrument eq '101-FT -100' request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=InstrumentName eq '101-FT -100'&$count=true
The response includes all the Instrument's properties. The partial list below shows a few lines displaying the property InstrumentName, which indicates the Instrument '101-FT -100' you filtered on.
Based on the previous filter query, you can select a few properties for Instrument Id ('4153').
-
Select the 04.02 Get Specific Instrument by Id + properties request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject('4153')?$select=Id,InstrumentName,InstrumentService,LoopName,InstrumentManufacturer,InstrumentModel
Get $filter Instrument ne '101-FT -100'
This request gets all the instruments which are not equal to '101-FT -100'. The request also includes the number of items and a list of selected properties.
-
Select the 04.03 $filter Instrument ne '101-FT -100' request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=InstrumentName ne '101-FT -100'&$count=true&$select=Id,InstrumentName,InstrumentService,LoopName,InstrumentManufacturer,InstrumentModel
Get $filter Instrument that contains '2212'
This request gets all the instrument names which contain '2212'. The request also includes the number of items and several properties.
-
Select the 04.04 $filter Instrument that contains '2212' request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=contains(InstrumentName,'2212')&$count=true&$select=Id,InstrumentName,InstrumentService,LoopName,InstrumentManufacturer,InstrumentModel
Get $filter Instrument that starts with '101-FT' plus a few additional properties
This request gets all the instrument names whose InstrumentName value starts with '101-FT'.
-
Select the 04.05 $filter Instrument that starts with '101-FT' + properties request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=startswith(InstrumentName,'101-FT')&$select=Id,InstrumentName,InstrumentService,LoopName,InstrumentManufacturer,InstrumentModel&$count=true
Get $filter Instrument that ends with '13' plus a few additional properties
This request filters for all instruments whose names end with '13'.
-
Select the 04.06 $filter Instrument that ends with '13' + properties request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=endswith(InstrumentName,'13')&$select=Id,InstrumentName,InstrumentService,LoopName,InstrumentManufacturer,InstrumentModel&$count=true
Get $filter Instrument change date eq (given date)
Date properties are returned in date and time offset format, where the time offset is displayed at the end of the date. This request displays the change date property using ChangeDate:
To filter by date field, provide the date string as follows:
Format |
Example |
|
Payload Date and Time |
YYYY-MM-DDTHH:MM:SS±HH:MM |
2002-04-04T00:00:00+03:00 |
Query on Date |
YYYY-MM-DDTHH:MM:SS%2B:MM |
2002-04-04T00:00:00%2B03:00 |
-
Replace the '+' character by '%2B'.
-
Almost all of Smart Instrumentations Date fields such as ChangeDate, record only the date although older data in the database may also include the time. For this reason, the API will ignore the time and only refer to the date when filters apply, even if the time is different than 00:00:00. For example, if the database returns a ChangeDate = "2002-04-04T11:30:15+03:00" and the filter asks for ChangeDate later than that time, you will get all rows of that date, even if the hour is earlier than the value in the database.
-
Select the 04.07 $filter Instrument change date eq (given date) and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=ChangeDate eq 1998-12-21T00:00:00%2B02:00&$select=Id,InstrumentName,ChangeDate
Payload response example:
Get $filter Instrument change date 'lt' (given date)
This request gets all the instruments Ids, name, and change date properties, where the date is 'lt' (less than) a given date. In addition, returns a count and sorts by the date.
-
Select the 04.08 $filter Instrument change date lt (given date) request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=ChangeDate lt 2016-08-02T00:00:00%2B03:00&$select=Id,InstrumentName,ChangeDate&$count=true&$orderby=ChangeDate
Get $filter Instrument change date ne (given date)
This request gets all the instruments' Ids, names, and change date properties, where the date 'ne' (not equal) to a given date, and in addition returns a count and sorts by date.
-
Select the 04.09 $filter Instrument change date ne (given date) request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=ChangeDate ne 2016-08-02T00:00:00%2B03:00&$select=Id,InstrumentName,ChangeDate&$count=true&$orderby=ChangeDate
Get $filter Instrument change date gt (given date)
This request gets all the instruments' Ids, names, and change date properties, where 'gt' (greater than) a given date and returns a count and sorts by the date.
-
Select the 04.10 $filter Instrument change date gt (given date) and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=ChangeDate gt 1999-10-19T00:00:00%2B02:00&$select=Id,InstrumentName,ChangeDate&$count=true&$orderby=ChangeDate
Get $filter Instrument change date ge (given date)
This request gets all the instruments' Ids, names, and change date, where ''ge' (greater than or equal) to a given date and returns a count and sorts by the date.
-
Select the 04.11 $filter Instrument change date ge (given date) request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=ChangeDate ge 1999-10-19T00:00:00%2B02:00&$select=Id,InstrumentName,ChangeDate&$count=true&$orderby=ChangeDate
Payload response example:
Get $filter Instrument change date le (given date)
This request gets all the instruments Ids, name, and change date, where 'le' (less than or equal) to a given date, and in addition returns account and sorts by date.
-
Select the 04.12 $filter Instrument change date le (given date) request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=ChangeDate le 1999-10-19T00:00:00%2B02:00&$select=Id,InstrumentName,ChangeDate&$count=true&$orderby=ChangeDate
Payload response example:
Get $filter using Logical or
This request gets all the instruments that contain 'FE' or 'FT' in their name.
-
Select the 04.13 $filter using Logical or request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=contains(InstrumentName,'FT') or contains(InstrumentName,'FE')&$select=Id,InstrumentName,InstrumentService,LoopName,InstrumentManufacturer,InstrumentModel,ChangeDate&$count=true&$orderby=InstrumentName asc
Payload response example:
Combined And/Or filter
When it comes to using and & or combined within the same request, there are few guidelines to remember in order to understand how the API extracts the payload:
-
The API ignores parenthesis () – i.e. a request in the form:
A+B·C (A or B and C) will produce the same result as (A+B)·C
-
The second rule is that the payload is evaluated according to SQL precedence rules of the database engine.
-
A navigation property by Id overrules the rest of the $filter query.
The next request filters instruments of the As-Built project that fulfill either of the following conditions:
-
The instrument name contains 'PT' AND the instrument service contains 'F-102 TOP'.
-
The instrument name contains '905''.
For both SQL server and Oracle databases, 'and' precedes 'or' operator.
-
Select the 04.14 Combined and/or $filter Query Options request and click Send.
{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$filter=contains(InstrumentName,'905') or contains(InstrumentName,'PT') and contains(InstrumentService,'F-102 TOP')&$count=true&$select=Id,InstrumentName,InstrumentService,LoopName
Payload response example:
Updating Data (Patch)
This API supports updating of data provided you have the appropriate Write license; the property is not read-only and you are not limited by access rights.
-
Update is available for a single, specific item by sending a PATCH request with the property and the value that should be updated in the body of the request. You can update multiple properties however, if some are read-only and others are not, no update will be carried out to any of the properties.
-
The update of item relations is not supported (for example, between Instrument and its loop).
-
Sending a patch request with wrong data type, the entire update will fail.
The following PATCH request updates the service description of instrument 101-FT -101. The body of the request includes the properties and the values to be changed in a Json format.
Select the 04.15 Update Instrument Service request and click Send.
The response returns the entire payload of the item.