Asset search criteria

The assets search API allows you to search for your assets with search criteria.

Searchable properties

Assets can be searched on the following asset properties:

• Asset top-level properties

  • Id, Name, Description, AssetTypeId, AssetTypeName

• Metadata properties

  • Name (only in association with values), Value

• Stream reference properties

  • StreamReferenceName - Stream Reference Name
  • StreamPropertyId - SDS Stream Property Ids, not including indices

Search criteria can be chained together using an AND. See examples below.

Search matched fields

Searches all assets and returns a list of asset identifiers and their matched fields.

Example response body

Below is a response when the query string is "Name:Tracer".

• TotalCount - Represents the number of matched assets in the database which matched the given query.

A list of results is returned. Each result contains:

• MatchProperties - A list of matched property objects. Each MatchProperties object contains the matched fields and their values.

• Id - Identifier of the matched asset.

• TypeId - Asset type identifier of the asset. This is null if the asset does not reference an asset type.

• Name - Asset name.

• Description - Description of the matched asset. If the description of the matched asset is null, the description from the asset type is returned.

• ETag - Version tag.

• CreatedDate - Asset creation date.

• LastModifiedDate - Last modified date of the asset.

• LastStatus - Last status of the matched asset. If a status is not defined for the asset, this field will be null. If a status is defined, this field will correspond to Unknown, Good, Warning, or Bad. The display name of the asset status has no effect on this field.

HTTP 200 OK 
Content-Type: application/json
{
    "TotalCount": 2,
    "Results": [
        {
            "MatchedProperties": [
                {
                    "Field": "Name",
                    "Value": "Asset Tracer ced7ee16-984d-480f-8338-3055f7f39d8b"
                }
            ],
            "Id": "AssetId2b5f41ae-0929-4977-bfbd-1e046d8a66f4",
            "TypeId": "AssetTracerType",
            "Name": "Asset Tracer ced7ee16-984d-480f-8338-3055f7f39d8b",
            "Description": "First tracer device",
            "ETag": "1",
            "CreatedDate": "2021-05-26T19:05:33.8979442Z",
            "LastModifiedDate": "2021-05-26T19:05:33.8979442Z"
        },
        {
            "MatchedProperties": [
                {
                    "Field": "Name",
                    "Value": "Asset Tracer d6b984dd-b6da-4225-a2e0-59f781d065a4"
                }
            ],
            "Id": "AssetId3dbfd185-7c62-49ed-b875-7953cba07fc3",
            "TypeId": "AssetTracerType",
            "Name": "Asset Tracer d6b984dd-b6da-4225-a2e0-59f781d065a4",
            "Description": "Another tracer device",
            "ETag": "1",
            "CreatedDate": "2021-05-26T19:05:40.9043726Z",
            "LastModifiedDate": "2021-05-26T19:05:40.9043726Z"        
        }
    ]
}

Examples of asset query strings

Special characters in search queries

Add the backslash escape character ( \ ) before any special characters in search queries. The following special characters require an escape character: " | / * \ ( ) :

The following are examples of using the escape character in query strings.

Examples of asset filter strings

Filter strings are not case sensitive. Numeric types must be passed as strings according to English locale. For example, a double of 1.1 must be sent as "1.1".

Special characters in filter values

Only " \ special characters need to be escaped with the backslash escape character ( \ ) in filter values.

The following are examples of using the escape character in filter value.

Faceted Search

Asset faceted search allows for searching using asset facets.

Example

If you have the following assets in your system:

Performing a GET search/assets/facets?Name=Location returns the following response.

HTTP 200 OK 
Content-Type: application/json
[
    {
        "Name": "Location",
        "FacetValues": [
            {
                "Value": "California",
                "DocumentCount": 2
            },
            {
                "Value": "Philly",
                "DocumentCount": 1
            }
        ]
    }
]

Asset autocomplete

Asset autocomplete allows you to query assets and retrieve a list of suggested assets based on your search criteria.

Example

Assume you have the following assets in your system.

Performing a GET Search/Assets/Autocomplete?term=t&termcount=10&facetcount=10 returns the following response.

{
    "Facets": [
        {
            "Value": "trackUnit1",
            "FacetCategories": [
                {
                    "Name": "track",
                    "DocumentCount": 1
                }
            ]
        },
        {
            "Value": "t1000",
            "FacetCategories": [
                {
                    "Name": "tractorNumber",
                    "DocumentCount": 1
                }
            ]
        }
    ],
    "Tokens": [
        {
            "Value": "tracerround",
            "DocumentCount": 2
        },
        {
            "Value": "tractornumber",
            "DocumentCount": 2
        },
        {
            "Value": "tracerround_type2",
            "DocumentCount": 1
        },
        {
            "Value": "track",
            "DocumentCount": 1
        },
        {
            "Value": "t1000",
            "DocumentCount": 1
        }
    ]
}

Performing a GET Search/Assets/Autocomplete?term=t&facetcount=10 returns the following response.

{
    "Facets": [
        {
            "Value": "trackUnit1",
            "FacetCategories": [
                {
                    "Name": "track",
                    "DocumentCount": 1
                }
            ]
        },
        {
            "Value": "t1000",
            "FacetCategories": [
                {
                    "Name": "tractorNumber",
                    "DocumentCount": 1
                }
            ]
        }
    ],
    "Tokens": []
}