Advanced Search REST API - v2

NEW IN RELEASE 88

The Advanced Search REST API was released in IQ Server release 88 as an Early Access feature. As of Release 100, Advanced Search is no longer Early Access feature.

This REST API allows you to

POST to Create a Search Index

Creating a search index is a resource intensive operation that can be demanding on IQ Server's database and which can take in the order of minutes to complete depending on IQ Server's database size.

We highly recommend only performing this operation at times when your IQ Server is under minimal usage.


To create a search index, a System Administrator can issue a POST request to the following path:

POST /api/v2/search/advanced/index

For example, using a local installation of IQ Server with its default configuration, a request using the cURL tool would be:

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/search/advanced/index

This is an asynchronous operation, which means that when the REST request completes the index will likely still be under construction.

GET Search Results

To search, an IQ Server user can issue a GET request to the following path:

GET /api/v2/search/advanced?query=query&pageSize=10&page=1

In the above, query is whatever search query you wish to search for and is the only mandatory query parameter, pageSize and page are optional query parameters that will take the default values of 10 and 1 respectively as shown.

For example, using a local installation of IQ Server with its default configuration, a request using the cURL tool would be:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/search/advanced?query=itemType%3Aorganization&pageSize=10&page=1

Take care to URL encode any special characters that require it, for example, in the above request ':' is URL encoded to '%3A'.

If a search index does not exist or is unreadable, then the request yields a HTTP conflict status code of 409, otherwise a JSON response body is returned with the following properties:

PropertyDescription
queryThe requested search query.
pageThe requested page number of the results.
pageSizeThe requested number of results per page.
totalNumberOfHitsThe total number of results.
isExactTotalNumberOfHitsIf the total number of results is exact, then this is true. Otherwise it's false indicating that this is a lower bound on the total number of results. An inexact value can happen when there is a large number of results making an exact count too expensive to compute.
groupingByDTOSAn array where each element is a collection of search results that have been grouped according to some criteria.
groupIdentifier

The field name that the search results have been grouped on.

groupByThe field value that the search results have been grouped on.
additionalInfoThis holds information shared between each element in a group e.g. when grouping on a security vulnerability, this is its description.
searchResultItemDTOSAn array of search results, each of these will contain an itemType indicating what type of result it is as well as a resultIndex indicating the order of the result. A lower resultIndex indicates a more relevant result that will appear earlier. Additionally each element may contain properties representing field names and values relevant to its type.

An example of a successful response body for the above example search request is as follows:

{
    "searchQuery": "itemType:organization",
    "page": 1,
    "pageSize": 10,
    "totalNumberOfHits": 2,
    "isExactTotalNumberOfHits": true,
    "groupingByDTOS": [
        {
            "groupIdentifier": "ITEM_TYPE",
            "groupBy": "ORGANIZATION",
            "additionalInfo": null,
            "searchResultItemDTOS": [
                {
                    "itemType": "ORGANIZATION",
                    "organizationId": "ROOT_ORGANIZATION_ID",
                    "organizationName": "Root Organization",
                    "resultIndex": 1
                },
                {
                    "itemType": "ORGANIZATION",
                    "organizationId": "aadb7e6a9c1444378498af5e0f7decab",
                    "organizationName": "org",
                    "resultIndex": 2
                }
            ]
        }
    ]
}

Before release 100, when Advanced Search was an experimental feature the aforementioned endpoints would be different:

POST /api/experimental/search/advanced/index

GET /api/experimental/search/advanced?search=query&pageSize=10&page=1