/document/search | Documentation

Request

Name	Type	Required	Description
`siteIds`	Array of Strings	Yes (either this or siteId)	Sites to be used for searching
`siteId`	String	Yes(either this or siteIds)	Site to be used for searching
`query`	String	No	Query for documents using Advanced Query Language . Defaults to match all documents
`filter`	String	No	Filter for documents using Advanced Query Language without affecting scoring/ranking
`count`	Number	No	Limit the number of matches. Must be an integer from 0 to 1000. Default value is 10.
`start`	Number	No	Skip a number of documents when returning matches. Must be a positive number. Default value is 0. Value of start + count must be at most 10000.
`resultFields`	Array of Strings	No	Only return a specific list of document fields
`facets`	Array of Facet objects	No	Configure facets for the search
`highlights`	Array of Highlight objects	No	Configure highlights for fields
`sort`	Array of Sort objects	No	Configure the sort order of the result
`logQuery`	String	No	The logged query string that will be used in /reports/search
`rank`	String	No	The rank model to use. A rank model affects how the score of a document is computed, and thus should be used with a `sort` object of type `score`. Supported models are `publishfreshhigh` and `publishfreshmed`, which both boost the score of recently published (fresh) documents, and `random` which assigns boost randomly to articles.
`spellcheck`	Spellcheck object	No	Did-you-mean spellchecking.

The main purpose of using facets is to surface relevant metadata for users as well as enable further narrowing of results by restricting the data returned to only those that match specific metadata values (e.g. Department = Books). You may know this feature also as Drill Down, Navigator or Faceted Browsing.

Facets are calculated for the current query only. To return facets across the entire index, simply execute a search matching all documents by not specifying query or filter in the request, with facets set to the facets for which you wish to return statistics. Also, if you are interested only in the facets, remember to specify that no results need to be retrieved by setting count to 0.

Facets can be an expensive operation, as they are calculated on the entire result set to provide exact frequency counts, and may affect query response time.

Name	Type	Required	Description
`type`	String	Yes	The type of the facet. Either `string`, `set`, `number-range`, `time-range` or `geo-distance-range`
`field`	String	Yes	The name of the field
`count`	Number	For `string` facets	The maximum number of facets
`min`	Number	For `string` facets	Only include results over a given threshold
`latitude`	Number	For `geo-distance-range` facets	The latitude/longitude of the origin point, which will be used when calculating the distance to documents. The longitude must be between -180 and 180 (where negative values are west). The latitude must be between -90 and 90 (negative values are south)
`longitude`	Number
`unit`	String	For `geo-distance-range` facets	The distance unit used in the buckets
`ranges`	Array of Bucket objects	For range facets	Configure bucket ranges to be used when building facets

Bucket

Name	Type	Required	Description
`start`	Number or String	No*	Set the boundaries for the range. The type must be a number for `number-range` facets and time specification for `time-range` facets.
`stop`	Number or String	No*

Name

Type

Required

Description

start

Number or String

No*

Set the boundaries for the range. The type must be a number for number-range facets and

time specification

for time-range facets.

stop

Number or String

No*

* At least one of start and stop must be set.

Spellcheck

Request a did-you-mean spellchecking of a provided query.

Name	Type	Required	Description
`query`	String	Yes	The query string to be spellchecked. Should typically be the raw query a user enters in a search box.

Highlight

Name	Type	Required	Description
`field`	String	Yes	The name of the field
`start`	String	Yes	Inserted at the beginning of the highlighted section
`stop`	String	Yes	Inserted at the end of the highlighted section
`length`	Number	No	Limit the number of characters of the highlighted section

Sort

Name	Type	Required	Description
`type`	String	Yes	The type of the sort. Either `score`, string, `number`, `time` or `geo-distance`
`order`	String	Yes	The sort order. Either `ascending` or `descending`
`field`	String	For `string`, `number` and `geo-distance` sort	The name of the field. Not supported for some free text fields (e.g. `body`, `title`, `heading`, `teaser`). For type `time`, `timestamp` (last updated) is the default field.
`longitude`, `latitude`	Number	For `geo-distance` sort	The latitude/longitude of the origin point, which will be used when calculating the distance to documents. The longitude must be between -180 and 180 (where negative values are west). The latitude must be between -90 and 90 (negative values are south)

Response

Name	Type	Required	Description
`totalCount`	Number	Yes	The total number of matching documents, independent of facets.
`matches`	Array of Match objects	Yes	The returned matches
`facets`	Array of Facet objects	No	The facets, if requested, returned in the same order as the request
`spellcheck`	Array of Spellcheck result objects	No	The possible spellcheck corrections, if requested. Possibly empty if no relevant corrections are found. For did-you-mean spellchecking (the type currently supported by this API), there will not be more than a single result.

Match

Name	Type	Required	Description
`id`	String	Yes	The document ID
`siteId`	String	Yes	The siteId where the document was found
`score`	Number	No	The score for the document, if score sort was used
`fields`	Array of Field objects	Yes	The document fields
`highlights`	Array of Highlight objects	No	The highlights for the document, if requested
`explanation`	Explanation object	No	Will only be set when search is made with `?debug=true`. Provides an explanation for the ranking of this match, showing the contribution of each relevant pair of field and query term.

Explanation

Name	Type	Required	Description
`score`	String	Yes	Final score of the match.
`scoreBeforeRank`	Any	No	The score before the rank algorithm is applied. Only included if rank is provided.
`fields`	Array of Object	Yes	Contains a `score` for each relevant pair of `field` and query `term`. These scores sum up to the total score of the match.

JSON

{
 "explanation": {
 "score": 30.0,
 "scoreBeforeRank": 1.0,
 "fields": [
 {
 "field": "xxx-tag",
 "term": "sports",
 "score": 0.25
 },
 {
 "field": "xxx-tag",
 "term": "illustrated",
 "score": 0.25
 },
 {
 "field": "title",
 "term": "sports",
 "score": 0.5
 }
 ]
 }
}

Field

Name	Type	Required	Description
`field`	String	Yes	The field's name
`value`	Any	Yes	The field's value

Highlight

Name	Type	Required	Description
`field`	String	Yes	The name of the field
`highlight`	String	Yes	The content of the field with highlight

Name	Type	Required	Description
`buckets`	Array of Bucket objects	Yes	The list of buckets for the facet. Buckets are returned in the requested order.

Bucket

Name	Type	Required	Description
`label`	String	Yes	The label of the bucket. For `string` facets this is the string itself. For `number-range` and `time-range` facets this is a label based on the bucket boundaries
`count`	Number	Yes	The number of documents in the bucket

Spellcheck

Name	Type	Required	Description
`term`	String	Yes	The term that is spellchecked. For did-you-mean spellchecking (the type currently supported by this API), the term is always the entire query.
`suggestions`	Array of suggestion objects	Yes	Non-empty list of did-you-mean spellcheck suggestions for the given term. Ordered by relevancy, with the most relevant suggestion first.

Suggestion

Name	Type	Required	Description
`term`	String	Yes	The spellcheck suggestion.

Basic example

Bash

cx.py /document/search '{"siteIds":["99999999","8888888"],"query":"query(\"2016 NFL playoffs schedule\")"}'
{
 "totalCount": 5,
 "matches": [
 {
 "id": "abeddbf210aa0160c0418ff2c3c3b4895459e1a7",
 "siteId": "9999999999",
 "score": 1.1385926,
 "fields": [
 {
 "field": "author",
 "value": "associated press"
 },
 {
 "field": "body",
 "value": [
 "Wild-card Playoffs",
:
:

Advanced Query Language

One of the main advantages of a query language is the flexibility it provides for you to construct complex search requests. Understanding the Advanced Query Language well allows you to construct queries containing parameters such as:

Single words or phrases.
Filters for textual metadata.
Range filters for numeric data, including dates.
Boosting different parts of the query differently against the target documents.
Nested boolean logic combining all of the above.

Handling special characters in user queries

Most characters are handled literally when passed through the query parameter, yet there are a few exceptions listed in this table below. When developing your search application, you must anticipate and properly handle the special characters listed below, or your queries will fail.

Character	Description
`\`	A backslash is used as the escape character for the below characters. Hence it must itself be escaped if present in a user query. To escape the backslash itself, it must be passed like this `\\`
*	Wildcard means all content. If you want to search `` as character, you need to escape it with backslash like this `\`
"	Any string passed as part of the query is quoted by double quotation (`e.g.` `query("ford")`). So if the user passes double quotes as part of the search terms, it must be escaped. You can escape double quotes in query content with backslash like this `\"`

Character

Description

\

A backslash is used as the escape character for the below characters. Hence it must itself be escaped if present in a user query. To escape the backslash itself, it must be passed like this \\

Wildcard means all content. If you want to search * as character, you need to escape it with backslash like this \*

Any string passed as part of the query is quoted by double quotation (e.g.

query("ford")). So if the user passes double quotes as part of the search terms, it must be escaped. You can escape double quotes in query content with backslash like this \"

Query operator

The query operator is used to specify multiple query fragments that can contain anything from a very single keyword targeting all searchable content to complex phrases targeting different parts of the document with different weight, giving different parts of the query different weight as well. Matching will be performed against normalized content (i.e. case/accent insensitive, depending on the index language). If exact match on a field value is needed, use the filter operator.

The query operator has the following syntax:

query(<field>^<boost>:"<query content>", token-op=<token operator>)

The following table provides more details on each of the available parameters listed above:

Parameter	Default	Meaning	Examples
`field`	_all	This parameter defines what parts of the content should checked when looking for the <query content> specified. If this parameter is omitted, it will default to the reserved value `_all`, which will target all searchable string fields. You can use this parameter to define one or more fields that should be searched on, which must be provided as a comma separated list.	query("ford") query(title:"ford") query(_all,body,description:"ford")
`boost`	1	Defines how much weight should be applied to this particular part of the query, and therefore can be used to define which fields are more important. A negative value will down-boost a field, making it less important. When defining multiple fields as mentioned above, each field get their own boost.	query(name^2:"mustang") query(title^5,description^2:"mustang")
`query content`	N/A	One or more words When passing multiple words, by default all of them must be found (see token operator below). The special value `*` can be provided through this parameter to return all content.	query("market research") query("*")
`token operator`	and	`and` (default): All the words must be present in the document `or`: One of the words must be present in the document `phrase`: All the words must be present, and in the same order as specified	query("classic dark green",token-op=phrase)

Filter operator

The filter operator have a similar format and use as the query operator. However, while a query condition will both affect recall (which documents are returned) and relevancy (which order the documents come back), a filter condition will only affect recall. In other words, a filter will not affect score of hits.

All values are strongly typed (i.e. filtering for a string will not match on a number field, event though the string looks like a number). The following types are supported:

Type	Description	Example
`string`	A string for filtering on exact string values without any normalization	filter(string-field:"example") filter(string-field:["foo", "bar", "baz"])
`number`	Integer or float	filter(number-field < 42) filter(number-field > 13.37)
`time`	A time/date formatted according to Traffic time specification . Note that time is queried with a resolution of seconds, even if millisecond time specifications are allowed.	filter(time-field > time("-24h")) filter(time-field:range[time("2013-01-01T00:00:00Z"), time("2014-01-11T00:00:00Z")])
`set`	A string for exact lookup in a field of type set	filter(set-field:contains("foo"))

Value filter

A value filter only works on exact values and no matching against normalized content will happen. When filtering on multiple values, all values must be of the same type. Documents that contain any one of the specified values will match. It has the following format:

filter(<field>:<value>)
filter(<field>:[<value1>,...,<valueN>])

Open range filter

The open range filters have the following format:

filter(<field><operator><value>)

Where these are the valid options for the operator parameter:

Operator	Description
`>`	Greater than
`>=`	Greater than or equal to
`<`	Less than
`<=`	Less than or equal to

Example - combining filter with relative time and fielded query

Bash

cx.py /document/search '{"siteId":"1234","resultFields":["url","timestamp","recs-publishtime","xxx-tag"],"filter":"filter(recs-publishtime > time(\"-300h\"))","query":"query(xxx-tag:\"nyhetsvarsel\")"}'

Closed range filter

The closed range filters have the following format:

filter(<field>:range<left operator><value1>,<value2><right operator>)

Where these are the valid options for the operator parameter:

Operator	Description
`(`	Greater than
`[`	Greater than or equal to
`)`	Less than
`]`	Less than or equal to

Geo box filter

When filtering for geo locations, it's often useful to find all points inside a bounding box. This can be accomplished using a geo bounding box filter, which has much better performance than the naive approach of using range filters. The geo bounding box filter has the following format:

filter(<field>:geobox[[<top left longitude>,<top left latitude>],[<bottom right longitude>,<bottom right latitude>]])

Contains filter

Fields of type "set" (multi value fields) can be filtered on by using the "contains" operator.

filter(<field>:contains(<value>))

Boolean Operators combining "query" or "filter"

The Boolean operators allow you to combine multiple query or filter operators to build complex search requests.

Operator	Description
`AND`	conditions are mandatory
`NOT`	condition after this operator must not be matched
`OR`	conditions are optional

# query examples
"query":"NOT query(...)"

"query":"NOT query(...) AND query(...)"

# filter examples
"filter":"filter(...) AND filter(...)"

"filter":"filter(...) OR filter(...)"

Last updated: December 28, 2023