Search Request JSON Properties
- 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 | ||
---|---|---|---|---|---|
Object |
Regular or Hybrid Search Only |
An object that contains the properties for one of the supported query types. The For more information about how to configure the |
|||
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 |
|||
ctl |
Object |
No |
An object that contains properties for query consistency. For more information about how to configure Search query consistency inside the |
||
Integer |
No |
Set the total number of results to return for a single page of search results. If you provide both the |
|||
from/offset |
Integer |
No |
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 If you provide both the |
||
highlight |
Object |
No |
Contains properties to control search result highlighting. For more information about how to configure highlighting in Search results, see Highlight Object. |
||
Array |
No |
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 |
|||
Object |
No |
Contains The Search Service supports the following facet types:
For more information, about how to configure the different facet types inside the |
|||
explain |
Boolean |
No |
To create an explanation for a search result’s score in search results, set To turn off explanations for search result scoring, set |
||
sort |
Array |
No |
Contains an array of strings or JSON objects to set how to sort search results. The strings can be:
For more information about the properties for a |
||
Boolean |
No |
To return the position of each occurrence of a search term inside a document, set
To turn off term locations, set |
|||
score |
String |
No |
To turn off document relevancy scoring in search results, set To turn on document relevancy scoring in search results, remove the |
||
search_after |
Array |
No |
Use Give a value for each string or JSON object in the You must provide the values in the same order that they appear in the For example, if you had a set of 10 documents to sort based on |
||
search_before |
Array |
No |
Use Give a value for each string or JSON object in the You must provide the values in the same order that they appear in the For example, if you had a set of 10 documents to sort based on |
||
Array |
No |
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 database 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 | ||
---|---|---|---|---|---|
k |
Integer |
Yes |
Enter the total number of results that you want to return from your Vector Search query. The Search Service returns the
|
||
field |
String |
Yes |
The name of the field that contains the vector data you want to search. |
||
vector |
Array of Floats |
Must have |
Enter the vector that you want to compare to the vector data in The Search Service uses the similarity metric defined in the Search index definition to return the
|
||
vector_base64 |
Base64 Encoded String |
Must have |
If your database 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 The Search Service uses the similarity metric defined in the Search index definition to return the
|
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 |
---|---|---|---|
Object |
Use a A For example, a query could have a |
reviews.content field must contain "location" and the phrase "nice view"
|
|
Object |
Use a A For example, a query could have a |
free_breakfast field must not be false and reviews.Cleanliness field must not be between 1 and 3
|
|
Object |
Use a A A document can be included in search results if it does not match the query or queries in a |
free_parking and free_internet fields should be true
|
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 |
---|---|---|---|
Array |
Use the You can use the If you use the You can create objects in a |
reviews.date field must be between 2001-10-09 and 2016-10-31 and description field must contain "pool"
|
|
Array |
Use the You can use the Use a You can create objects in a |
free_parking field must be true or checkin field must be "1PM"
|
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 |
---|---|---|---|
|
See boost. |
If you use multiple clauses in a query, you can use the Clauses with a larger number after the |
Query String query with a boost on the name field containing pool
|
You can run two types of range queries with the the later than (
|
Query String query for a date in the created field after September 21, 2016
Query String query for a rating in the reviews.ratings.Cleanliness field greater than 4
|
||
|
N/A |
Use a backslash character ( You must escape the following characters to search for them literally in a Query String query:
|
Query String match query with escaped exclamation mark (!)
Query String match phrase query with escaped quotation mark (")
|
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, The Query String syntax does not support SQL++ field syntax.
For example, you cannot use If your database 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 |
Query String query for "pool" in the description field
(Version 7.6.2) Query String query for "sample" in an XATTRs description field
|
|
|
See the must property, must_not property, and should property. |
Use the
Documents that match the |
Query String query with boolean syntax
The Query String syntax specifies that:
|
|
Surround a search term in quotation marks ( To use a match phrase query:
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"
|
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 Web Console.
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 |
---|---|---|---|
String |
Use the 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 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
|
|
String |
Use the Unlike a To use a match phrase query:
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
|
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 Web Console.
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 |
---|---|---|---|
Boolean |
Use the Use the field property and set the 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
|
|
String |
Use the 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 If you use the 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
|
|
String |
Use the Set the property to a regular expression to return matches for that regular expression in search results. If you use the 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
|
|
String |
Use the The Search Service searches for an exact match for the text you provide in the You can change the matching behavior by using the fuzziness property. If you use the 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
|
|
Array |
Use the Unlike the match_phrase property, the For example, set the To use a phrase query:
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
|
|
String |
Use the Set the property to a regular expression that includes a wildcard character in the middle or end of a search term:
For example, you could set the You cannot place the wildcard character at the start of the search term. If you use the |
Search for any terms that start with "inter" followed by zero or more characters in the reviews.content field
|
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 |
---|---|---|---|
min |
Integer |
No |
Set the minimum value of the numeric range that you want to search for. You can specify only a By default, |
max |
Integer |
No |
Set the maximum value of the numeric range that you want to search for. You can specify only a By default, |
inclusive_min |
Boolean |
No |
Set whether the Search Service should return documents that contain the exact If you set If you do not set the |
inclusive_max |
Boolean |
No |
Set whether the Search Service should return documents that contain the exact If you set If you do not set the |
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 |
---|---|---|---|
start |
Integer |
No |
Set the start date of the date range that you want to search for. You can specify only a By default, |
end |
Integer |
No |
Set the end date of the date range that you want to search for. You can specify only a By default, |
inclusive_start |
Boolean |
No |
Set whether the Search Service should return documents that contain the exact If you set If you do not set the |
inclusive_end |
Boolean |
No |
Set whether the Search Service should return documents that contain the exact If you set If you do not set the |
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 |
---|---|---|---|
min |
Integer |
No |
Set the minimum term of the term range that you want to search for. You can specify only a By default, |
max |
Integer |
No |
Set the minimum term of the term range that you want to search for. You can specify only a By default, |
inclusive_min |
Boolean |
No |
Set whether the Search Service should return documents that contain the exact If you set If you do not set the |
inclusive_max |
Boolean |
No |
Set whether the Search Service should return documents that contain the exact If you set If you do not set the |
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. |
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 or the {field-name} object.
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
If you use |
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, You can use the following distance units:
|
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.
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 or the {field-name} object.
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
If you use |
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
If you use |
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.
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 or the {field-name} object.
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 For 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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
Array |
Yes |
An array of coordinate floating point values that define the GeoJSON shape. For a The Search Service uses the first value in the |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON Point search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
Array of Arrays |
Yes |
An array that contains arrays of 2 coordinate floating point values that define the GeoJSON LineString shape. For a The Search Service uses the first value in any nested |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON LineString search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
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 The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order. |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON Polygon search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
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 |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON MultiPoint search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
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": [ [ [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 |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON MultiLineString search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
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 The Search Service also follows strict GeoJSON syntax, and expects exterior coordinates in a polygon to be in counterclockwise order. |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON MultiPolygon search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and geometries property. |
|
String |
Yes |
Set |
|
Array of Objects |
Yes |
Contains objects to define each GeoJSON shape in the GeometryCollection. Each object in the Set the |
|
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: 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. |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON GeometryCollection search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property, coordinates property, and radius property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
Array |
Yes |
An array of coordinate floating point values that define the center point of the Circle. Set the The Search Service uses the first value in the |
|
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, You can use the following distance units:
|
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON Circle search. Your selected You can use the following string values in the
|
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"
}
}
}
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 or the {field-name} object.
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. |
Object |
Yes |
Contains the type property and coordinates property. Defines the specific GeoJSON shape to use in the query. |
|
String |
Yes |
Set |
|
Array of 2 Arrays |
Yes |
An array of 2 different arrays that contain coordinate floating point values. The first 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 |
|
String |
Yes |
Set how the Search Service should return a match for a GeoJSON Envelope search. Your selected You can use the following string values in the
|
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 |
---|---|---|---|
match_all |
Object |
Use the |
Return all documents in the Search index
|
Object |
Use the If you add a knn object and a |
Return no documents from the Search index
|
Additional Query Object Properties
You can use the following properties to modify the results returned by specific query types.
Property | Type | Description | Examples |
---|---|---|---|
String |
Use the Set the 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
|
|
Integer |
If you use multiple clauses in a query, you can use the Clauses with a higher value in the |
Disjunction query with boost property on the city field containing glossop
|
|
String |
Specify a specific field name, using dot notation, where the Search Service should search for a match to your search query. If your database is running Couchbase Server version 7.6.2 or later, and you want to search for document metadata held in XATTRs, you must add |
Search for documents where the pets_ok field is true
|
|
Integer |
Use the The You can set Use the |
Search for a match the term "interest" inside the reviews.content field with a fuzziness of 2
|
|
String |
Use the
For example, if you set a If you set the |
Match query for "best" or "worst" in reviews.content
|
|
Integer |
Use the The |
Match query for "location hostel" in reviews.content with a prefix_length of 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 |
---|---|---|---|
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 |
consistency |
Object |
Yes |
An object that contains a 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 |
---|---|---|---|
vectors |
Object |
Yes |
An object that contains a For more information about the |
level |
String |
Yes |
Set the consistency to bounded or unbounded consistency:
|
results |
String |
No |
To display an error instead of partial results if any index partitions are unavailable on a node, set To return partial results from a query if a node is unreachable, remove the |
{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:
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 Set the value of the property to the sequence number for the write operation. For example, if you had a property of |
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 |
---|---|---|---|
style |
String |
No |
Sets how the Search Service highlights a match from a search query:
|
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 |
{facet-name} Object
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 |
---|---|---|---|
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 A For more information, see Numeric_ranges Array Objects. |
date_ranges |
Array |
No |
If you want to collect a Date Range facet, add a A 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 |
---|---|---|---|
name |
String |
Yes |
The name for the numeric range. |
min |
Integer |
No |
The minimum value to compare against the value of the If a document’s value for the field is greater than You can also define a |
max |
Integer |
No |
The maximum value to compare against the value of the If a document’s value for the field is less than You can also define a |
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 |
---|---|---|---|
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 If a document’s value for the field is later than You can also define a |
end |
RFC-3339 formatted Date String |
No |
The ending date value to compare against the value of the If a document’s value for the field is earlier than You can also define a |
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"
],
The sort
object can contain the following string values:
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 |
_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 |
_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 |
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 |
---|---|---|---|
by |
String |
Yes |
Sets what value to use for the sort:
|
String |
No |
When |
|
desc |
Boolean |
Yes |
To sort the values in the field in descending order, set To sort the values in the field in ascending order, set |
mode |
String |
Yes |
Set the order for search results when the
|
missing |
String |
Yes |
Set how the Search Service sorts documents that do not have a value for the field specified in
|
type |
String |
Yes |
Set the data type of the field specified in
|
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. |