Search
The search endpoint exposes a number of search types, including full-text search and faceted search. It also includes parameters supporting visual search and accepts a query parameter representing the serialized and encoded query in use.
Access the OpenAPI definition of the latest version of the Search API
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=10The server replies with a resource containing the serialized and encoded query that has all query arguments added, so any subsequent calls (for example, for extra faceting, sorting, paging, and so on) can use the returned query to build on.
In its simplest implementation, 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).
Available operators for the type parameter
In a search request, the type parameter defines how filter logic is applied to the data. It determines the structure and behavior of the filter, whether it compares field values, handles nested data, or filters by specific IDs. Choosing the right type is essential for the filter to work as intended.
The type parameter can have the following operators:
|
Operator |
Description |
Enum values |
|---|---|---|
|
|
Filters by a specific field using operators such as |
0 |
|
|
Filters by multiple values using operators such as |
1 |
|
|
Lets you build filter conditions dynamically during runtime. |
2 |
|
|
Filters on nested fields inside complex structures. |
3 |
|
|
Filters by specific IDs. |
4 |
|
|
Filters by predefined item groups or categories. |
5 |
Facet search
The easiest way to execute a facet search is to call the search endpoint without any arguments and look 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
{
"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, you can limit the result set to assets of type image. For this, look up the appropriate addQuery value, and relaunch the request.
GET http://<HOSTNAME>/api/search?query=FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0
{
"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 look up 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
{
"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 preceding 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, after the appropriate query is composed.
Each of these calls could also have been executed by means of a POST with a JSON request payload, such as:
{
"query": "encodedquery"
}
Get all queries for a specific 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
{
"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
{
"query": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NBuABjisNIUAAAA0",
"facet": "taxonomy_items.26.children",
"children": {
"E": [
{
"labels": {
(Default): "Europe"
},
"addQuery": "JwAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA9vtzi83djU5NDuQ0sgQmYQISOgEADOriR0JwAAAA2",
"ispartial": false,
"matchCount": 1,
"children": [
]
}
]
}
}
Get the query for a specific facet value
Given an entity ID, you can retrieve the corresponding query ID.
In this example, the classification name Europe has entity ID 324.
GET http://<HOSTNAME>/api/search?id=324
{
"query": "FAAAAB-LCAAAAAAABAAzOLz90Gqjw9uNzA5vtzi83djI5NBuAGEF6Y4UAAAA0",
"filters": [ ]
}
Using this query ID will return all assets with a Europe label.
Query builder
In addition to facet searches, you can also filter using a combination of name, operator, and values parameters. Which filters are available depends on the configuration.
In the request, replace periods with underscores in names.
POST http://<HOSTNAME>/api/search
{
filters: [
{
"name": "Title",
"operator": "Contains",
"values": [
"text to search for"
]
}
]
}
{
"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": [...]
}
You can add multiple filters, or combine filter queries with facet queries through query IDs.
Full-text search
You can execute a full-text search with the following request:
POST http://<HOSTNAME>/api/search
{
"fulltext": [
"text to search for"
]
}
{
"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": [ ]
}