Skip to main content

Highlighting textual matches

This page explains how highlighting textual matches works in the Partium Find API.

When performing a text search, the user submits a query that may match the data of the resulting parts. For example, if the user searches for Bluetooth, the results may contain parts that have the word Bluetooth in their ID, name, and/or metadata.

By highlighting the specific portions of the results that match the user's query terms, we aim to improve the search experience and provide better visibility and understanding of why each result was returned. This makes it easier for users to quickly identify relevant parts in search results.

Enabling highlighting of textual matches​

The user can get the highlights of textual matches by sending the results.highlights projection in the search request. For more information about projections, please refer to the Expanding search results article.

When this projection is sent, the API will return an additional results.highlights field for each result, with the following two nested fields:

  • results.highlights.snippet: A snippet containing the exact matches in the metadata attributes. For example, if the user query is Bluetooth and a resulting part has a metadata attribute called Category with the value Bluetooth Module, then this snippet field will be Category: Bluetooth Module for that part.
  • results.highlights.indices: A field that contains three nested fields: id, name, and snippet. Each of these fields will contain an array of index ranges, represented by objects with a from and to property. These indices are zero-based, and the interval is inclusive of the from index and exclusive of the to index. Indices inside results.highlights.indices.id indicate which characters in the results.id field match the user query. Similarly, indices inside results.highlights.indices.name will refer to the results.name field, and indices inside results.highlights.indices.snippet will refer to the results.highlights.snippet field.

Here is a request and response example:

> POST https://api.partium.io/1/find/search
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
> Content-Length: 282
>
> {
>   "language": "en",
>   "projection": [
>     "results.id",
>     "results.name",
>     "results.highlights"
>   ],
>   "matches": {
>     "organization": "partium-demo",
>     "text": "RDC 12"
>   },
>   "resultOptions": {
>     "limit": 2
>   }
> }
> 
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 971
<
< {
<   "sessionId": "39a7a1c4-3af0-4a3a-86db-9463050750b7",
<   "imageId": null,
<   "results": [
<     {
<       "id": "RDC19889",
<       "name": "Fuse-PV URDC 10x38, 1,000 V / 12 A",
<       "highlights": {
<         "snippet": null,
<         "indices": {
<           "id": [
<             {
<               "from": 0,
<               "to": 3
<             }
<           ],
<           "name": [
<             {
<               "from": 9,
<               "to": 12
<             },
<             {
<               "from": 30,
<               "to": 32
<             }
<           ],
<           "snippet": []
<         }
<       }
<     },
<     {
<       "id": "RM5138867",
<       "name": "Standard cylinder",
<       "highlights": {
<         "snippet": "Category: Standard cylinder",
<         "indices": {
<           "id": [],
<           "name": [
<             {
<               "from": 6,
<               "to": 10
<             }
<           ],
<           "snippet": [
<             {
<               "from": 16,
<               "to": 20
<             }
<           ]
<         }
<       }
<     }
<   ],
<   "resultsTotalCount": 500
< }
note

Replace <<Your Organization Name>> with the provided organization name.

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

As can be seen in the example, the results.highlights object looks like this:

{
  "snippet": null,
  "indices": {
    "id": [
      {
        "from": 0,
        "to": 3
      }
    ],
    "name": [
      {
        "from": 9,
        "to": 12
      },
      {
        "from": 30,
        "to": 32
      }
    ],
    "snippet": []
  }
}

In this case, we have a match for both the id and the name fields, but no match for the snippet field. These indices indicate the position of the match. For example, a frontend could use the indices to highlight the matching text like this:

  • id: RDC19889
  • name: Fuse-PV URDC 10x38, 1,000 V / 12 A

Fetching highlights for additional pages​

Once you have the sessionId of an existing search, subsequent result pages can be retrieved via the GET /search/state/{sessionId} endpoint (see Paginating search results). The results.highlights projection can also be used in this case.

Here is an example of it. Note that we are getting the state of the previous 39a7a1c4-3af0-4a3a-86db-9463050750b7 search session:

> GET https://api.partium.io/1/find/search/state/39a7a1c4-3af0-4a3a-86db-9463050750b7? \
    limit=2& \
    projection=results.id,results.name,results.highlights
> Authorization: Bearer <<Your Access Token or API Key>>
> 
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1033
<
< {
<    "sessionId": "39a7a1c4-3af0-4a3a-86db-9463050750b7",
<    "imageId": null,
<    "results": [
<        {
<            "id": "RDC19889",
<            "name": "Fuse-PV URDC 10x38, 1,000 V / 12 A",
<            "highlights": {
<                "snippet": null,
<                "indices": {
<                    "id": [
<                        {
<                            "from": 0,
<                            "to": 3
<                        }
<                    ],
<                    "name": [
<                        {
<                            "from": 9,
<                            "to": 12
<                        },
<                        {
<                            "from": 30,
<                            "to": 32
<                        }
<                    ],
<                    "snippet": []
<                }
<            }
<        },
<        {
<            "id": "RM5138867",
<            "name": "Standard cylinder",
<            "highlights": {
<                "snippet": "Category: Standard cylinder",
<                "indices": {
<                    "id": [],
<                    "name": [
<                        {
<                            "from": 6,
<                            "to": 10
<                        }
<                    ],
<                    "snippet": [
<                        {
<                            "from": 16,
<                            "to": 20
<                        }
<                    ]
<                }
<            }
<        }
<    ],
<   "resultsTotalCount": 500
< }

An important note regarding the GET /search/state/{sessionId} endpoint is that the results.highlights projection will return the highlights only if the last POST /search request for that session had the results.highlights projection set. Otherwise, it will return null for the results.highlights field.

For example, assume we did not set the results.highlights projection in the last POST /search request for the session with ID 29baa1e6-7973-4cb7-b1e6-bcc351c3efc5:

> GET https://api.partium.io/1/find/search/state/29baa1e6-7973-4cb7-b1e6-bcc351c3efc5? \
    limit=2& \
    projection=results.id,results.name,results.highlights
> Authorization: Bearer <<Your Access Token or API Key>>
> 
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 203
<
< {
<    "sessionId": "29baa1e6-7973-4cb7-b1e6-bcc351c3efc5",
<    "imageId": null,
<    "results": [
<        {
<            "id": "RDC19889",
<            "name": "Fuse-PV URDC 10x38, 1,000 V / 12 A",
<            "highlights": null
<        },
<        {
<            "id": "RM5138867",
<            "name": "Standard cylinder",
<            "highlights": null
<        }
<    ],
<   "resultsTotalCount": 500
< }

As can be seen in the example, the results.highlights field is null for both results in this case.