Faceted search data API

The AIM Dashboard/API allows advanced search using additional criteria and projections specified by you to query data from the AIM database. However, with data now available in faceted search, similar features, subject to certain limitations, can now be directly accessed through faceted search data API. This approach eliminates dependencies on the AIM API and offer faster search performance compared to AIM.

Note: The faceted search data API delivers comparable functionality, though with some constraints, while offering significant improvements in search performance and scalability to support higher concurrency.

Authentication

To obtain a CONNECT access token, use the shared authentication instructions for the AIM APIs. Pass the token in the Authorization: Bearer {access token} header when calling the faceted search data API.

Faceted search also requires a Tenant header, described below. It does not require the XSRF cookie used by the General AIM API.

For more information, refer to Integrate CONNECT Services with AIM-A.

API usage

Based on the region where AIM-Advanced environment is deployed, described in the Faceted Search API Endpoint table below. Ensure that you are using the right endpoint to avoid any authorization issues.

Call POST API (/query) and pass bearer token for authorization to invoke the faceted search data API.

POST {Faceted Search API Endpoint}/query

To invoke the API, you must pass the Tenant header for AIM-Advanced. Set the Tenant header as displayed in the screenshot.:

How to identify the Tenant header:

The Tenant value is derived from the AIM-A dashboard URL.

1. If the AIM-A dashboard URL has a portalId parameter, the Tenant value is {stage}_{portalId}. Example: If the AIM-A URL is https://abc.dashboard.imav.connect.aveva.com/?portalId=e8c57158-7955-499b-a3ce-f1cd0af7ab32#/, the Tenant header is abc_e8c57158-7955-499b-a3ce-f1cd0af7ab32

2. If the AIM-A dashboard URL doesn't have a portalId parameter, the Tenant value is {stage}. Example: If the AIM-A URL is https://abc.dashboard.dev-av.capdev-connect.aveva.com, the Tenant header is abc.

If you still run into authorization issues after providing the correct values, you can raise a support ticket with AVEVA providing the following details:

• AIM-A URL

• CONNECT Account name

• CONNECT Folder name

Specify the criteria in the POST API request body to use the new faceted search endpoint (/query) as illustrated in the following screenshots:

POST {regional endpoint}/query

• Authorization: Bearer {CONNECT access token}

• Tenant: {tenant value}

• Content-Type: application/json

  {

  "criteria": {

  "Id": "*",

  "ClassId": "FACILITY",

  "attributes": [

  {

  "id": "@AT00005",

  "operator": "like",

  "value": "SW*"

  }

  ]

  },

  "projections": {

  "fields": [

  {

  "attributeId": "@AT00002",

  "label": "Tag Number"

  }

  ]

  },

  "psize": "50"

  }

Queries

The following data can be queries using faceted search with criteria:

• Facility Objects (Tags)

  • Attributes

  • Relationships (associations using FULLID are supported; associations by classId and nested/multi-level associations are also supported)

• Documents

  • Attributes

• Equipment Objects

  • Attributes

  • Relationships (associations using FULLID are supported; associations by classId and nested/multi-level associations are also supported)

The access to above information is made available using APIs, the detailed information on usage is furnished in the subsequent sections in this topic.

Criteria

Defines the primary filters to narrow down the search.

Attribute filter object

Association filter object

Projections

Specifies the output fields to include in the search response.

psize (Page Size)

resultsContinuationKey (Fetch Next Results After This fullId)

API request body restrictions

• Projection fields: If no projection fields are specified, all available attributes for the object is returned.

• ID field meaning: The ID field always refers to the FullId of the object.

• Attribute criteria IDs: When specifying attributes in the criteria, use class IDs, not attribute display names.

• Range operators: When using in between or not between operators, both minValue and maxValue must be provided.

• Datetime handling:

  • The like operator is not supported for datetime attributes.

  • Datetime values must be in ISO 8601 format (e.g., 2022-07-22T00:00:00Z).

• Operator rules:

  • For properties with a UOM (Unit of Measure), operators such as gt, lt, gte, lte, in between, and not between are supported.

  • If no UOM is defined, only equals and not equals are supported.

• Association queries: For associations, the id field must always be a FullId; wildcard or partial matches are not supported.

Wildcard search

Wildcard search allows users to include the `*` character in their search term, matching zero or more characters. For example, `test*` will match `test` as well as any word starting with `test`.

It is not recommended to start a search term with a wildcard (e.g., `*test`) as this can negatively impact search performance.

The Faceted Search wildcard search behavior differs from AIM, which can lead to different result counts.

Wildcard search behavior in faceted search

Faceted Search uses text analysis and tokenization when indexing attribute values.
This affects how wildcard patterns (* and ?) work compared to simple string matching.

Tokenization

• Attribute values are split into individual tokens (usually words) based on spaces, punctuation, and configured analyzers.

• Each token is indexed separately.

• Example:

  Attribute Value: "Pressure Transmitter"

  Tokens: ["Pressure", "Transmitter"]

Wildcard matching

• Wildcards are applied per token, not on the entire attribute string.

  Transmitter: Matches any token that ends with Transmitter.
  Transmitter
  PressureTransmitter (because it’s a different token unless indexed as one word)

• Pressure Transmitter as a search term: Matches documents containing both tokens, in any order:

  • Pressure Transmitter

  • Transmitter for Pressure

  • High Pressure Transmitter

    Important: Wildcards do not span across token boundaries.
    Searching for *Pressure*Transmitter* might not match High Pressure Transmitter unless PressureTransmitter exists as a single token in the index.

Search API Request Inputs - Initial Load

Below table lists down the request body to be used for retrieving objects using faceted search data API.

Search API Request Inputs - Delta Loads

Below table lists down the request body to be used for retrieving objects from EDW as deltas. Update the highlighted date to fetch delta from that date.

Search API Request Inputs – Tag-Document relationships

Pagination using resultsContinuationKey

• Use the totalHits field to see how many results are available in total.

• To retrieve results in sequence, start by omitting the resultsContinuationKey in your first request. The API returns the first set of matching records along with a continuationKey in the response.

• For the next request, include this token to fetch the subsequent set of results. The token acts as a position marker (for example, the last fullID returned), allowing the API to continue from where the previous request ended. Pass this token in your next request to retrieve the next page.

  

User guidance and limitations

Review the following limitations and important notes before using the Faceted Search Data API. These constraints are designed to ensure reliable performance and accurate results. Adhering to the specified formats and supported features will help avoid errors and maximize the effectiveness of your queries.

• Maximum API rate limit: 1,000 requests per minute per asset

• Maximum result size: 500 results per page per request to ensure optimal API performance.

• Wildcard performance: Using wildcard queries can slow down search performance and should be used judiciously.

• Datagroup handling: Datagroups are not directly supported, but equivalent filtering can be achieved through appropriate query criteria.

• Attribute Criteria limit: You can define up to 10 attributes as part of criteria per request.

• Association Criteria limit: You can define up to 5 associations as part of criteria per request.

• You may refer to the class library (data model) for the asset to obtain the appropriate ClassIDs, AttributeIDs, and AssociationTypes.