Functionality

The search endpoint accepts a query parameter representing the serialized and encoded query in use.

You can use the skip and take parameters to page the results set.

A typical API call is as follows:

http://<hostname>/api/search?q=myQuery&skip=3&take=10.

The server replies with a resource containing the serialized and encoded query that has all query arguments added, so any subsequent calls (e.g. for extra faceting, sorting, paging, etc.) can use the returned query to build on.

In its basic incarnation, the Search API's response consists of three parts:

Information about the executed query.
Additional facet queries that you can add to refine the result, based on the current results.
Entities in the result set, including a limited set of properties (see Configuration)

Facet search

The easiest way to execute a facet search, is to start with calling the search endpoint without any arguments, and looking for the appropriate query id in the response.

Calling the endpoint without any arguments, returns all entities the user has access to (possibly limited by the default search configuration).

GET http://<hostname>/api/search

Response

{
    "query": "",
    "skip": 0,
    "take": 10,
    "totalItemCount": 63,
    "returnedItemCount": 10,
    "sorting": null,
    "sortingOptions": [ ],
    "filters": [ ],
    "fulltext": [ ],
    "facets": [
        {
            "labels": {
                (Default): "Asset type"
            },
            "name": "taxonomy_items.27.children",
            "childCount": 63,
            "ispartial": false,
            "children": [
                {
                    "labels": {
                        (Default): "Image"
                    },
                    "addQuery": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0",
                    "ispartial": false,
                    "matchCount": 45,
                    "children": [ ]
                },
                ...
            ],
            "definition": "M.AssetType"
        },
        {...},
        ...
    ],
    "items": [
        {
            "id": 381,
            "properties": {
                "Title": "Test-asset-embedded-fonts.doc",
                "FileName": "Test-asset-embedded-fonts.doc",
                "Renditions": {
                    ...
                }
            },
            "relations": { },
            "created_by": {...},
            "created_on": "2014-12-31T08:57:12.4325965Z",
            "modified_by": {...},
            "modified_on": "2014-12-31T09:10:13.3950924Z",
            "entitydefinition": {...},
            "copy": {...},
            "permissions": {...},
            "lifecycle": {...},
            "is_root_taxonomy_item": false,
            "full": {...},
            "self": {...},
            "renditions": {...},
        },
        ...
    ]
}

Next limit the result set to assets of type image. For this, lookup the appropriate addQuery value, and relaunch the request.

GET http://<hostname>/api/search?query=FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0

Response

{
    "query": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0",
    "skip": 0,
    "take": 10,
    "totalItemCount": 45,
    "returnedItemCount": 10,
    "sorting": null,
    "sortingOptions": [ ],
    "filters": [
        {
            "name": "taxonomy_items.27.children",
            "label": "Asset type",
            "type": "string",
            "values": [
                {
                    "value": 354,
                    "label": "Image"
                }
            ],
            "operator": "FacetEquals",
            "removeQuery": "",
            "group": "27"
        }
    ],
    "fulltext": [ ],
    "facets": [
        {
            "labels": {
                (Default): "Geography"
            },
            "name": "taxonomy_items.26.children",
            "childCount": 1,
            "ispartial": false,
            "children": [
                {
                    "labels": {
                        (Default): "Europe"
                    },
                    "addQuery": "JwAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NDuQ0sgQmYQISOgEADOriR0JwAAAA2",
                    "ispartial": false,
                    "matchCount": 1,
                    "children": [ ]
                }
            ],
            "definition": "M.Geography"
        },
        ...
    ],
    "items": [...]
}

To further restrict the result set to include only European images, again lookup the appropriate addQuery value and relaunch the request. Note the different addQuery values for the facet Europe in the second response, compared to the value for the same facet in the first response. The system automatically amends the encoded queries with all previous restrictions.

GET http://<hostname>/api/search?query=JwAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NDuQ0sgQmYQISOgEADOriR0JwAAAA2

Response

{
    "query": "JwAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NDuQ0sgQmYQISOgEADOriR0JwAAAA2",
    "skip": 0,
    "take": 10,
    "totalItemCount": 1,
    "returnedItemCount": 1,
    "sorting": null,
    "sortingOptions": [ ],
    "filters": [
        {
            "name": "taxonomy_items.26.children",
            "label": "Geography",
            "type": "string",
            "values": [
                {
                    "value": 324,
                    "label": "Europe"
                }
            ],
            "operator": "FacetEquals",
            "removeQuery": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0",
            "group": "26"
        },
        {
            "name": "taxonomy_items.27.children",
            "label": "Asset type",
            "type": "string",
            "values": [
                {
                    "value": 354,
                    "label": "Image"
                }
            ],
            "operator": "FacetEquals",
            "removeQuery": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA5vtzi83djI5NBuAGEF6Y4UAAAA0",
            "group": "27"
        }
    ],
    "fulltext": [ ],
    "facets": [ ],
    "items": [ ]
}

The following example shows how facet queries can be composed. However, it should be clear that the encoded query includes all information about all facets combined. It is by no means necessary to execute all previous calls, once the appropriate query is composed.

Each of these calls could also have been executed by means of a POST with a JSON request payload

{
    "query": "encodedquery"
}

Getting all queries for a certain taxonomy item

Given the entity ID of a facet, it is also possible to directly retrieve the query IDs.

GET http://<hostname>/api/search?facetFieldName=taxonomy_items.27.children

Response

{
    "query": "",
    "facet": "taxonomy_items.27.children",
    "children": {
        "I": [
            {
                "labels": {
                    (Default): "Image"
                },
                "addQuery": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0",
                "ispartial": false,
                "matchCount": 45,
                "children": [

                ]
            }
        ],
        ...
    }
}

Also in this case, it is possible to chain queries.

GET http://<hostname>/api/search?query=FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0&facetFieldName=taxonomy_items.26.children

Response

{
    "query": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0",
    "facet": "taxonomy_items.26.children",
    "children": {
        "E": [
            {
                "labels": {
                    (Default): "Europe"
                },
                "addQuery": "JwAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NDuQ0sgQmYQISOgEADOriR0JwAAAA2",
                "ispartial": false,
                "matchCount": 1,
                "children": [

                ]
            }
        ]
    }
}

Getting the query for a specific facet value

Given an entity ID, it is possible to immediately retrieve the corresponding query ID.

In this example, the Classification Name "Europe" has enitity ID 324.

GET http://<hostname>/api/search?id=324

Response

{
    "query": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA5vtzi83djI5NBuAGEF6Y4UAAAA0",
    "filters": [ ]
}

Using this query ID will return all "Europe" assets.

Query builder

In addition to facet searches, it is also possible to filter using name/operator/value pairs. Which filters are available, depends on the configuration.

POST http://<hostname>/api/search

Request payload

{
    filters: [
        {
            "name": "Title",
            "operator": "Contains",
            "values": [
                "text to search for"
            ]
        }
    ]
}

Response

{
    "query": "GwAAAB-LCAAAAAAABAAzOLz90Gqjw9u19EIyS3JSD283P7w9sbg4teTQbgCuZcmBGwAAAA2",
    "skip": 0,
    "take": 20,
    "totalItemCount": 14,
    "returnedItemCount": 14,
    "sorting": null,
    "sortingOptions": [ ],
    "filters": [
        {
            "name": "properties.*.Title",
            "label": "Title",
            "type": "string",
            "values": [
                {
                    "value": "asset",
                    "label": "asset"
                }
            ],
            "operator": "Contains",
            "removeQuery": ""
        }
    ],
    "fulltext": [ ],
    "facets": [ ],
    "items": [...]
}

Multiple filters can be added. Also, filter queries can be combined with facet queries through the query IDs.

Full-text search

You can also execute a full-text search.

POST http://<hostname>/api/search

Request payload:

{
    "fulltext": [
        "text to search for"
    ]
}

Response:

{
    "query": "FwAAAB-LCAAAAAAABAAzPLy9JLWiRKEkX6E4NbEoOUMhLb_o8HQAJ3Er4RcAAAA1",
    "skip": 0,
    "take": 20,
    "totalItemCount": 0,
    "returnedItemCount": 0,
    "sorting": {
        "name": "Title",
        "labels": {

        },
        "asc": true
    },
    "sortingOptions": [ ],
    "filters": [ ],
    "fulltext": [
        {
            "value": "text to search for",
            "removeQuery": ""
        }
    ],
    "facets": [ ],
    "items": [ ]
}

Available operators

You can use any of the following operators to build search API queries:

None
Equals
LessThan
GreaterThan
Between
StartsWith
EndsWith
Contains
FacetEquals
DoesNotContain
DoesNotStartWith
DoesNotEndWith
LessThanOrEquals
GreaterThanOrEquals
DoesNotEqual
AnyOf
AllOf
NoneOf
Missing
Exists
Changed

Can we improve this article ? Provide feedback