Search Request JSON Properties

Capella Operational

reference

You can add additional properties to a Search request to control how the Search Service returns results.

The following is an example Search request:

{
    "query": {
        "must": {
            "conjuncts":[
                {
                    "field": "free_breakfast",
                    "bool": false
                },
                {
                    "field": "ratings.Cleanliness",
                    "min": 1,
                    "max": 3,
                    "inclusive_min": true,
                    "inclusive_max": false
                }
            ]
        },
        "must_not": {
            "disjuncts": [
                {
                    "field": "geojson",
                    "geometry": {
                        "shape": {
                            "coordinates": [-2.2450285424707204, 53.48503270828377],
                            "type": "circle",
                            "radius": "100mi"
                        },
                        "relation": "within"
                    }
                }
            ],
            "min": 1
        },
        "should": {
            "disjuncts": [
                {
                    "match_phrase": "very nice",
                    "field": "reviews.content"
                }
            ]
        }
    },
    "knn": [
        {
            "k": 10,
            "field": "vector_field",
            "vector": [ 0.707106781186548, 0, 0.707106781186548 ]
        }
    ],
    "ctl": {
        "timeout": 10000,
        "consistency": {
            "vectors": {
                "searchIndexName": {
                    "607/205096593892159": 2,
                    "640/298739127912798": 4  
                }
            },
            "level": "at_plus",
            "results": "complete"
        }
    },
    "size": 10,
    "from": 0,
    "highlight": {

        "style": "html",
        "fields": ["textField"]

    },
    "fields": ["textField"],
    "facets": {

        "field1": {
            "size": 5,
            "field": "field1"
        },

        "field2": {
            "size": 5,
            "field": "field2",
            "numeric_ranges": [
                {

                    "name": "high",
                    "min": 7,
                    "max": 10

                },
                {

                    "name": "low",
                    "min": 0,
                    "max": 7

                }
             ]
        },

        "field3": {
            "size": 10,
            "field": "dateField",
            "date_ranges": [
                {
                    "name": "old",
                    "start": "2020-12-31",
                    "end": "2023-12-31"
                },
                {
                    "name": "new",
                    "start": "2023-12-31",
                    "end": "2024-12-31"
                }  
            ]
        }

    },
    "explain": true,
    "sort": [

        "field1",
            {
                "by": "field",
                "field": "field2",
                "desc": false,
                "mode": "max",
                "missing": "last",
                "type": "number"
            },
            "-_score",
            "-_id"
            
    ],
    "includeLocations": false,
    "score": "none",
    "search_after": ["field1Value", "5", "10.033205341869529", "1234"],
    "search_before": ["field1Value", "5", "10.033205341869529", "1234"],
    "limit": 10,
    "offset": 0,
    "collections": ["collection1", "collection2"]
}

A Search request can contain the following properties:

Property Type Required? Description

query

Object

Regular or Hybrid Search Only

An object that contains the properties for one of the supported query types.

The query object is required if you want to run a regular search, or a hybrid search that includes a Vector Search query. If your cluster is running Couchbase Server version 7.6.2 and later, you do not need to include the query object for a pure Vector Search query.

For more information about how to configure the query object, see Query Object.

knn

Array of Objects

Vector Only

An array that contains objects that describe a Vector Search query.

For more information about how to configure the objects inside a knn array, see Knn Objects.

ctl

Object

An object that contains properties for query consistency.

For more information about how to configure Search query consistency inside the ctl object, see Ctl Object.

size/limit

Integer

Set the total number of results to return for a single page of search results.

If you provide both the size and limit properties, the Search Service uses the size value.

If you do not provide a from, size, or other pagination settings in your query, the Search Service defaults to a size value of 10 and a from value of 0. This means the Search Service does not offset results, and returns the first 10 matches to your query.

from/offset

Integer

Set an offset value to change where pagination starts for search results, based on the Search query’s Sort Object.

For example, if you set a size value of 5 and a from value of 10, the Search query returns results 11 through 15 on a page.

If you provide both the from and offset properties, the Search Service uses the from value.

highlight

Object

Contains properties to control search result highlighting.

For more information about how to configure highlighting in Search results, see Highlight Object.

fields

Array

An array of strings to specify each indexed field you want to return in search results.

You must add a field and its contents to a Search index to view it in search results or add it to the fields array.

facets

Object

Contains {facet-name} objects to define each facet you want to return with search results.

The Search Service supports the following facet types:

Term Facet: Counts the documents that have the same value for a specified field.
Numeric Range Facet: Counts the documents with numeric field values that are greater than or less than a specified range or ranges.
Date Range Facet: Counts the documents with date field values that are earlier or later than a specified range or ranges.

For more information, about how to configure the different facet types inside the facets object, see {facet-name} Object.

explain

Boolean

To create an explanation for a search result’s score in search results, set explain to true.

To turn off explanations for search result scoring, set explain to false.

sort

Array

Contains an array of strings or JSON objects to set how to sort search results. By default, the Search Service sorts results based on score values, from highest to lowest.

The strings can be:

{field_name}: Specify the name of a field to use to sort the search results.
_id: Use the document’s identifier to sort the search results.
_score: Use the document’s score from the Search query to sort the search results.

For more information about the properties for a sort JSON object, see Sort Object.

includeLocations

Boolean

To return the position of each occurrence of a search term inside a document, set includeLocations to true.

You must have Include Term Vectors enabled or the include_term_vectors property set to true on a field to use includeLocations. For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties.

To turn off term locations, set includeLocations to false.

score

String

To turn off document relevancy scoring in search results, set score to none.

To turn on document relevancy scoring in search results, remove the score property.

search_after

Array

If you use search_after in a search request, you cannot use search_before. Both properties are included in the example code to show the correct syntax.

Use search_after with from/offset and sort to control pagination in search results.

For example, if you had a set of 10 documents to sort based on _id values of 1-10, with from set to 2 and search_after set to 8, documents 9-10 appear on the same page.

You must give a value for each string or JSON object in the sort array to the search_after array. The Search Service starts search result pagination after the document with those values.

You must provide the values in the same order that they appear in the sort array. Your sort array must force a total order on your search results.

Use search_after to make the memory requirements of deeper page searches more manageable, when compared to using only from/offset. search_after lets you start your search results from a specific result, rather than needing to process a number of search results to skip.

search_before

Array

If you use search_before in a search request, you cannot use search_after. Both properties are included in the example code to show the correct syntax.

Use search_before with from/offset and sort to control pagination in search results.

For example, if you had a set of 10 documents to sort based on _id values of 1-10, with from set to 2 and search_before set to 8, documents 2-6 appear on the same page.

You must give a value for each string or JSON object in the sort array to the search_before array. The Search Service starts search result pagination before the document with those values.

You must provide the values in the same order that they appear in the sort array. Your sort array must force a total order on your search results.

Use search_before to make the memory requirements of deeper page searches more manageable, when compared to using only from/offset. search_before lets you start your search results back from a specific result, rather than needing to process a number of search results to skip.

collections

Array

Contains an array of strings that specify the collections where you want to run the query.

Knn Objects

Each object inside the knn array in a Search query describes a Vector Search query.

Add the knn array with at least one object to run a Vector Search query:

    "knn": [
        {
            "k": 10,
            "field": "vector_field",
            "vector": [ 0.707106781186548, 0, 0.707106781186548 ]
        }
    ],

If your cluster is running Couchbase Server version 7.6.2 and later, to return only results from your Vector Search query, do not include a query object with your Search request. To run a hybrid query that uses regular Search Service parameters together with Vector Search to return results, see the Query Object section.

An object in the knn array can contain the following properties:

Property Type Required? Description

Integer

Yes

Enter the total number of results that you want to return from your Vector Search query.

The Search Service returns the k closest vectors to the vector given in vector or, if your cluster is running Couchbase Server version 7.6.2 or later, vector_base64.

The size or limit property overrides any value set in k.

field

String

Yes

The name of the field that contains the vector data you want to search.

vector

Array of Floats

Must have vector or vector_base64

Enter the vector that you want to compare to the vector data in field.

The Search Service uses the similarity metric defined in the Search index definition to return the k closest vectors from the Search index.

The vector in your Search query must match the dimension of the vectors stored in your Search index. If the dimensions do not match, your Search query does not return any results. For more information about the dimension value, see the dims property or the Dimension option in the UI.

vector_base64

Base64 Encoded String

Must have vector or vector_base64

If your cluster is running Couchbase Server version 7.6.2 or later, enter a vector, encoded as a base64 string, that you want to compare to the vector data in field.

The Search Service uses the similarity metric defined in the Search index definition to return the k closest vectors from the Search index.

Query Object

Use the query object to set the specific details of your Search query.

Use the properties in the query object to control search result rankings, add multiple subqueries, and more.

{
    "query": {
        "must": {
            "conjuncts":[
                {
                    "field": "free_breakfast",
                    "bool": false
                },
                {
                    "field": "ratings.Cleanliness",
                    "min": 1,
                    "max": 3,
                    "inclusive_min": true,
                    "inclusive_max": false
                }
            ]
        },
        "must_not": {
            "disjuncts": [
                {
                    "field": "geojson",
                    "geometry": {
                        "shape": {
                            "coordinates": [-2.2450285424707204, 53.48503270828377],
                            "type": "circle",
                            "radius": "100mi"
                        },
                        "relation": "within"
                    }
                }
            ],
            "min": 1
        },
        "should": {
            "disjuncts": [
                {
                    "match_phrase": "very nice",
                    "field": "reviews.content"
                }
            ]
        }
    },

Boolean Queries

Use any of the following properties to run a boolean query. A boolean query searches for a combination of queries that a document must match to be included in search results.

Boolean queries use a compound query array inside the must, must_not and should objects to set the queries a document must match.

Property Type Description Examples

Property	Type	Description	Examples
must	Object	Use a `must` object to create a boolean query. A `must` object must contain a conjuncts array. The array lists all the queries that must have a match in a document to include the document in search results. For example, a query could have a `must` object with 2 queries in a `conjuncts` array. The Search Service must find a match for both those queries in a document to include it in search results.	reviews.content field must contain "location" and the phrase "nice view" `{ "query":{ "must":{ "conjuncts":[ { "field": "reviews.content", "match": "location" }, { "field":"reviews.content", "match_phrase": "nice view" } ] } } }`
must_not	Object	Use a `must_not` object to create a boolean query. A `must_not` object must contain a disjuncts array. The array lists all the queries that must have a match in a document to include the document in search results. For example, a query could have a `must_not` object with 3 queries in a `disjuncts` array. The Search Service must not find a match for any of the 3 queries in a document to include it in search results.	free_breakfast field must not be false and reviews.Cleanliness field must not be between 1 and 3 `{ "query":{ "must_not":{ "disjuncts":[ { "field": "free_breakfast", "bool": false }, { "field": "ratings.Cleanliness", "min": 1, "max": 3 } ] } } }`
should	Object	Use a `should` object to create a boolean query. A `should` object must contain a disjuncts array. The array lists all the queries that must have a match in a document to score the document higher in search results. A document can be included in search results if it does not match the query or queries in a `should` object. The document scores higher in search results if it does match the query.	free_parking and free_internet fields should be true `{ "query":{ "should":{ "disjuncts":[ { "field": "free_parking", "bool": true }, { "field": "free_internet", "bool": true } ], "min": 1 } } }`

must

Object

Use a must object to create a boolean query.

A must object must contain a conjuncts array. The array lists all the queries that must have a match in a document to include the document in search results.

For example, a query could have a must object with 2 queries in a conjuncts array. The Search Service must find a match for both those queries in a document to include it in search results.

reviews.content field must contain "location" and the phrase "nice view"

{
    "query":{
        "must":{
            "conjuncts":[
                {
                    "field": "reviews.content", 
                    "match": "location"
                },
                {
                    "field":"reviews.content",
                    "match_phrase": "nice view"
                }
            ]
        }
    }
}

must_not

Object

Use a must_not object to create a boolean query.

A must_not object must contain a disjuncts array. The array lists all the queries that must have a match in a document to include the document in search results.

For example, a query could have a must_not object with 3 queries in a disjuncts array. The Search Service must not find a match for any of the 3 queries in a document to include it in search results.

free_breakfast field must not be false and reviews.Cleanliness field must not be between 1 and 3

{
    "query":{
        "must_not":{
            "disjuncts":[
                {
                    "field": "free_breakfast",
                    "bool": false
                },
                {
                    "field": "ratings.Cleanliness",
                    "min": 1,
                    "max": 3
                }
            ]
        }
    }
}

should

Object

Use a should object to create a boolean query.

A should object must contain a disjuncts array. The array lists all the queries that must have a match in a document to score the document higher in search results.

A document can be included in search results if it does not match the query or queries in a should object. The document scores higher in search results if it does match the query.

free_parking and free_internet fields should be true

{
    "query":{
        "should":{
            "disjuncts":[
                {
                    "field": "free_parking",
                    "bool": true
                },
                {
                    "field": "free_internet",
                    "bool": true
                }
            ],
            "min": 1
        }
    }
}

Compound Queries (AND and OR)

Use a compound query array to specify multiple child queries that must have a match in a document for that document to be included in search results.

You must use compound query arrays to run a boolean query, but you can use a compound query array outside of a boolean query.

You can use 2 different types of compound queries:

Property Type Description Examples

Property	Type	Description	Examples
conjuncts	Array	Use the `conjuncts` array to specify multiple child queries in a single `query` object. You can use the `conjuncts` array inside a must object or directly inside a `query` object. If you use the `conjuncts` array, every query object in the array must have a match in a document to include the document in search results. You can create objects in a `conjuncts` array to describe any of the available query types: Analytic Queries Non-Analytic Queries Numeric Range Queries Date Range Queries Term Range Queries Distance/Radius-Based Geopoint Queries Rectangle-Based Geopoint Queries Polygon-Based Geopoint Queries Point GeoJSON Queries LineString GeoJSON Queries Polygon GeoJSON Queries MultiPoint GeoJSON Queries MultiLineString GeoJSON Queries MultiPolygon GeoJSON Queries GeometryCollection GeoJSON Queries Circle GeoJSON Queries Envelope GeoJSON Queries	reviews.date field must be between 2001-10-09 and 2016-10-31 and description field must contain "pool" `{ "query":{ "conjuncts":[ { "field": "reviews.date", "start": "2001-10-09", "end": "2016-10-31", "inclusive_start": false, "inclusive_end": false }, { "field": "description", "match": "pool" } ] } }`
disjuncts	Array	Use the `disjuncts` array to specify multiple child queries in a single `query` object. You can use the `disjuncts` array inside a must_not object, should object, or directly inside a `query` object. Use a `min` property to set the number of query objects from the `disjuncts` array that must have a match in a document. If a document does not match the `min` number of query objects, the Search Service does not include the document in search results. You can create objects in a `disjuncts` array to describe any of the available query types: Analytic Queries Non-Analytic Queries Numeric Range Queries Date Range Queries Term Range Queries Distance/Radius-Based Geopoint Queries Rectangle-Based Geopoint Queries Polygon-Based Geopoint Queries Point GeoJSON Queries LineString GeoJSON Queries Polygon GeoJSON Queries MultiPoint GeoJSON Queries MultiLineString GeoJSON Queries MultiPolygon GeoJSON Queries GeometryCollection GeoJSON Queries Circle GeoJSON Queries Envelope GeoJSON Queries	free_parking field must be true or checkin field must be "1PM" `{ "query":{ "disjuncts":[ { "field": "free_parking", "bool": true }, { "field": "checkin", "match": "1PM" } ], "min": 1 } }`

conjuncts

Array

Use the conjuncts array to specify multiple child queries in a single query object.

You can use the conjuncts array inside a must object or directly inside a query object.

If you use the conjuncts array, every query object in the array must have a match in a document to include the document in search results.

You can create objects in a conjuncts array to describe any of the available query types:

Analytic Queries
Non-Analytic Queries
Numeric Range Queries
Date Range Queries
Term Range Queries
Distance/Radius-Based Geopoint Queries
Rectangle-Based Geopoint Queries
Polygon-Based Geopoint Queries
Point GeoJSON Queries
LineString GeoJSON Queries
Polygon GeoJSON Queries
MultiPoint GeoJSON Queries
MultiLineString GeoJSON Queries
MultiPolygon GeoJSON Queries
GeometryCollection GeoJSON Queries
Circle GeoJSON Queries
Envelope GeoJSON Queries

reviews.date field must be between 2001-10-09 and 2016-10-31 and description field must contain "pool"

{
    "query":{
        "conjuncts":[
            {
                "field": "reviews.date",
                "start": "2001-10-09",
                "end": "2016-10-31",
                "inclusive_start": false,
                "inclusive_end": false
            },
            {
                "field": "description",
                "match": "pool"
            }
        ]
    }
}

disjuncts

Array

Use the disjuncts array to specify multiple child queries in a single query object.

You can use the disjuncts array inside a must_not object, should object, or directly inside a query object.

Use a min property to set the number of query objects from the disjuncts array that must have a match in a document. If a document does not match the min number of query objects, the Search Service does not include the document in search results.

You can create objects in a disjuncts array to describe any of the available query types:

Analytic Queries
Non-Analytic Queries
Numeric Range Queries
Date Range Queries
Term Range Queries
Distance/Radius-Based Geopoint Queries
Rectangle-Based Geopoint Queries
Polygon-Based Geopoint Queries
Point GeoJSON Queries
LineString GeoJSON Queries
Polygon GeoJSON Queries
MultiPoint GeoJSON Queries
MultiLineString GeoJSON Queries
MultiPolygon GeoJSON Queries
GeometryCollection GeoJSON Queries
Circle GeoJSON Queries
Envelope GeoJSON Queries

free_parking field must be true or checkin field must be "1PM"

{
    "query":{
        "disjuncts":[
            {
                "field": "free_parking",
                "bool": true
            },
            {
                "field": "checkin",
                "match": "1PM"
            }
        ],
        "min": 1
    }
}

Query String Query Syntax

Use the following properties and syntax to run a Query String query.

Query String queries let you express more complex queries with a special syntax. You can reduce the properties you need to specify for a Search query with Query String syntax.

If you do not add any additional Query String syntax to a query, the Search Service interprets the query as a match query. It searches for an exact match to the provided term in any fields that have been added to the default field. For more information about how to configure the default field for your Search index, see Set Search Index General Settings or the default_field property.

Query String syntax is not recommended for use in production environments.

Operator Property Description Examples

Operator	Property	Description	Examples
`^`	See boost.	If you use multiple clauses in a query, you can use the `^` operator to assign the relative importance to a clause. Clauses with a larger number after the `^` operator score higher and appear earlier in search results.	Query String query with a boost on the name field containing pool `{ "query": { "query": "description:pool name:pool^5" } }`
`>`, `>=`, `<`, and `⇐`	See Date Range Queries or Numeric Range Queries.	You can run two types of range queries with the the later than (`>`), later than or equal to (`>=`), earlier than (`<`), and earlier than or equal to (`⇐`) operators: Use the operators with a date value to run a date range query. The Search Service searches for a date value in the specified field that matches the specified operator. Use operators with a numeric value to run a numeric range query. The Search Service searches for a numeric value in the specified field that matches the specified operator.	Query String query for a date in the created field after September 21, 2016 `{ "query": { "query": "reviews.date:>\"2012-09-21\"" } }` Query String query for a rating in the reviews.ratings.Cleanliness field greater than 4 `{ "query": { "query": "reviews.ratings.Cleanliness:>4" } }`
`\`	N/A	Use a backslash character (`\`) to escape characters in a Query String query. You must escape the following characters to search for them literally in a Query String query: Quotes (`"`) Plus sign (`+`) Dash (`-`) Equals sign (`=`) Ampersand (`&`) Caret (`^`) Asterix (`*`) Pipe (`\|`) Greater than and less than symbol (`>` and `<`) Exclamation mark (`!`) Question mark (`?`) Parentheses (`( )`) Curly braces (`{ }`) Square brackets (`[ ]`) Single or double backslash (`\`) Forward slash (`/`) Tilde (`~`) Colon (`:`)	Query String match query with escaped exclamation mark (!) `{ "query": { "query": "\!" } }` Query String match phrase query with escaped quotation mark (") `{ "query": { "query": "\" a phrase in quotes \"" } }`
`{field-name}:`	See field.	Set the field in a document where the Search Service should search for your query by adding a field name and a colon to the start of a search term. Use dot notation for the field name. For example, `parentField.childField`. The Query String syntax does not support SQL++ field syntax. For example, you cannot use `[*]` or `[3]` as array locations in a field name path. If your cluster is running Couchbase Server version 7.6.2 or later and you want to search your document metadata, you must prefix the metadata field’s name with `_$xattrs`.	Query String query for "pool" in the description field `{ "query": { "query": "description:pool" } }` (Version 7.6.2) Query String query for "sample" in an XATTRs description field `{ "query": { "query": "_$xattrs.description:sample" } }`
`+` and `-`	See the must property, must_not property, and should property.	Use the `+` and `-` operators before a clause in a Query String query to run a boolean query: The `+` operator adds the clause to the `MUST` list of a boolean query. The `-` operator adds the clause to the `MUST_NOT` list of a boolean query. The Search Service adds any additional query clauses not marked with a `+` or a `-` operator to the `SHOULD` list of a boolean query. Documents that match the `SHOULD` list of queries score higher than those that do not return a match.	Query String query with boolean syntax `{ "query": { "query": "+description:pool -continental breakfast" } }` The Query String syntax specifies that: The document must have `pool` in the `description` field. The document must not have `continental` in the `default` field. The document should have `breakfast` in the `default` field.
`""`	See match_phrase property.	Surround a search term in quotation marks (`" "`) to run a match phrase query. To use a match phrase query: You must specify a field to search with the field property or the {field-name} syntax in your search query. You must have Include Term Vectors enabled or the `include_term_vectors` property set to `true` on the field you want to search. For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties. The Search Service searches for exact matches to the phrase you specify.	Query String match phrase query for "continental breakfast" `{ "query": { "query": "continental breakfast" } }`

^

See boost.

If you use multiple clauses in a query, you can use the ^ operator to assign the relative importance to a clause.

Clauses with a larger number after the ^ operator score higher and appear earlier in search results.

Query String query with a boost on the name field containing pool

{
    "query": {
        "query": "description:pool name:pool^5"
    }
}

>, >=, <, and ⇐

See Date Range Queries or Numeric Range Queries.

You can run two types of range queries with the the later than (>), later than or equal to (>=), earlier than (<), and earlier than or equal to (⇐) operators:

Use the operators with a date value to run a date range query. The Search Service searches for a date value in the specified field that matches the specified operator.
Use operators with a numeric value to run a numeric range query. The Search Service searches for a numeric value in the specified field that matches the specified operator.

Query String query for a date in the created field after September 21, 2016

{
    "query": {
        "query": "reviews.date:>\"2012-09-21\""
    }
}

Query String query for a rating in the reviews.ratings.Cleanliness field greater than 4

{
    "query": {
        "query": "reviews.ratings.Cleanliness:>4"
    }
}

\

N/A

Use a backslash character (\) to escape characters in a Query String query.

You must escape the following characters to search for them literally in a Query String query:

Quotes (")
Plus sign (+)
Dash (-)
Equals sign (=)
Ampersand (&)
Caret (^)
Asterix (*)
Pipe (|)
Greater than and less than symbol (> and <)
Exclamation mark (!)
Question mark (?)
Parentheses (( ))
Curly braces ({ })
Square brackets ([ ])
Single or double backslash (\)
Forward slash (/)
Tilde (~)
Colon (:)

Query String match query with escaped exclamation mark (!)

{
    "query": {
        "query": "\!"
    }
}

Query String match phrase query with escaped quotation mark (")

{ 
    "query": {
        "query": "\" a phrase in quotes \""
    }
}

{field-name}:

See field.

Set the field in a document where the Search Service should search for your query by adding a field name and a colon to the start of a search term.

Use dot notation for the field name. For example, parentField.childField.

The Query String syntax does not support SQL++ field syntax. For example, you cannot use [*] or [3] as array locations in a field name path.

If your cluster is running Couchbase Server version 7.6.2 or later and you want to search your document metadata, you must prefix the metadata field’s name with _$xattrs.

Query String query for "pool" in the description field

{ 
    "query": {
        "query": "description:pool"
    }
}

(Version 7.6.2) Query String query for "sample" in an XATTRs description field

{ 
    "query": {
        "query": "_$xattrs.description:sample"
    }
}

+ and -

See the must property, must_not property, and should property.

Use the + and - operators before a clause in a Query String query to run a boolean query:

The + operator adds the clause to the MUST list of a boolean query.
The - operator adds the clause to the MUST_NOT list of a boolean query.
The Search Service adds any additional query clauses not marked with a + or a - operator to the SHOULD list of a boolean query.

Documents that match the SHOULD list of queries score higher than those that do not return a match.

Query String query with boolean syntax

{
    "query": {
        "query": "+description:pool -continental breakfast"
    }
}

The Query String syntax specifies that:

The document must have pool in the description field.
The document must not have continental in the default field.
The document should have breakfast in the default field.

""

See match_phrase property.

Surround a search term in quotation marks (" ") to run a match phrase query.

To use a match phrase query:

You must specify a field to search with the field property or the {field-name} syntax in your search query.
You must have Include Term Vectors enabled or the include_term_vectors property set to true on the field you want to search.

For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties.

The Search Service searches for exact matches to the phrase you specify.

Query String match phrase query for "continental breakfast"

{ 
    "query": {
        "query": "continental breakfast"
    }
}

Analytic Queries

Analytic queries use an analyzer to analyze the contents of your Search query, and find a match in the documents inside your Search index.

For more information about analyzers, see Customize a Search Index with the Capella UI.

From Couchbase Server 7.6 and later, when you run a Search query with the SQL++ Search Function, the analyzer used in your Analytic query does not need to match the analyzer used in the Search index.

Property Type Description Examples

Property	Type	Description	Examples
match	String	Use the `match` property to run a match query. The Search Service searches for an exact match to the specified term inside the Search index’s default field. You can set a specific field to search with the field property. You can change the matching behavior by using the fuzziness property. You cannot include spaces inside the string you provide to the `match` property without specifying the operator property, which tells the Search Service how to interpret the string. For more information about the properties you can specify with a match query, see Additional Query Object Properties.	Match query for "best" or "great" in reviews.content with the "standard" analyzer `{ "query": { "match": "best great", "field": "reviews.content", "analyzer": "standard", "operator": "or" } }`
match_phrase	String	Use the `match_phrase` property to run a match phrase query. The Search Service searches for exact matches to the phrase you specify. Unlike a `match` query string, a match_phrase query string can contain spaces without using the operator property. To use a match phrase query: You must specify a field to search with the field property or the {field-name} syntax in your search query. You must have Include Term Vectors enabled or the `include_term_vectors` property set to `true` on the field you want to search. For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties. For more information about the additional properties you can specify with a match phrase query, see Additional Query Object Properties.	Match phrase query for "very nice" in reviews.content `{ "query": { "match_phrase": "very nice", "field": "reviews.content" } }`

match

String

Use the match property to run a match query. The Search Service searches for an exact match to the specified term inside the Search index’s default field.

You can set a specific field to search with the field property.

You can change the matching behavior by using the fuzziness property.

You cannot include spaces inside the string you provide to the match property without specifying the operator property, which tells the Search Service how to interpret the string.

For more information about the properties you can specify with a match query, see Additional Query Object Properties.

Match query for "best" or "great" in reviews.content with the "standard" analyzer

{
    "query": {
        "match": "best great",
        "field": "reviews.content",
        "analyzer": "standard",
        "operator": "or"
    }
}

match_phrase

String

Use the match_phrase property to run a match phrase query. The Search Service searches for exact matches to the phrase you specify.

Unlike a match query string, a match_phrase query string can contain spaces without using the operator property.

To use a match phrase query:

You must specify a field to search with the field property or the {field-name} syntax in your search query.
You must have Include Term Vectors enabled or the include_term_vectors property set to true on the field you want to search.

For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties.

For more information about the additional properties you can specify with a match phrase query, see Additional Query Object Properties.

Match phrase query for "very nice" in reviews.content

{
    "query": {
        "match_phrase": "very nice",
        "field": "reviews.content"
    }
}

Non-Analytic Queries

Use Non-Analytic queries to run a search query without using an analyzer on the contents of your Search query.

For more information about analyzers, see Customize a Search Index with the Capella UI.

From Couchbase Server 7.6 and later, when you run a Search query with the SQL++ Search Function, you do not need to use the keyword analyzer in your Search index to run a non-analytic query.

Property Type Description Examples

Property	Type	Description	Examples
bool	Boolean	Use the `bool` property to query a field that contains a boolean value. Use the field property and set the `bool` property to `true` or `false` to run a search. The Search Service does not use any analyzers on the contents of your query. For more information about the additional properties you can specify with a bool query, see Additional Query Object Properties.	Search for documents where the pets_ok field is true `{ "query": { "field": "pets_ok", "bool": true } }`
prefix	String	Use the `prefix` property to run a prefix query. Set the property to a string to return matches for any term that starts with that string in search results. For example, you could set the `prefix` property to `inter` to return matches for `interview`, `internal`, `interesting`, and so on. If you use the `prefix` property, the Search Service does not use any analyzers on the contents of your query text. For more information about the additional properties you can specify with a prefix query, see Additional Query Object Properties.	Search for terms that start with "inter" inside the reviews.content field `{ "query": { "prefix": "inter", "field": "reviews.content" } }`
regexp	String	Use the `regexp` property to run a regular expression query. Set the property to a regular expression to return matches for that regular expression in search results. If you use the `regexp` property, the Search Service does not use any analyzers on the contents of your query text. For more information about the additional properties you can specify with a regexp query, see Additional Query Object Properties.	Search for terms that match the regular expression "plan.+" inside the reviews.content field `{ "query": { "regexp": "plan.+", "field": "reviews.content" } }`
term	String	Use the `term` property to run a term query. The Search Service searches for an exact match for the text you provide in the `term` property. You can change the matching behavior by using the fuzziness property. If you use the `term` property, the Search Service does not use any analyzers on the contents of your query text. For more information about the additional properties you can specify with a term query, see Additional Query Object Properties.	Search for terms that match the term "interest" inside the reviews.content field with a fuzziness of 2 `{ "query": { "term": "interest", "field": "reviews.content", "fuzziness": 2 } }`
terms	Array	Use the `terms` array to run a phrase query. The Search Service searches for the strings you provide in the `terms` array in the specified order. Unlike the match_phrase property, the `terms` array does not use any analyzers on the contents of your query text. For example, set the `terms` array to `["nice", "view"]`. The Search Service looks for any occurrences of `nice` in a document that are followed by an occurrence of `view`. To use a phrase query: You must set the field property in your search query. You must have Include Term Vectors enabled or the `include_term_vectors` property set to `true` on the field you want to search. For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties.	Search for the phrase "nice view" in the reviews.content field `{ "query": { "terms": ["nice", "view"], "field": "reviews.content" } }`
wildcard	String	Use the `wildcard` property to run a wildcard query. Set the property to a regular expression that includes a wildcard character in the middle or end of a search term: Use `?` to allow a match to any single character. Use `` to allow a match to zero or many characters. For example, you could set the `wildcard` property to `inter` to return matches for `interview`, `interject`, `internal`, and so on. You cannot place the wildcard character at the start of the search term. If you use the `wildcard` property, the Search Service does not use any analyzers on the contents of your query text.	Search for any terms that start with "inter" followed by zero or more characters in the reviews.content field `{ "query": { "wildcard": "inter*", "field": "reviews.content" } }`

bool

Boolean

Use the bool property to query a field that contains a boolean value.

Use the field property and set the bool property to true or false to run a search.

The Search Service does not use any analyzers on the contents of your query.

For more information about the additional properties you can specify with a bool query, see Additional Query Object Properties.

Search for documents where the pets_ok field is true

{ 
    "query": {
        "field": "pets_ok",
        "bool": true
    }
}

prefix

String

Use the prefix property to run a prefix query.

Set the property to a string to return matches for any term that starts with that string in search results.

For example, you could set the prefix property to inter to return matches for interview, internal, interesting, and so on.

If you use the prefix property, the Search Service does not use any analyzers on the contents of your query text.

For more information about the additional properties you can specify with a prefix query, see Additional Query Object Properties.

Search for terms that start with "inter" inside the reviews.content field

{
    "query": {
        "prefix": "inter",
        "field": "reviews.content"
    }
}

regexp

String

Use the regexp property to run a regular expression query.

Set the property to a regular expression to return matches for that regular expression in search results.

If you use the regexp property, the Search Service does not use any analyzers on the contents of your query text.

For more information about the additional properties you can specify with a regexp query, see Additional Query Object Properties.

Search for terms that match the regular expression "plan.+" inside the reviews.content field

{ 
    "query": {
        "regexp": "plan.+",
        "field": "reviews.content"
    }
}

term

String

Use the term property to run a term query.

The Search Service searches for an exact match for the text you provide in the term property.

You can change the matching behavior by using the fuzziness property.

If you use the term property, the Search Service does not use any analyzers on the contents of your query text.

For more information about the additional properties you can specify with a term query, see Additional Query Object Properties.

Search for terms that match the term "interest" inside the reviews.content field with a fuzziness of 2

{ 
    "query": {
        "term": "interest",
        "field": "reviews.content",
        "fuzziness": 2
    }
}

terms

Array

Use the terms array to run a phrase query. The Search Service searches for the strings you provide in the terms array in the specified order.

Unlike the match_phrase property, the terms array does not use any analyzers on the contents of your query text.

For example, set the terms array to ["nice", "view"]. The Search Service looks for any occurrences of nice in a document that are followed by an occurrence of view.

To use a phrase query:

You must set the field property in your search query.
You must have Include Term Vectors enabled or the include_term_vectors property set to true on the field you want to search.

For more information about how to enable term vectors, see Child Field Options or Search Index JSON Properties.

Search for the phrase "nice view" in the reviews.content field

{ 
    "query": {
        "terms": ["nice", "view"],
        "field": "reviews.content"
    }
}

wildcard

String

Use the wildcard property to run a wildcard query.

Set the property to a regular expression that includes a wildcard character in the middle or end of a search term:

Use ? to allow a match to any single character.
Use * to allow a match to zero or many characters.

For example, you could set the wildcard property to inter* to return matches for interview, interject, internal, and so on.

You cannot place the wildcard character at the start of the search term.

If you use the wildcard property, the Search Service does not use any analyzers on the contents of your query text.

Search for any terms that start with "inter" followed by zero or more characters in the reviews.content field

{ 
    "query": {
        "wildcard": "inter*",
        "field": "reviews.content"
    }
}

Numeric Range Queries

Use a numeric range query to search for a range of numbers inside documents in your Search index:

{ 
    "query": {
        "min": 3,
        "max": 5,
        "inclusive_min": false,
        "inclusive_max": true,
        "field": "reviews.ratings.Cleanliness"
    }
}

The field value is an optional property. For more information about the field property, see Additional Query Object Properties.

Property Type Required? Description

Property	Type	Required?	Description
min	Integer	No	Set the minimum value of the numeric range that you want to search for. You can specify only a `min` value or only a `max` value on your numeric range. By default, `min` is inclusive to the range.
max	Integer	No	Set the maximum value of the numeric range that you want to search for. You can specify only a `max` value or only a `min` value on your numeric range. By default, `max` is exclusive to the range.
inclusive_min	Boolean	No	Set whether the Search Service should return documents that contain the exact `min` value. If you set `inclusive_min` to `false`, only values greater than `min` count as a match to your Search query. If you do not set the `inclusive_min` value, by default, `min` is inclusive to the range.
inclusive_max	Boolean	No	Set whether the Search Service should return documents that contain the exact `max` value. If you set `inclusive_max` to `false`, only values less than `max` count as a match to your Search query. If you do not set the `inclusive_max` value, by default, `max` is exclusive to the range.

min

Integer

Set the minimum value of the numeric range that you want to search for.

You can specify only a min value or only a max value on your numeric range.

By default, min is inclusive to the range.

max

Integer

Set the maximum value of the numeric range that you want to search for.

You can specify only a max value or only a min value on your numeric range.

By default, max is exclusive to the range.

inclusive_min

Boolean

Set whether the Search Service should return documents that contain the exact min value.

If you set inclusive_min to false, only values greater than min count as a match to your Search query.

If you do not set the inclusive_min value, by default, min is inclusive to the range.

inclusive_max

Boolean

Set whether the Search Service should return documents that contain the exact max value.

If you set inclusive_max to false, only values less than max count as a match to your Search query.

If you do not set the inclusive_max value, by default, max is exclusive to the range.

Date Range Queries

Use a date range query to search for a range of date values inside documents in your Search index:

{
    "query": {
        "start": "2001-10-09T10:20:30-08:00",
        "end": "2016-10-31",
        "inclusive_start": false,
        "inclusive_end": false,
        "field": "reviews.date"
    }
}

The field value is an optional property. For more information about the field property, see Additional Query Object Properties.

Property Type Required? Description

Property	Type	Required?	Description
start	Integer	No	Set the start date of the date range that you want to search for. You can specify only a `start` value or only a `end` value on your date range. By default, `start` is inclusive to the range.
end	Integer	No	Set the end date of the date range that you want to search for. You can specify only a `end` value or only a `start` value on your date range. By default, `end` is exclusive to the range.
inclusive_start	Boolean	No	Set whether the Search Service should return documents that contain the exact `start` value. If you set `inclusive_start` to `false`, only dates later than `start` count as a match to your Search query. If you do not set the `inclusive_start` value, by default, `start` is inclusive to the range.
inclusive_end	Boolean	No	Set whether the Search Service should return documents that contain the exact `end` value. If you set `inclusive_end` to `false`, only dates earlier than `end` count as a match to your Search query. If you do not set the `inclusive_end` value, by default, `end` is exclusive to the range.

start

Integer

Set the start date of the date range that you want to search for.

You can specify only a start value or only a end value on your date range.

By default, start is inclusive to the range.

end

Integer

Set the end date of the date range that you want to search for.

You can specify only a end value or only a start value on your date range.

By default, end is exclusive to the range.

inclusive_start

Boolean

Set whether the Search Service should return documents that contain the exact start value.

If you set inclusive_start to false, only dates later than start count as a match to your Search query.

If you do not set the inclusive_start value, by default, start is inclusive to the range.

inclusive_end

Boolean

Set whether the Search Service should return documents that contain the exact end value.

If you set inclusive_end to false, only dates earlier than end count as a match to your Search query.

If you do not set the inclusive_end value, by default, end is exclusive to the range.

Term Range Queries

Use a term range query to search for a range of terms inside documents in your Search index.

For example, the following query searches for any terms that occur in alphabetical order between be and beautiful from the reviews.content field in a Search index:

{ 
    "query": {  
        "min": "be", 
        "max": "beautiful",  
        "inclusive_min": true,  
        "inclusive_max": true,  
        "field": "reviews.content" 
    }
}

The query returns results such as beach, beaches, beans, and beast.

The field value is an optional property. For more information about the field property, see Additional Query Object Properties.

Property Type Required? Description

Property	Type	Required?	Description
min	Integer	No	Set the minimum term of the term range that you want to search for. You can specify only a `min` value or only a `max` value on your term range. By default, `min` is inclusive to the range.
max	Integer	No	Set the minimum term of the term range that you want to search for. You can specify only a `max` value or only a `min` value on your term range. By default, `max` is exclusive to the range.
inclusive_min	Boolean	No	Set whether the Search Service should return documents that contain the exact `min` value. If you set `inclusive_min` to `false`, only terms that would occur after `min` in the dictionary count as a match to your Search query. If you do not set the `inclusive_min` value, by default, `min` is inclusive to the range.
inclusive_max	Boolean	No	Set whether the Search Service should return documents that contain the exact `max` value. If you set `inclusive_max` to `false`, only terms that would occur before `max` in the dictionary count as a match to your Search query. If you do not set the `inclusive_max` value, by default, `max` is exclusive to the range.

min

Integer

Set the minimum term of the term range that you want to search for.

You can specify only a min value or only a max value on your term range.

By default, min is inclusive to the range.

max

Integer

Set the minimum term of the term range that you want to search for.

You can specify only a max value or only a min value on your term range.

By default, max is exclusive to the range.

inclusive_min

Boolean

Set whether the Search Service should return documents that contain the exact min value.

If you set inclusive_min to false, only terms that would occur after min in the dictionary count as a match to your Search query.

If you do not set the inclusive_min value, by default, min is inclusive to the range.

inclusive_max

Boolean

Set whether the Search Service should return documents that contain the exact max value.

If you set inclusive_max to false, only terms that would occur before max in the dictionary count as a match to your Search query.

If you do not set the inclusive_max value, by default, max is exclusive to the range.

IP Address Range Queries

Use an IP Address Range query to search for IP address data in your Search index.

You can use IPv4 or IPv6 CIDR syntax in your query.

For example, the following query searches for any IP addresses in the range 2.7.13.141/32 and 2001:4860:4860::8888/24:

{
    "query": {
        "conjuncts": [
            {
                "cidr": "2.7.13.0/24",
                "field": "ipv4"
            },
            {
                "cidr": "2001:db8:1234:5678::/119",
                "field": "ipv6"
            }
        ]
    }
}

If your IP range includes over 1024 IP addresses, you must update the bleveMaxResultWindow setting to accommodate your results. For more information about how to change this setting, see bleveMaxResultWindow.

Property	Type	Required?	Description
cidr	String Containing An IPv4 or IPv6 IP Address	Yes	Enter an IP address range or single IP address, in IPv4 or IPv6 CIDR notation. The Search Service returns documents with IP addresses that fall inside the specified range or match the specified IP address.

Property

Type

Required?

Description

cidr

String Containing An IPv4 or IPv6 IP Address

Yes

Enter an IP address range or single IP address, in IPv4 or IPv6 CIDR notation.

The Search Service returns documents with IP addresses that fall inside the specified range or match the specified IP address.

Distance/Radius-Based Geopoint Queries

Use a Geopoint distance/radius-based query to search for geo location values in a set radius around a specified latitude and longitude:

{
  "query": {
      "location": {
        "lon": -2.235143,
        "lat": 53.482358
      },
        "distance": "100mi",
        "field": "geo"
  }
}

To use a Geopoint query, you must have a child field in your Search index with the geopoint type. For more information about how to create a child field, see Create a Child Field in Advanced Mode or the {field-name} object.

Property Type Required? Description

Property	Type	Required?	Description
location	Object or Array	Yes	Set the geo location value to use as the center of the search radius for your query. If you use `location` as an object, you must set two values: `lon`: The longitude of the geo location to use as the center of the search radius. `lat`: The latitude of the geo location to use as the center of the search radius. If you use `location` as an array, your array must contain a longitude value followed by a latitude value. For example, `[-2.235143, 53.482358]`, where `-2.235143` is the longitude.
distance	String	Yes	The radius where the Search Service should search for matching geo location values. Enter the radius as a single string, with a numeric value and a unit value. For example, `100.5mi`. You can use the following distance units: `mm`: Millimeters `cm`: Centimeters `in`: Inches `yd`: Yards `ft`: Feet `m`: Meters `km`: Kilometers `mi`: Miles `nm`: Nautical miles

location

Object or Array

Yes

Set the geo location value to use as the center of the search radius for your query.

If you use location as an object, you must set two values:

lon: The longitude of the geo location to use as the center of the search radius.
lat: The latitude of the geo location to use as the center of the search radius.

If you use location as an array, your array must contain a longitude value followed by a latitude value. For example, [-2.235143, 53.482358], where -2.235143 is the longitude.

distance

String

Yes

The radius where the Search Service should search for matching geo location values.

Enter the radius as a single string, with a numeric value and a unit value. For example, 100.5mi.

You can use the following distance units:

mm: Millimeters
cm: Centimeters
in: Inches
yd: Yards
ft: Feet
m: Meters
km: Kilometers
mi: Miles
nm: Nautical miles

Rectangle-Based Geopoint Queries

Use a Geopoint rectangle-based query to search for geo location values in a defined rectangle:

{ 
  "query": {
      "top_left": [-2.235143, 53.482358],
      "bottom_right": {
        "lon": 28.955043,
        "lat": 40.991862
      },
      "field": "geo"
  }
}

The Search Service takes a value for the top-left and bottom-right corners of a rectangle, and draws a bounding box that connects those points. The resulting rectangle is used as the search area for geo location values.

Property Type Required? Description

Property	Type	Required?	Description
top_left	Object or Array	Yes	Set the geo location value to use as the top-left corner point of the rectangle search area. If you use `top_left` as an object, you must set two values: `lon`: The longitude of the geo location to use as the top-left corner of the rectangle. `lat`: The latitude of the geo location to use as the top-left corner of the rectangle. If you use `top_left` as an array, your array must contain a longitude floating point value followed by a latitude floating point value. For example, `[-2.235143, 53.482358]`, where `-2.235143` is the longitude.
bottom_right	Object or Array	Yes	Set the geo location value to use as the bottom-right corner point of the rectangle search area. If you use `bottom_right` as an object, you must set two values: `lon`: The longitude of the geo location to use as the bottom-right corner of the rectangle. `lat`: The latitude of the geo location to use as the bottom-right corner of the rectangle. If you use `bottom_right` as an array, your array must contain a longitude floating point value followed by a latitude floating point value. For example, `[-2.235143, 53.482358]`, where `-2.235143` is the longitude.

top_left

Object or Array

Yes

Set the geo location value to use as the top-left corner point of the rectangle search area.

If you use top_left as an object, you must set two values:

lon: The longitude of the geo location to use as the top-left corner of the rectangle.
lat: The latitude of the geo location to use as the top-left corner of the rectangle.

If you use top_left as an array, your array must contain a longitude floating point value followed by a latitude floating point value. For example, [-2.235143, 53.482358], where -2.235143 is the longitude.

bottom_right

Object or Array

Yes

Set the geo location value to use as the bottom-right corner point of the rectangle search area.

If you use bottom_right as an object, you must set two values:

lon: The longitude of the geo location to use as the bottom-right corner of the rectangle.
lat: The latitude of the geo location to use as the bottom-right corner of the rectangle.

If you use bottom_right as an array, your array must contain a longitude floating point value followed by a latitude floating point value. For example, [-2.235143, 53.482358], where -2.235143 is the longitude.

Polygon-Based Geopoint Queries

Use a Geopoint polygon-based query to search for geo location values in a defined polygon:

{
  "query": {
      "field": "geo",
      "polygon_points": [
        "37.79393211306212,-122.44234633404847",
        "37.77995881733997,-122.43977141339417",
        "37.788031092020155,-122.42925715405579",
        "37.79026946582319,-122.41149020154114",
        "37.79571192027403,-122.40735054016113",
        "37.79393211306212,-122.44234633404847"
      ]
  }
}

The Search Service takes an array of latitude and longitude values and connects them in the specified order to form a polygon. The resulting polygon is used as the search area for geo location values.

Property Type Required? Description

Property	Type	Required?	Description
polygon_points	Array	Yes	Set an array of latitude and longitude string values to use as the points in your polygon search area. For example, an array of `[ "37.79393211306212,-122.44234633404847", "37.77995881733997,-122.43977141339417", "37.788031092020155,-122.42925715405579"]` is interpreted as 3 separate polygon points and creates a 3-sided polygon. For `polygon_points`, the first value in the string is the latitude, and the second is the longitude. You can set the last value in the array to the same value as the first latitude and longitude to explicitly close your polygon. Otherwise, the Search Service infers the polygon’s closure.

polygon_points

Array

Yes

Set an array of latitude and longitude string values to use as the points in your polygon search area.

For example, an array of [ "37.79393211306212,-122.44234633404847", "37.77995881733997,-122.43977141339417", "37.788031092020155,-122.42925715405579"] is interpreted as 3 separate polygon points and creates a 3-sided polygon.

For polygon_points, the first value in the string is the latitude, and the second is the longitude.

You can set the last value in the array to the same value as the first latitude and longitude to explicitly close your polygon. Otherwise, the Search Service infers the polygon’s closure.

Point GeoJSON Queries

Use a GeoJSON Point query to search for a single latitude and longitude coordinate that intersects or is contained inside a GeoJSON shape in your documents:

{
    "query": {        
        "field": "geojson",     
        "geometry": {                
            "shape": {                      
                "type": "Point",                      
                "coordinates": [0.47482593026924746, 51.31232878073189]               
            },                
            "relation": "intersects"          
        }    
    }
}

To use a GeoJSON query, you must have a child field in your Search index with the geoshape type. The geoshape field must contain a type property and a coordinates array. For more information about how to create a child field, see Create a Child Field in Advanced Mode or the {field-name} object.

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `Point`.
coordinates	Array	Yes	An array of coordinate floating point values that define the GeoJSON shape. For a `point` query, set the `coordinates` array to a single array with a longitude and latitude value. The Search Service uses the first value in the `coordinates` array as the longitude value.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON Point search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: The defined query Point overlaps a defined Point or LineString, or exists within the defined area for a Polygon, Circle, or Envelope. For multi-shape geometries, the query point must only overlap with one Point, LineString, or Polygon. `contains`: The defined query Point overlaps a defined Point or LineString, or exists within the defined area for a Polygon, Circle, or Envelope. For multi-shape geometries, the query point must only overlap with one Point, LineString, or Polygon. `within`: Not supported for Point queries.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to Point.

coordinates

Array

Yes

An array of coordinate floating point values that define the GeoJSON shape.

For a point query, set the coordinates array to a single array with a longitude and latitude value.

The Search Service uses the first value in the coordinates array as the longitude value.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON Point search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: The defined query Point overlaps a defined Point or LineString, or exists within the defined area for a Polygon, Circle, or Envelope.

For multi-shape geometries, the query point must only overlap with one Point, LineString, or Polygon.
contains: The defined query Point overlaps a defined Point or LineString, or exists within the defined area for a Polygon, Circle, or Envelope.

For multi-shape geometries, the query point must only overlap with one Point, LineString, or Polygon.
within: Not supported for Point queries.

LineString GeoJSON Queries

Use a GeoJSON LineString query to search for a line of coordinates that intersects or is contained inside a GeoJSON shape in your documents:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
            "type": "LineString",
            "coordinates": [
                    [-2.753735609842721, 53.94860827535115],
                    [-2.599898256093695,53.65007434185782]
                ]
            },
            "relation": "intersects"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `LineString`.
coordinates	Array of Arrays	Yes	An array that contains arrays of 2 coordinate floating point values that define the GeoJSON LineString shape. For a `linestring` query, the `coordinates` array can contain multiple coordinate point arrays. The Search Service uses the first value in any nested `coordinates` array as the longitude value for the coordinate.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON LineString search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: The defined query LineString overlaps a defined Point or LineString, or intersects with the defined edges of a Polygon, Circle, or Envelope. For multi-shape geometries, the defined LineString must only overlap one Point, or intersect one LineString or Polygon. `contains`: The start and end points of the LineString are within the defined area of a Polygon, Circle, or Envelope. Points and LineStrings are not supported. For MultiPolygon or GeometryCollection shapes, only one Polygon must contain both the start and end points of the LineString. `within`: Not supported for LineString queries.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to LineString.

coordinates

Array of Arrays

Yes

An array that contains arrays of 2 coordinate floating point values that define the GeoJSON LineString shape.

For a linestring query, the coordinates array can contain multiple coordinate point arrays.

The Search Service uses the first value in any nested coordinates array as the longitude value for the coordinate.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON LineString search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: The defined query LineString overlaps a defined Point or LineString, or intersects with the defined edges of a Polygon, Circle, or Envelope.

For multi-shape geometries, the defined LineString must only overlap one Point, or intersect one LineString or Polygon.
contains: The start and end points of the LineString are within the defined area of a Polygon, Circle, or Envelope.

Points and LineStrings are not supported. For MultiPolygon or GeometryCollection shapes, only one Polygon must contain both the start and end points of the LineString.
within: Not supported for LineString queries.

Polygon GeoJSON Queries

Use a GeoJSON Polygon query to search for a defined area that intersects, is contained inside, or surrounds a GeoJSON shape in your documents:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "type": "Polygon",
                "coordinates": [
                    [
                    [
                        0.47482593026924746,
                        51.31232878073189
                    ],
                    [
                        0.6143265647863245,
                        51.31232878073189
                    ],
                    [
                        0.6143265647863245,
                        51.384000374770466
                    ],
                    [
                        0.47482593026924746,
                        51.384000374770466
                    ],
                    [
                        0.47482593026924746,
                        51.31232878073189
                    ]
                    ]
                ]
            },
            "relation": "within"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `Polygon`.
coordinates	Array of Arrays	Yes	An array that contains an outer array, and arrays of 2 coordinate floating point values that define the GeoJSON Polygon shape. The Search Service uses the first value in any nested `coordinates` array as the longitude value for the coordinate. The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON Polygon search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: The defined query Polygon contains a Point, or one of its edges intersects a LineString, Polygon, Circle, or Envelope. For multi-shape geometries, only one Point must be contained, or only one LineString or Polygon must intersect. `contains`: The entire defined area of the query Polygon exists inside a Polygon, Circle, or Envelope. Points and LineStrings are not supported. For multi-shape geometries, one shape must contain the entirety of the defined query Polygon. `within`: The query Polygon contains a Point, the endpoints of a LineString, or the entirety of a Polygon, Circle, or Envelope. For multi-shape geometries, the query Polygon must contain the entirety of each defined Point, LineString, or Polygon.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to Polygon.

coordinates

Array of Arrays

Yes

An array that contains an outer array, and arrays of 2 coordinate floating point values that define the GeoJSON Polygon shape.

The Search Service uses the first value in any nested coordinates array as the longitude value for the coordinate.

The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON Polygon search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: The defined query Polygon contains a Point, or one of its edges intersects a LineString, Polygon, Circle, or Envelope.

For multi-shape geometries, only one Point must be contained, or only one LineString or Polygon must intersect.
contains: The entire defined area of the query Polygon exists inside a Polygon, Circle, or Envelope.

Points and LineStrings are not supported. For multi-shape geometries, one shape must contain the entirety of the defined query Polygon.
within: The query Polygon contains a Point, the endpoints of a LineString, or the entirety of a Polygon, Circle, or Envelope.

For multi-shape geometries, the query Polygon must contain the entirety of each defined Point, LineString, or Polygon.

MultiPoint GeoJSON Queries

Use a GeoJSON MultiPoint query to search for multiple coordinate points that intersect or are contained inside a GeoJSON shape in your documents:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "type": "MultiPoint",
                "coordinates": [
                    [1.954764, 50.962097],
                    [3.029578, 49.868547]
                ]
            },
            "relation": "intersects"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `MultiPoint`.
coordinates	Array of Arrays	Yes	An array that contains arrays of 2 coordinate floating point values that define the GeoJSON MultiPoint shape. The Search Service uses the first value in any nested `coordinates` array as the longitude value for the coordinate.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON MultiPoint search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: One of the points in the MultiPoint overlaps a Point or a LineString endpoint, or exists inside the area of a Polygon, Circle, or Envelope. For multi-shape geometries, only one Point must inside the shape or overlap a Point or endpoint. `contains`: All points in the MultiPoint exist inside a Polygon, Circle, or Envelope. Points and LineStrings are not supported. A MultiPoint shape can return a match if all points in the query overlap with the MultiPoint in the document. A MultiPolygon or GeometryCollection returns a match if all query points exist within any of the defined Polygons or MultiPoints. `within`: Any of the points in the query MultiPoint overlap with a defined Point. A MultiPoint shape returns a match if all points in the query overlap with the MultiPoint in the document.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to MultiPoint.

coordinates

Array of Arrays

Yes

An array that contains arrays of 2 coordinate floating point values that define the GeoJSON MultiPoint shape.

The Search Service uses the first value in any nested coordinates array as the longitude value for the coordinate.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON MultiPoint search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: One of the points in the MultiPoint overlaps a Point or a LineString endpoint, or exists inside the area of a Polygon, Circle, or Envelope.

For multi-shape geometries, only one Point must inside the shape or overlap a Point or endpoint.
contains: All points in the MultiPoint exist inside a Polygon, Circle, or Envelope.

Points and LineStrings are not supported. A MultiPoint shape can return a match if all points in the query overlap with the MultiPoint in the document.

A MultiPolygon or GeometryCollection returns a match if all query points exist within any of the defined Polygons or MultiPoints.
within: Any of the points in the query MultiPoint overlap with a defined Point.

A MultiPoint shape returns a match if all points in the query overlap with the MultiPoint in the document.

MultiLineString GeoJSON Queries

Use a GeoJSON MultiLineString query to search for multiple LineStrings that intersect or are contained inside a GeoJSON shape in your documents:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "type": "MultiLineString",
                "coordinates": [
                        [ [1.954764, 50.962097], [3.029578, 49.868547] ],
                        [ [3.029578, 49.868547], [-0.387444, 48.545836] ]
                    ]
            },
            "relation": "intersects"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `MultiLineString`.
coordinates	Array of Arrays	Yes	An array that contains nested arrays, each with their own nested arrays of 2 coordinate floating point values. For example, the following `coordinates` array defines 2 LineStrings with start and end points: "coordinates": [ [ [1.954764, 50.962097], [3.029578, 49.868547] ], [ [3.029578, 49.868547], [-0.387444, 48.545836] ] ] The innermost arrays define the individual points for a LineString in the MultiLineString shape. The Search Service uses the first value in the nested `coordinates` arrays as the longitude value for a coordinate.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON MultiLineString search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: Any LineString inside the defined query MultiLineString overlaps a defined Point or LineString, or intersects with the defined edges of a Polygon, Circle, or Envelope. For multi-shape geometries, any defined LineString must only overlap one Point, or intersect one LineString or Polygon. `contains`: The start and end points of every LineString inside the defined query MultiLineString are within the defined area of a Polygon, Circle, or Envelope. Points and LineStrings are not supported. For MultiPolygon or GeometryCollection shapes, only one Polygon must contain both the start and end points of every LineString. `within`: Not supported for MultiLineString queries.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to MultiLineString.

coordinates

Array of Arrays

Yes

An array that contains nested arrays, each with their own nested arrays of 2 coordinate floating point values.

For example, the following coordinates array defines 2 LineStrings with start and end points:

"coordinates": [
    [
        [1.954764, 50.962097], [3.029578, 49.868547]
    ],

    [
        [3.029578, 49.868547], [-0.387444, 48.545836]
    ]
]

The innermost arrays define the individual points for a LineString in the MultiLineString shape.

The Search Service uses the first value in the nested coordinates arrays as the longitude value for a coordinate.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON MultiLineString search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: Any LineString inside the defined query MultiLineString overlaps a defined Point or LineString, or intersects with the defined edges of a Polygon, Circle, or Envelope.

For multi-shape geometries, any defined LineString must only overlap one Point, or intersect one LineString or Polygon.
contains: The start and end points of every LineString inside the defined query MultiLineString are within the defined area of a Polygon, Circle, or Envelope.

Points and LineStrings are not supported. For MultiPolygon or GeometryCollection shapes, only one Polygon must contain both the start and end points of every LineString.
within: Not supported for MultiLineString queries.

MultiPolygon GeoJSON Queries

Use a GeoJSON MultiPolygon query to search for a group of defined Polygons that intersect, are contained inside, or surround a GeoJSON shape in your documents:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "type": "MultiPolygon",
                "coordinates": [
                    [
                        [[-1.8167959002718135, 53.8626654046235],
                        [-1.8728039536828476, 53.6335890387158],
                        [-1.4029586167332582, 53.57727933778668],
                        [-1.0031233465474827, 53.664942195474936],
                        [-1.1742590653039997, 53.84522968338081],
                        [-1.5523134258297944, 53.89384804206853],
                        [-1.8167959002718135, 53.8626654046235]]
                    ],
                    [
                        [[-2.4935598789906805, 53.64373525825596],
                        [-2.664695597747226, 53.33735696804186],
                        [-2.0143798664721544, 53.28065279675474],
                        [-1.8572461610683888, 53.550482816448266],
                        [-2.309977926141812, 53.604982015453714],
                        [-2.4935598789906805, 53.64373525825596]]
                    ]
                ]
            },
            "relation": "within"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `MultiPolygon`.
coordinates	Array of Arrays	Yes	An array that contains arrays that describe a GeoJSON Polygon shape. Each inner array that describes a Polygon can contain multiple arrays with 2 coordinate floating point values. These innermost arrays describe the coordinates of the Polygon. The Search Service uses the first value in any nested `coordinates` array as the longitude value for the coordinate. The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON MultiPolygon search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: Any of the Polygons defined in the query MultiPolygon contain a Point, or one of their edges intersects a LineString, Polygon, Circle, or Envelope. For multi-shape geometries, only one Point must be contained in a query Polygon, or only one LineString or Polygon must intersect. `contains`: Every Polygon defined in the query MultiPolygon exists inside a Polygon, Circle, or Envelope. Points and LineStrings are not supported. For multi-shape geometries, one shape must contain the entirety of the defined query Polygons. `within`: Any of the Polygons defined in the query MultiPolygon contain a Point, the endpoints of a LineString, or the entirety of a Polygon, Circle, or Envelope. For multi-shape geometries, any of the query Polygons must collectively contain the entirety of each defined Point, LineString, or Polygon.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to MultiPolygon.

coordinates

Array of Arrays

Yes

An array that contains arrays that describe a GeoJSON Polygon shape.

Each inner array that describes a Polygon can contain multiple arrays with 2 coordinate floating point values. These innermost arrays describe the coordinates of the Polygon.

The Search Service uses the first value in any nested coordinates array as the longitude value for the coordinate.

The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON MultiPolygon search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: Any of the Polygons defined in the query MultiPolygon contain a Point, or one of their edges intersects a LineString, Polygon, Circle, or Envelope.

For multi-shape geometries, only one Point must be contained in a query Polygon, or only one LineString or Polygon must intersect.
contains: Every Polygon defined in the query MultiPolygon exists inside a Polygon, Circle, or Envelope.

Points and LineStrings are not supported. For multi-shape geometries, one shape must contain the entirety of the defined query Polygons.
within: Any of the Polygons defined in the query MultiPolygon contain a Point, the endpoints of a LineString, or the entirety of a Polygon, Circle, or Envelope.

For multi-shape geometries, any of the query Polygons must collectively contain the entirety of each defined Point, LineString, or Polygon.

GeometryCollection GeoJSON Queries

Use a GeoJSON GeometryCollection query to search for a group of defined Points, LineStrings, or Polygons that intersect, are contained inside, or surround a GeoJSON shape in your documents:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "type": "GeometryCollection",
                "geometries": [
                    {
                        "type": "LineString",
                        "coordinates": [
                            [-2.753735609842721, 53.94860827535115],
                            [-2.599898256093695, 53.65007434185782]
                        ]
                    }, 
                    {
                        "type": "MultiPolygon",
                        "coordinates": [
                            [[
                                [-1.8167959002718135, 53.8626654046235],
                                [-1.8728039536828476, 53.6335890387158],
                                [-1.4029586167332582, 53.57727933778668],
                                [-1.0031233465474827, 53.664942195474936],
                                [-1.1742590653039997, 53.84522968338081],
                                [-1.5523134258297944, 53.89384804206853],
                                [-1.8167959002718135, 53.8626654046235]
                            ]],
                            [[
                                [-2.4935598789906805, 53.64373525825596],
                                [-2.664695597747226, 53.33735696804186],
                                [-2.0143798664721544, 53.28065279675474],
                                [-1.8572461610683888, 53.550482816448266],
                                [-2.309977926141812, 53.604982015453714],
                                [-2.4935598789906805, 53.64373525825596]
                            ]]
                        ]
                    }
                ]
            },
            "relation": "contains"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and geometries property.
type	String	Yes	Set `type` to `GeometryCollection`.
geometries	Array of Objects	Yes	Contains objects to define each GeoJSON shape in the GeometryCollection. Each object in the `geometries` array has a `type` property and a coordinates property. Set the `type` property inside the object to the specific shape type you want to define: point LineString polygon MultiPoint MultiLineString MultiPolygon
coordinates	Array or Array of Arrays	Yes	An array or array of arrays that describes a GeoJSON shape. The exact structure of the arrays depends on the shape: Point LineString Polygon MultiPoint MultiLineString MultiPolygon For any array that contains only floating point values, the Search Service uses the first value as the longitude. The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON GeometryCollection search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: If any of the shapes in the query intersect with a shape in the document, the Search Service returns the document. `contains`: Every shape in the query must be contained, cumulatively, inside the shape or shapes defined in a document. `within`: Any of the shapes in a document must be contained within a shape in the query.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and geometries property.

type

String

Yes

Set type to GeometryCollection.

geometries

Array of Objects

Yes

Contains objects to define each GeoJSON shape in the GeometryCollection.

Each object in the geometries array has a type property and a coordinates property.

Set the type property inside the object to the specific shape type you want to define:

point
LineString
polygon
MultiPoint
MultiLineString
MultiPolygon

coordinates

Array or Array of Arrays

Yes

An array or array of arrays that describes a GeoJSON shape.

The exact structure of the arrays depends on the shape:

Point
LineString
Polygon
MultiPoint
MultiLineString
MultiPolygon

For any array that contains only floating point values, the Search Service uses the first value as the longitude.

The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON GeometryCollection search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: If any of the shapes in the query intersect with a shape in the document, the Search Service returns the document.
contains: Every shape in the query must be contained, cumulatively, inside the shape or shapes defined in a document.
within: Any of the shapes in a document must be contained within a shape in the query.

Circle GeoJSON Queries

Use a GeoJSON Circle query to search in a radius around a single latitude and longitude coordinate:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "coordinates": [-2.2450285424707204, 53.48503270828377],
                "type": "Circle",
                "radius": "100mi"
            },
            "relation": "within"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property, coordinates property, and radius property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `Circle`.
coordinates	Array	Yes	An array of coordinate floating point values that define the center point of the Circle. Set the `coordinates` array to a single array with a longitude and latitude value. The Search Service uses the first value in the `coordinates` array as the longitude value.
radius	String	Yes	Set the radius of the Circle. Enter the radius as a single string, with a numeric value and a unit value. For example, `100.5mi`. You can use the following distance units: `mm`: Millimeters `cm`: Centimeters `in`: Inches `yd`: Yards `ft`: Feet `m`: Meters `km`: Kilometers `mi`: Miles `nm`: Nautical miles
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON Circle search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: A defined Point exists within the radius of the Circle, or a LineString, Polygon, Envelope or Circle intersects the Circle. For multi-shape geometries, the Circle must only contain with one Point, or intersect one LineString or Polygon. `contains`: A defined Polygon, Envelope, or Circle contains the entire defined query Circle. Points and LineStrings are not supported. For MultiPolygons or GeometryCollections containing only Polygons, the query Circle must be contained by one Polygon. `within`: All defined GeoJSON shapes in the document must exist inside the defined query Circle.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property, coordinates property, and radius property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to Circle.

coordinates

Array

Yes

An array of coordinate floating point values that define the center point of the Circle.

Set the coordinates array to a single array with a longitude and latitude value.

The Search Service uses the first value in the coordinates array as the longitude value.

radius

String

Yes

Set the radius of the Circle.

Enter the radius as a single string, with a numeric value and a unit value. For example, 100.5mi.

You can use the following distance units:

mm: Millimeters
cm: Centimeters
in: Inches
yd: Yards
ft: Feet
m: Meters
km: Kilometers
mi: Miles
nm: Nautical miles

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON Circle search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: A defined Point exists within the radius of the Circle, or a LineString, Polygon, Envelope or Circle intersects the Circle.

For multi-shape geometries, the Circle must only contain with one Point, or intersect one LineString or Polygon.
contains: A defined Polygon, Envelope, or Circle contains the entire defined query Circle.

Points and LineStrings are not supported. For MultiPolygons or GeometryCollections containing only Polygons, the query Circle must be contained by one Polygon.
within: All defined GeoJSON shapes in the document must exist inside the defined query Circle.

Envelope GeoJSON Queries

Use a GeoJSON Envelope query to search in a bounded rectangle, based on a pair of coordinates that define the minimum and maxium longitude and latitude:

{
    "query": {
        "field": "geojson",
        "geometry": {
            "shape": {
                "type": "Envelope",
                "coordinates": [
                    [-3.1720240079703785, 53.58545703217979],
                    [-1.8566251855731082, 53.282076725710596]
                ]
            },
            "relation": "intersects"
        }
    }
}

Property Type Required? Description

Property	Type	Required?	Description
geometry	Object	Yes	Contains the shape property and relation property. Defines the GeoJSON shape and how the Search Service should find a match in documents.
shape	Object	Yes	Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query.
type	String	Yes	Set `type` to `Envelope`.
coordinates	Array of 2 Arrays	Yes	An array of 2 different arrays that contain coordinate floating point values. The first `coordinates` nested array contains the minimum longitude and maximum latitude, or the top-left corner of the rectangle. The second nested array contains the maximum longitude and minimum latitude, or the bottom-right corner. The Search Service uses the first value in the nested `coordinates` array as the longitude value.
relation	String	Yes	Set how the Search Service should return a match for a GeoJSON Envelope search. Your selected `relation` type determines which shapes return a match for your query. You can use the following string values in the `relation` property: `intersects`: A defined Point exists within the Envelope, or a LineString, Polygon, Envelope or Circle intersects the Envelope. For multi-shape geometries, the Envelope must only contain with one Point, or intersect one LineString or Polygon. `contains`: A defined Polygon, Envelope, or Circle contains the entire defined query Envelope. Points and LineStrings are not supported. For MultiPolygons or GeometryCollections containing only Polygons, the query Envelope must be contained by one Polygon. `within`: All defined GeoJSON shapes in the document must exist inside the defined query Envelope.

geometry

Object

Yes

Contains the shape property and relation property.

Defines the GeoJSON shape and how the Search Service should find a match in documents.

shape

Object

Yes

Contains the type property and coordinates property.

Defines the specific GeoJSON shape to use in the query.

type

String

Yes

Set type to Envelope.

coordinates

Array of 2 Arrays

Yes

An array of 2 different arrays that contain coordinate floating point values.

The first coordinates nested array contains the minimum longitude and maximum latitude, or the top-left corner of the rectangle.

The second nested array contains the maximum longitude and minimum latitude, or the bottom-right corner.

The Search Service uses the first value in the nested coordinates array as the longitude value.

relation

String

Yes

Set how the Search Service should return a match for a GeoJSON Envelope search.

Your selected relation type determines which shapes return a match for your query.

You can use the following string values in the relation property:

intersects: A defined Point exists within the Envelope, or a LineString, Polygon, Envelope or Circle intersects the Envelope.

For multi-shape geometries, the Envelope must only contain with one Point, or intersect one LineString or Polygon.
contains: A defined Polygon, Envelope, or Circle contains the entire defined query Envelope.

Points and LineStrings are not supported. For MultiPolygons or GeometryCollections containing only Polygons, the query Envelope must be contained by one Polygon.
within: All defined GeoJSON shapes in the document must exist inside the defined query Envelope.

Special Queries

You can use the following special queries as the only properties inside a query object to return all or no documents from your Search index in search results.

Property Type Description Examples

Property	Type	Description	Examples
match_all	Object	Use the `match_all` object as the only property in your `query` object to return all documents from the Search index in search results.	Return all documents in the Search index `{ "query": { "match_all": {} } }`
match_none	Object	Use the `match_none` object as the only property in your `query` object to return no documents from the Search index in search results. If you add a knn object and a `query` object with the `match_none` object to your request, your search returns only matches to the Vector Search query inside the `knn` object. If your cluster is running Couchbase Server version 7.6.2 and later, when running a Vector Search query without a `query` object, the Search Service automatically adds a `query` object with a `match_none` query object to your request.	Return no documents from the Search index `{ "query": { "match_none": {} } }`

match_all

Object

Use the match_all object as the only property in your query object to return all documents from the Search index in search results.

Return all documents in the Search index

{ 
    "query": {
        "match_all": {}
    }
}

match_none

Object

Use the match_none object as the only property in your query object to return no documents from the Search index in search results.

If you add a knn object and a query object with the match_none object to your request, your search returns only matches to the Vector Search query inside the knn object. If your cluster is running Couchbase Server version 7.6.2 and later, when running a Vector Search query without a query object, the Search Service automatically adds a query object with a match_none query object to your request.

Return no documents from the Search index

{
    "query": {
        "match_none": {}
    }
}

Additional Query Object Properties

You can use the following properties to modify the results returned by specific query types.

Property Type Description Examples

Property	Type	Description	Examples
analyzer	String	Use the `analyzer` property to modify the behavior of a match query or a match phrase query. Set the `analyzer` property to the name of the analyzer you want to use on the contents of the match property or match_phrase property. The specified analyzer only applies to the content of your Search request. It does not apply to the contents of documents in the Search index. However, the analyzer set on your Search request and in your Search index should match.	Match query for "location" and "hostel" in reviews.content with the "en" analyzer `{ "query":{ "match": "location hostel", "field": "reviews.content", "analyzer": "en" } }`
boost	Integer	If you use multiple clauses in a query, you can use the `boost` property to assign the relative importance to a clause. Clauses with a higher value in the `boost` property score higher and appear earlier in search results.	Disjunction query with boost property on the city field containing glossop `{ "query": { "disjuncts": [ { "match": "glossop", "field": "city", "boost": 10 }, { "match": "glossop", "field": "title" } ] } }`
field	String	Specify a specific field name, using dot notation, where the Search Service should search for a match to your search query. If your cluster is running Couchbase Server version 7.6.2 or later and you want to search for document metadata held in XATTRs, you must add `$xattrs` to the start of your metadata field’s name. For example, `"``$xattrs.description"`.	Search for documents where the pets_ok field is true `{ "query": { "field": "pets_ok", "bool": true } }`
fuzziness	Integer	Use the `fuzziness` property to run a fuzzy query. The `fuzziness` property uses your specified edit distance to match terms based on their similarity, rather than exact matches. You can set `fuzziness` to a maximum value of `2`. Use the `fuzziness` property with the term property for a term query or the match property for a match query.	Search for a match the term "interest" inside the reviews.content field with a fuzziness of 2 `{ "query": { "term": "interest", "field": "reviews.content", "fuzziness": 2 } }`
operator	String	Use the `operator` property to modify the behavior of a match query: "and": Any spaces between terms in the match property are interpreted as the `AND` operator. Documents must match all of the terms in the query. "or": Any spaces between terms in the match property are interpreted as the `OR` operator. Documents must match at least one of the terms in the query. For example, if you set a `match` property to the value `"good great"` and the `operator` property to `"and"`, the Search Service only returns matches for documents that contain `good` and `great`. If you set the `operator` property to `"or"`, a document only needs to contain one of the terms from the `match` property: `good` or `great`.	Match query for "best" or "worst" in reviews.content `{ "query": { "match": "best worst", "field": "reviews.content", "operator": "or" } }`
prefix_length	Integer	Use the `prefix_length` property to modify the behavior of a match query. The `prefix_length` changes a match query to a prefix match query. The Search Service matches terms based on the query and the result sharing a prefix of the specified length.	Match query for "location hostel" in reviews.content with a prefix_length of 4 `{ "query": { "match": "location hostel", "field": "reviews.content", "prefix_length": 4 } }`

analyzer

String

Use the analyzer property to modify the behavior of a match query or a match phrase query.

Set the analyzer property to the name of the analyzer you want to use on the contents of the match property or match_phrase property.

The specified analyzer only applies to the content of your Search request. It does not apply to the contents of documents in the Search index. However, the analyzer set on your Search request and in your Search index should match.

Match query for "location" and "hostel" in reviews.content with the "en" analyzer

{
    "query":{
        "match": "location hostel",
        "field": "reviews.content",
        "analyzer": "en"
    }
}

boost

Integer

If you use multiple clauses in a query, you can use the boost property to assign the relative importance to a clause.

Clauses with a higher value in the boost property score higher and appear earlier in search results.

Disjunction query with boost property on the city field containing glossop

{
    "query": {
        "disjuncts": [
            {
                "match": "glossop",
                "field": "city",
                "boost": 10
            },
            {
                "match": "glossop",
                "field": "title"
            }
        ]
    }
}

field

String

Specify a specific field name, using dot notation, where the Search Service should search for a match to your search query.

If your cluster is running Couchbase Server version 7.6.2 or later and you want to search for document metadata held in XATTRs, you must add $xattrs to the start of your metadata field’s name. For example, "$xattrs.description".

Search for documents where the pets_ok field is true

{ 
    "query": {
        "field": "pets_ok",
        "bool": true
    }
}

fuzziness

Integer

Use the fuzziness property to run a fuzzy query.

The fuzziness property uses your specified edit distance to match terms based on their similarity, rather than exact matches.

You can set fuzziness to a maximum value of 2.

Use the fuzziness property with the term property for a term query or the match property for a match query.

Search for a match the term "interest" inside the reviews.content field with a fuzziness of 2

{ 
    "query": {
        "term": "interest",
        "field": "reviews.content",
        "fuzziness": 2
    }
}

operator

String

Use the operator property to modify the behavior of a match query:

"and": Any spaces between terms in the match property are interpreted as the AND operator. Documents must match all of the terms in the query.
"or": Any spaces between terms in the match property are interpreted as the OR operator. Documents must match at least one of the terms in the query.

For example, if you set a match property to the value "good great" and the operator property to "and", the Search Service only returns matches for documents that contain good and great.

If you set the operator property to "or", a document only needs to contain one of the terms from the match property: good or great.

Match query for "best" or "worst" in reviews.content

{
    "query": {
        "match": "best worst",
        "field": "reviews.content",
        "operator": "or"
    }
}

prefix_length

Integer

Use the prefix_length property to modify the behavior of a match query.

The prefix_length changes a match query to a prefix match query. The Search Service matches terms based on the query and the result sharing a prefix of the specified length.

Match query for "location hostel" in reviews.content with a prefix_length of 4

{
    "query": {
        "match": "location hostel",
        "field": "reviews.content",
        "prefix_length": 4
    }
}

Ctl Object

Use the ctl object to make sure that the Search Service runs your Search query against the latest version of the documents in your database.

The ctl object and its properties cause the Search Service to run your query against the latest version of a document written to a vBucket. The Search Service uses a consistency vector to synchronize the last document write to a vBucket from the Data Service with the Search index.

    "ctl": {
        "timeout": 10000,
        "consistency": {
            "vectors": {
                "searchIndexName": {
                    "607/205096593892159": 2,
                    "640/298739127912798": 4  
                }
            },
            "level": "at_plus",
            "results": "complete"
        }
    },

The ctl object contains the following properties:

Property Type Required? Description

Property	Type	Required?	Description
timeout	Integer	No	Set the maximum time, in milliseconds, that a Search query can execute on a Search index partition. If the query time exceeds the `timeout`, the Search Service cancels the query. The query might return partial results if any index partitions responded before the timeout.
consistency	Object	Yes	An object that contains a `vectors` object and the `level` and `results` properties. For more information, see Consistency Object.

timeout

Integer

Set the maximum time, in milliseconds, that a Search query can execute on a Search index partition.

If the query time exceeds the timeout, the Search Service cancels the query. The query might return partial results if any index partitions responded before the timeout.

consistency

Object

Yes

An object that contains a vectors object and the level and results properties.

For more information, see Consistency Object.

Consistency Object

Use the consistency object to control the consistency behavior for a Search index:

        "consistency": {
            "vectors": {
                "searchIndexName": {
                    "607/205096593892159": 2,
                    "640/298739127912798": 4  
                }
            },
            "level": "at_plus",
            "results": "complete"
        }

A consistency object has the following properties:

Property Type Required? Description

Property	Type	Required?	Description
vectors	Object	Yes	An object that contains a `{search-index-name}` object for each Search index in the query. For more information about the `{search-index-name}` object, see {search-index-name} Object.
level	String	Yes	Set the consistency to bounded or unbounded consistency: `at_plus`: The Search query executes but requires that the Search index matches the timestamp of the last document update. You must provide a `vectors` object `not_bounded`: The Search query executes without a consistency requirement. `not_bounded` is faster than `at_plus`, as it doesn’t rely on a `vectors` object or wait for the Search index to match the Data Service index.
results	String	No	To display an error instead of partial results if any index partitions are unavailable on a node, set `results` to `complete`. To return partial results from a query if a node is unreachable, remove the `results` property.

vectors

Object

Yes

An object that contains a {search-index-name} object for each Search index in the query.

For more information about the {search-index-name} object, see {search-index-name} Object.

level

String

Yes

Set the consistency to bounded or unbounded consistency:

at_plus: The Search query executes but requires that the Search index matches the timestamp of the last document update. You must provide a vectors object
not_bounded: The Search query executes without a consistency requirement. not_bounded is faster than at_plus, as it doesn’t rely on a vectors object or wait for the Search index to match the Data Service index.

results

String

To display an error instead of partial results if any index partitions are unavailable on a node, set results to complete.

To return partial results from a query if a node is unreachable, remove the results property.

{search-index-name} Object

Use a {search-index-name} object to set the Search index and consistency vectors for a Search query.

The {search-index-name} object contains a vBucket mapping and UUID property with the sequence number for each update to a vBucket’s data that you want to include in your search results. For example, the SearchIndexName object contains 2 vBucket mappings, UUIDs, and sequence numbers:

            "vectors": {
                "searchIndexName": {
                    "607/205096593892159": 2,
                    "640/298739127912798": 4  
                }
            },

If your Search query uses an index alias that references multiple Search indexes, you must include a {search-index-name} object for each Search index in the alias.

To get the vBucket mapping, UUID, and the sequence number for a data write, use a MutationToken from a Data Service MutationResult. The Data Service returns a MutationResult object or promise for CRUD operations. For more information, see Work with Documents.

For examples on how to obtain and use a MutationToken with the Couchbase SDKs, see:

.NET | Go | Java | Kotlin | Node.js | PHP | Python | Ruby | Scala

Property Type Required? Description

Property	Type	Required?	Description
{search-index-name}	Object	Yes	The name of the Search index that you want to search and use with consistency. The `{search-index-name}` object contains a `{vBucketMapping}/{vBucketUUID}` property for each document write operation that you want in your search results. Set the value of the property to the sequence number for the write operation. For example, if you had a property of `607/205096593892159": 2`, the Search Service looks for a write operation on vBucket `607`, with a UUID of `205096593892159`, with sequence number `2`.

{search-index-name}

Object

Yes

The name of the Search index that you want to search and use with consistency.

The {search-index-name} object contains a {vBucketMapping}/{vBucketUUID} property for each document write operation that you want in your search results.

Set the value of the property to the sequence number for the write operation.

For example, if you had a property of 607/205096593892159": 2, the Search Service looks for a write operation on vBucket 607, with a UUID of 205096593892159, with sequence number 2.

Highlight Object

Use the highlight object to control how the Search Service highlights matches in search results.

    "highlight": {

        "style": "html",
        "fields": ["textField"]

    },

Property Type Required? Description

Property	Type	Required?	Description
style	String	No	Sets how the Search Service highlights a match from a search query: `ansi`: The Search Service highlights matches with a yellow background (`\u001b[43m`). `html`: The Search Service surrounds matches with `<mark>` and `</mark>` HTML tags.
fields	Array	No	Contains an array of strings for each field name where you want to highlight a search query match. If you include the `fields` array, the Search Service only highlights fields that are in the array.

style

String

Sets how the Search Service highlights a match from a search query:

ansi: The Search Service highlights matches with a yellow background (\u001b[43m).
html: The Search Service surrounds matches with <mark> and </mark> HTML tags.

fields

Array

Contains an array of strings for each field name where you want to highlight a search query match.

If you include the fields array, the Search Service only highlights fields that are in the array.

Use a {facet-name} object to create a search facet.

You can have multiple {facet-name} objects inside the facets object in your search query.

    "facets": {

        "field1": {
            "size": 5,
            "field": "field1"
        },

        "field2": {
            "size": 5,
            "field": "field2",
            "numeric_ranges": [
                {

                    "name": "high",
                    "min": 7,
                    "max": 10

                },
                {

                    "name": "low",
                    "min": 0,
                    "max": 7

                }
             ]
        },

        "field3": {
            "size": 10,
            "field": "dateField",
            "date_ranges": [
                {
                    "name": "old",
                    "start": "2020-12-31",
                    "end": "2023-12-31"
                },
                {
                    "name": "new",
                    "start": "2023-12-31",
                    "end": "2024-12-31"
                }  
            ]
        }

    },

A {facet-name} object contains the following properties:

Property Type Required? Description

Property	Type	Required?	Description
size	Integer	Yes	Set the total number of categories to return with the search results for a Term facet. The Search Service orders facet categories from values with the most occurrences to the least occurrences. For Numeric Range and Date Range facets, the total number of categories returned depends on the number of ranges defined for the facet.
field	String	Yes	The name of the field to use to collect facet information.
numeric_ranges	Array	No	If you want to collect a Numeric Range facet, add a `numeric_ranges` array. A `numeric_ranges` array contains objects that define each numeric range you want to collect with your search results. For more information, see Numeric_ranges Array Objects.
date_ranges	Array	No	If you want to collect a Date Range facet, add a `date_ranges` array. A `date_ranges` array contains objects that define each date range you want to collect with your search results. For more information, see Date_ranges Array Objects.

size

Integer

Yes

Set the total number of categories to return with the search results for a Term facet.

The Search Service orders facet categories from values with the most occurrences to the least occurrences.

For Numeric Range and Date Range facets, the total number of categories returned depends on the number of ranges defined for the facet.

field

String

Yes

The name of the field to use to collect facet information.

numeric_ranges

Array

If you want to collect a Numeric Range facet, add a numeric_ranges array.

A numeric_ranges array contains objects that define each numeric range you want to collect with your search results.

For more information, see Numeric_ranges Array Objects.

date_ranges

Array

If you want to collect a Date Range facet, add a date_ranges array.

A date_ranges array contains objects that define each date range you want to collect with your search results.

For more information, see Date_ranges Array Objects.

Numeric_ranges Array Objects

The objects in a numeric_ranges array specify the range or ranges for a Numeric Range facet.

For example, the following numeric_ranges array sets two ranges, high and low, to collect for a Numeric Range facet:

            "numeric_ranges": [
                {

                    "name": "high",
                    "min": 7,
                    "max": 10

                },
                {

                    "name": "low",
                    "min": 0,
                    "max": 7

                }
             ]

The Search query increments the count property for high when the value of the field in the {facet-name} Object is greater than 7 but less than 10.

If the document’s field value is less than 7 but greater than 0, the query increments the count value for low.

You can set both a min and max for a range, or just a min or max.

Property Type Required? Description

Property	Type	Required?	Description
name	String	Yes	The name for the numeric range.
min	Integer	No	The minimum value to compare against the value of the `field` in the {facet-name} Object. If a document’s value for the field is greater than `min`, the Search Service increments the `count` value returned in the Search query results. You can also define a `max` property to set an upper limit for your numeric range.
max	Integer	No	The maximum value to compare against the value of the `field` in the {facet-name} Object. If a document’s value for the field is less than `max`, the Search Service increments the `count` value returned in the Search query results. You can also define a `min` property to set a lower limit for your numeric range.

name

String

Yes

The name for the numeric range.

min

Integer

The minimum value to compare against the value of the field in the {facet-name} Object.

If a document’s value for the field is greater than min, the Search Service increments the count value returned in the Search query results.

You can also define a max property to set an upper limit for your numeric range.

max

Integer

The maximum value to compare against the value of the field in the {facet-name} Object.

If a document’s value for the field is less than max, the Search Service increments the count value returned in the Search query results.

You can also define a min property to set a lower limit for your numeric range.

Date_ranges Array Objects

The objects in a date_ranges array specify the range or ranges for a Date Range facet.

For example, the following date_ranges array sets two ranges, old and new, to collect for a Date Range facet:

            "date_ranges": [
                {
                    "name": "old",
                    "start": "2020-12-31",
                    "end": "2023-12-31"
                },
                {
                    "name": "new",
                    "start": "2023-12-31",
                    "end": "2024-12-31"
                }  
            ]

The Search query increments the count property for old when the value of the field in the {facet-name} Object is later than 2020-12-31 but earlier than 2023-12-31.

If the document’s field value is later than 2023-12-31 but earlier than 2024-12-31, the query increments the count value for new.

You can set both a start and end for a range, or just a start or end.

Property Type Required? Description

Property	Type	Required?	Description
name	String	Yes	The name for the date range.
start	RFC-3339 formatted Date String	No	The starting date value to compare against the value of the `field` in the {facet-name} Object. If a document’s value for the field is later than `start`, the Search Service increments the `count` value returned in the Search query results. You can also define a `end` property to set an upper limit for your date range.
end	RFC-3339 formatted Date String	No	The ending date value to compare against the value of the `field` in the {facet-name} Object. If a document’s value for the field is earlier than `end`, the Search Service increments the `count` value returned in the Search query results. You can also define a `start` property to set a lower limit for your date range.

name

String

Yes

The name for the date range.

start

RFC-3339 formatted Date String

The starting date value to compare against the value of the field in the {facet-name} Object.

If a document’s value for the field is later than start, the Search Service increments the count value returned in the Search query results.

You can also define a end property to set an upper limit for your date range.

end

RFC-3339 formatted Date String

The ending date value to compare against the value of the field in the {facet-name} Object.

If a document’s value for the field is earlier than end, the Search Service increments the count value returned in the Search query results.

You can also define a start property to set a lower limit for your date range.

Sort Object

Use the sort object to control how the Search Service sorts search results.

The following sort object orders search results by the values in field1, then by field2, the document’s score, and then the document’s ID value:

    "sort": [

        "field1",
            {
                "by": "field",
                "field": "field2",
                "desc": false,
                "mode": "max",
                "missing": "last",
                "type": "number"
            },
            "-_score",
            "-_id"
            
    ],

For the best results with sorting and page navigation in search results, always include your document ID values (_id or -_id) as the final sort criteria in your sort object.

The sort object can contain the following string values:

Value Description

Value	Description
{field_name}	The name of a field in the Search index. The Search Service sorts documents based on the value of the field, in ascending order. To sort in descending order based on a `{field-name}`, add a hyphen (-) to the start of the field name string.
_id	The Search Service sorts documents based on their identifier value, in ascending order. To sort in descending order based on a document’s ID value, add a hyphen (-) before the underscore (_) in the `_id` string.
_score	The Search Service sorts documents based on their score value, in ascending order. To sort in descending order based on a document’s score, add a hyphen (-) before the underscore (_) in the `_score` string.

{field_name}

The name of a field in the Search index. The Search Service sorts documents based on the value of the field, in ascending order.

To sort in descending order based on a {field-name}, add a hyphen (-) to the start of the field name string.

_id

The Search Service sorts documents based on their identifier value, in ascending order.

To sort in descending order based on a document’s ID value, add a hyphen (-) before the underscore (_) in the _id string.

_score

The Search Service sorts documents based on their score value, in ascending order.

To sort in descending order based on a document’s score, add a hyphen (-) before the underscore (_) in the _score string.

To customize search result sorting beyond ascending and descending values, use a JSON object.

JSON objects in a sort object can contain the following properties:

Property Type Required? Description

Property	Type	Required?	Description
by	String	Yes	Sets what value to use for the sort: `id`: Uses the document’s ID value. `score`: Uses the document’s score. `field`: Uses the value of a specific field to sort. See field.
field	String	No	When `by` is set to `field`, specify the name of the field to use to sort search results.
desc	Boolean	Yes	To sort the values in the field in descending order, set `desc` to `true`. To sort the values in the field in ascending order, set `desc` to `false`.
mode	String	Yes	Set the order for search results when the `field` contains multiple values, such as an array: `default`: Use the first value in the field as the sort key. `min`: Use the smallest value in the field as the sort key. `max`: Use the largest value in the field as the sort key.
missing	String	Yes	Set how the Search Service sorts documents that do not have a value for the field specified in `field`: `first`: Documents with a missing value appear first and before other results in search results. `last`: Documents with a missing value appear last and after other results in search results.
type	String	Yes	Set the data type of the field specified in `field`: `string`: The field contains a string. `date`: The field contains date/time data. `number`: The field contains a number or geographic data, like a latitude or longitude value.
unit	String	No	When running a Geopoint Distance/Radius query, you can set the unit of distance to use when sorting documents. The unit of distance does not have to match the unit specified in the query object.

String

Yes

Sets what value to use for the sort:

id: Uses the document’s ID value.
score: Uses the document’s score.
field: Uses the value of a specific field to sort. See field.

field

String

When by is set to field, specify the name of the field to use to sort search results.

desc

Boolean

Yes

To sort the values in the field in descending order, set desc to true.

To sort the values in the field in ascending order, set desc to false.

mode

String

Yes

Set the order for search results when the field contains multiple values, such as an array:

default: Use the first value in the field as the sort key.
min: Use the smallest value in the field as the sort key.
max: Use the largest value in the field as the sort key.

missing

String

Yes

Set how the Search Service sorts documents that do not have a value for the field specified in field:

first: Documents with a missing value appear first and before other results in search results.
last: Documents with a missing value appear last and after other results in search results.

type

String

Yes

Set the data type of the field specified in field:

string: The field contains a string.
date: The field contains date/time data.
number: The field contains a number or geographic data, like a latitude or longitude value.

unit

String

When running a Geopoint Distance/Radius query, you can set the unit of distance to use when sorting documents.

The unit of distance does not have to match the unit specified in the query object.