Find documents using a declarative JSON querying syntax. Queries can use the built-in _all_docs index or custom indices, specified using the _index endpoint.
Parameters: |
|
---|---|
Request Headers: | |
|
|
Query Parameters: | |
|
|
Response Headers: | |
|
|
Response JSON Object: | |
|
|
Status Codes: |
|
Request:
POST /movies/_find HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 168
Host: localhost:5984
{
"selector": {
"year": {"$gt": 2010}
},
"fields": ["_id", "_rev", "year", "title"],
"sort": [{"year": "asc"}],
"limit": 2,
"skip": 0
}
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Thu, 01 Sep 2016 15:41:53 GMT
Server: CouchDB (Erlang OTP)
Transfer-Encoding: chunked
{
"docs": [
{
"_id": "176694",
"_rev": "1-54f8e950cc338d2385d9b0cda2fd918e",
"year": 2011,
"title": "The Tragedy of Man"
},
{
"_id": "780504",
"_rev": "1-5f14bab1a1e9ac3ebdf85905f47fb084",
"year": 2011,
"title": "Drive"
}
]
}
Selectors are expressed as a JSON object describing documents of interest. Within this structure, you can apply conditional logic using specially named fields.
Whilst selectors have some similarities with MongoDB query documents, these arise from a similarity of purpose and do not necessarily extend to commonality of function or result.
Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for those fields. This selector matches all documents whose “director” field has the value “Lars von Trier”.
{ "director": "Lars von Trier" }
You can create more complex selector expressions by combining operators. However, you cannot use ‘combination’ or ‘array logical’ operators such as $regex as the basis of a query. Only the equality operators such as $eq, $gt, $gte, $lt, and $lte (but not $ne) can be used as the basis of a more complex query. For more information about creating complex selector expressions, see creating selector expressions.
This selector matches any document with a name field containing "Paul", and that also has a location field with the value "Boston".
{ "name": "Paul", "location": "Boston" }
A more complex selector enables you to specify the values for field of nested objects, or subfields. For example, you might use a standard JSON structure for specifying a field and subfield.
{ "imdb": { "rating": 8 } }
An abbreviated equivalent uses a dot notation to combine the field and subfield names into a single name.
{ "imdb.rating": 8 }
Operators are identified by the use of a dollar sign ($) prefix in the name field.
There are two core types of operators in the selector syntax:
In general, combination operators are applied at the topmost level of selection. They are used to combine conditions, or to create combinations of conditions, into one selector.
Every explicit operator has the form:
{"$operator": argument}
A selector without an explicit operator is considered to have an implicit operator. The exact implicit operator is determined by the structure of the selector expression.
There are two implicit operators:
In a selector, any field containing a JSON value, but that has no operators in it, is considered to be an equality condition. The implicit equality test applies also for fields and subfields.
Any JSON object that is not the argument to a condition operator is an implicit $and operator on each field.
In the below example, we use an operator to match any document, where the "year" field has a value greater than 2010:
{ "year": { "$gt": 2010 } }
In this next example, there must be a field "director" in a matching document, and the field must have a value exactly equal to "Lars von Trier".
{ "director": "Lars von Trier" }
You can also make the equality operator explicit.
{ "director": { "$eq": "Lars von Trier" } }
In the next example using subfields, the required field "imdb" in a matching document must also have a subfield "rating" and the subfield must have a value equal to 8.
{ "imdb": { "rating": 8 } }
Again, you can make the equality operator explicit.
{ "imdb": { "rating": { "$eq": 8 } } }
In this example, the field "director" must be present and contain the value "Lars von Trier" and the field "year" must exist and have the value 2003.
{ "director": "Lars von Trier", "year": 2003 }
You can make both the $and operator and the equality operator explicit.
{ "$and": [ { "director": { "$eq": "Lars von Trier" } }, { "year": { "$eq": 2003 } } ] }
All operators, apart from ‘Equality’ and ‘And’, must be stated explicitly.
Combination operators are used to combine selectors. In addition to the common boolean operators found in most programming languages, there are two combination operators ($all and $elemMatch) that help you work with JSON arrays.
A combination operator takes a single argument. The argument is either another selector, or an array of selectors.
The list of combination operators:
Operator | Argument | Purpose |
---|---|---|
$and | Array | Matches if all the selectors in the array match. |
$or | Array | Matches if any of the selectors in the array match. All selectors must use the same index. |
$not | Selector | Matches if the given selector does not match. |
$nor | Array | Matches if none of the selectors in the array match. |
$all | Array | Matches an array value if it contains all the elements of the argument array. |
$elemMatch | Selector | Matches and returns all documents that contain an array field with at least one element that matches all the specified query criteria. |
The ``$and`` operator
The $and operator matches if all the selectors in the array match. Below is an example using the primary index (`_all_docs`):
{ "$and": [ { "_id": { "$gt": null } }, { "year": { "$in": [2014, 2015] } } ] }
The ``$or`` operator
The $or operator matches if any of the selectors in the array match. Below is an example used with an index on the field "year":
{ "year": 1977, "$or": [ { "director": "George Lucas" }, { "director": "Steven Spielberg" } ] }
The ``$not`` operator
The $not operator matches if the given selector does not match. Below is an example used with an index on the field "year":
{ "year": { "$gte": 1900 }, "year": { "$lte": 1903 }, "$not": { "year": 1901 } }
The ``$nor`` operator
The $nor operator matches if the given selector does not match. Below is an example used with an index on the field "year":
{ "year": { "$gte": 1900 }, "year": { "$lte": 1910 }, "$nor": [ { "year": 1901 }, { "year": 1905 }, { "year": 1907 } ] }
The ``$all`` operator
The $all operator matches an array value if it contains all the elements of the argument array. Below is an example used with used with the primary index (_all_docs):
{ "_id": { "$gt": null }, "genre": { "$all": ["Comedy","Short"] } }
The ``$elemMatch`` operator
The $elemMatch operator matches and returns all documents that contain an array field with at least one element matching the supplied query criteria. Below is an example used with used with the primary index (_all_docs):
{ "_id": { "$gt": null }, "genre": { "$elemMatch": { "$eq": "Horror" } } }
Condition operators are specific to a field, and are used to evaluate the value stored in that field. For instance, the basic $eq operator matches when the specified field contains a value that is equal to the supplied argument.
The basic equality and inequality operators common to most programming languages are supported. In addition, some ‘meta’ condition operators are available. Some condition operators accept any valid JSON content as the argument. Other condition operators require the argument to be in a specific JSON format.
Operator type | Operator | Argument | Purpose |
---|---|---|---|
(In)equality | $lt | Any JSON | The field is less than the argument |
$lte | Any JSON | The field is less than or equal to the argument. | |
$eq | Any JSON | The field is equal to the argument | |
$ne | Any JSON | The field is not equal to the argument. | |
$gte | Any JSON | The field is greater than or equal to the argument. | |
$gt | Any JSON | The field is greater than the to the argument. | |
Object | $exists | Boolean | Check whether the field exists or not, regardless of its value. |
$type | String | Check the document field’s type. Valid values are "null", "boolean", "number", "string", "array", and "object". | |
Array | $in | Array of JSON values | The document field must exist in the list provided. |
$nin | Array of JSON values | The document field not must exist in the list provided. | |
$size | Integer | Special condition to match the length of an array field in a document. Non-array fields cannot match this condition. | |
Miscellaneous | $mod | [Divisor, Remainder] | Divisor and Remainder are both positive or negative integers. Non-integer values result in a 404. Matches documents where field % Divisor == Remainder is true, and only when the document field is an integer. |
$regex | String | A regular expression pattern to match against the document field. Only matches when the field is a string value and matches the supplied regular expression. The matching algorithms are based on the Perl Compatible Regular Expression (PCRE) library. For more information about what is implemented, see the see the Erlang Regular Expression |
Warning
Regular expressions do not work with indexes, so they should not be used to filter large data sets.
We have seen examples of combining selector expressions, such as using explicit $and and $eq operators.
In general, whenever you have an operator that takes an argument, that argument can itself be another operator with arguments of its own. This enables us to build up more complex selector expressions.
However, only equality operators such as $eq, $gt, $gte, $lt, and $lte (but not $ne) can be used as the basis of a query. You should include at least one of these in a selector.
For example, if you try to perform a query that attempts to match all documents that have a field called afieldname containing a value that begins with the letter A, this will trigger a warning because no index could be used and the database performs a full scan of the primary index:
Request
POST /movies/_find HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 112 Host: localhost:5984 { "selector": { "afieldname": {"$regex": "^A"} } }Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Thu, 01 Sep 2016 17:25:51 GMT Server: CouchDB (Erlang OTP) Transfer-Encoding: chunked { "warning":"no matching index found, create an index to optimize query time", "docs":[ ] }
Warning
It’s always recommended that you create an appropriate index when deploying in production.
Most selector expressions work exactly as you would expect for the given operator.
The sort field contains a list of field name and direction pairs, expressed as a basic array. The first field name and direction pair is the topmost level of sort. The second pair, if provided, is the next level of sort.
The field can be any field, using dotted notation if desired for sub-document fields.
The direction value is "asc" for ascending, and "desc" for descending. If you omit the direction value, the default "asc" is used.
Example, sorting by 2 fields:
[{"fieldName1": "desc"}, {"fieldName2": "desc" }]
Example, sorting by 2 fields, assuming default direction for both :
["fieldNameA", "fieldNameB"]
A typical requirement is to search for some content using a selector, then to sort the results according to the specified field, in the required direction.
To use sorting, ensure that:
At least one of the sort fields is included in the selector.
order.
Each object in the sort array has a single key.
If an object in the sort array does not have a single key, the resulting sort order is implementation specific and might change.
Find does not support multiple fields with different sort orders, so the directions must be either all ascending or all descending.
It is possible to specify exactly which fields are returned for a document when selecting from a database. The two advantages are:
required for your application.
A reduction in the size of the response.
The fields returned are specified as an array.
Only the specified filter fields are included, in the response. There is no automatic inclusion of the _id or other metadata fields when a field list is included.
Example of selective retrieval of fields from matching documents:
{ "selector": { "Actor_name": "Robert De Niro" }, "fields": ["Actor_name", "Movie_year", "_id", "_rev"] }
Parameters: |
|
---|---|
Request Headers: | |
|
|
Query Parameters: | |
|
|
Response Headers: | |
|
|
Response JSON Object: | |
|
|
Status Codes: |
|
Index object format
The index object is a JSON array of field names following the sort syntax. Nested fields are also allowed, e.g. “person.name”.
Request:
POST /db/_index HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 116
Host: localhost:5984
{
"index": {
"fields": ["foo"]
},
"name" : "foo-index"
}
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 96
Content-Type: application/json
Date: Thu, 01 Sep 2016 18:17:48 GMT
Server: CouchDB (Erlang OTP/18)
{
"result":"created",
"id":"_design/a5f4711fc9448864a13c81dc71e660b524d7410c",
"name":"foo-index"
}
Parameters: |
|
---|---|
Response Headers: | |
|
|
Response JSON Object: | |
|
|
Status Codes: |
|
Request:
GET /db/_index HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 238
Content-Type: application/json
Date: Thu, 01 Sep 2016 18:17:48 GMT
Server: CouchDB (Erlang OTP/18)
{
"total_rows": 2,
"indexes": [
{
"ddoc": null,
"name": "_all_docs",
"type": "special",
"def": {
"fields": [
{
"_id": "asc"
}
]
}
},
{
"ddoc": "_design/a5f4711fc9448864a13c81dc71e660b524d7410c",
"name": "foo-index",
"type": "json",
"def": {
"fields": [
{
"foo": "asc"
}
]
}
}
]
}
Parameters: |
|
---|---|
Response Headers: | |
|
|
Response JSON Object: | |
|
|
Status Codes: |
|
Request:
DELETE /db/_index/_design/a5f4711fc9448864a13c81dc71e660b524d7410c/json/foo-index HTTP/1.1
Accept: */*
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Thu, 01 Sep 2016 19:21:40 GMT
Server: CouchDB (Erlang OTP/18)
{
"ok": true
}
Query parameters are the same as _find
Parameters: |
|
---|---|
Request Headers: | |
|
|
Response Headers: | |
|
|
Response JSON Object: | |
|
|
Status Codes: |
|
Request:
POST /movies/_explain HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 168
Host: localhost:5984
{
"selector": {
"year": {"$gt": 2010}
},
"fields": ["_id", "_rev", "year", "title"],
"sort": [{"year": "asc"}],
"limit": 2,
"skip": 0
}
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Thu, 01 Sep 2016 15:41:53 GMT
Server: CouchDB (Erlang OTP)
Transfer-Encoding: chunked
{
"dbname": "movies",
"index": {
"ddoc": "_design/0d61d9177426b1e2aa8d0fe732ec6e506f5d443c",
"name": "0d61d9177426b1e2aa8d0fe732ec6e506f5d443c",
"type": "json",
"def": {
"fields": [
{
"year": "asc"
}
]
}
},
"selector": {
"year": {
"$gt": 2010
}
},
"opts": {
"use_index": [],
"bookmark": "nil",
"limit": 2,
"skip": 0,
"sort": {},
"fields": [
"_id",
"_rev",
"year",
"title"
],
"r": [
49
],
"conflicts": false
},
"limit": 2,
"skip": 0,
"fields": [
"_id",
"_rev",
"year",
"title"
],
"range": {
"start_key": [
2010
],
"end_key": [
{}
]
}
}
_find chooses which index to use for responding to a query, unless you specify an index at query time.
If there are two or more json type indexes on the same fields, the index with the smallest number of fields in the index is preferred. If there are still two or more candidate indexes, the index with the first alphabetical name is chosen.
Note
It’s good practice to specify indexes explicitly in your queries. This prevents existing queries being affected by new indexes that might get added in a production environment.