docs/mango.md
Rama master · réplica de lectura del repositorio original.
[Table of contents](README.md#table-of-contents)
# Mango
## Create an index for some documents
The body should contain a `index` JSON field containing a `fields` which is an
ordered array of fields to index.
### Request
```http
POST /data/:doctype/_index HTTP/1.1
```
```http
POST /data/io.cozy.events/_index HTTP/1.1
Content-Type: application/json
```
```json
{
"index": {
"fields": ["calendar", "date"]
}
}
```
### Response OK
```http
HTTP/1.1 200 OK
Date: Mon, 27 Sept 2016 12:28:53 GMT
Content-Length: ...
Content-Type: application/json
```
```json
{
"result": "created",
"id": "_design/a5f4711fc9448864a13c81dc71e660b524d7410c",
"name": "a5f4711fc9448864a13c81dc71e660b524d7410c"
}
```
### Details
- if the doctype does not exist, the database is created.
- if the index already exists, a `{result: "exists"}` is returned, but the
response code is still 200
- design doc & name can be provided in request. **This is not recommended**,
let couchdb handle naming and deduplication.
```json
{
"name": "by-calendar-and-date",
"ddoc": "_design/some-ddoc-name",
"index": { "fields": ... }
}
```
### Possible errors
- 401 unauthorized (no authentication has been provided)
- 403 forbidden (the authentication does not provide permissions for this
action)
- 500 internal server error
## Find documents
Find allows to find documents using a mango selector. You can read more about
mango selectors
[here](http://docs.couchdb.org/en/stable/api/database/find.html#selector-syntax)
### Request
```http
POST /data/:doctype/_find HTTP/1.1
```
```http
POST /data/io.cozy.events/_find HTTP/1.1
Content-Type: application/json
```
```json
{
"selector": {
"calendar": "perso",
"date": { "$gt": "20161001T00:00:00" }
},
"limit": 2,
"sort": ["calendar", "date"],
"fields": ["_id", "_type", "_date"],
"execution_stats": true,
"use_index": "_design/a5f4711fc9448864a13c81dc71e660b524d7410c"
}
```
### Response OK
```http
HTTP/1.1 200 OK
Date: Mon, 27 Sept 2016 12:28:53 GMT
Content-Length: ...
Content-Type: application/json
```
```json
{
"docs": [
{
"_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
"_type": "io.cozy.events",
"date": "20161023T160000Z"
},
{
"_id": "6494e0ac-dfcb-472e84a9cbee",
"_type": "io.cozy.events",
"date": "20161013T160000Z"
}
],
"execution_stats": {
"total_docs_examined": 10,
"results_returned": 2,
"execution_time_ms": 8.833
},
"bookmark": "g1AAAAB2eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJB",
"limit": 2,
"next": true
}
```
### Details
- If an index does not exist for the selector, an error 400 is returned
- The sort field must contains all fields used in selector
- The sort field must match an existing index
- It is possible to sort in reverse direction
`sort:[{"calendar":"desc"}, {"date": "desc"}]` but **all fields** must be
sorted in same direction.
- `use_index` is optional but recommended.
- `execution_stats` is false by default. It gives execution information about the query. See [here](https://docs.couchdb.org/en/stable/api/database/find.html#execution-statistics) for more details.
## Pagination cookbook
Pagination of mango query should be handled by the client. The stack will limit
query results to a maximum of 100 documents. This limit can be raised up to
1000 documents per page with the `limit` parameter, but not further.
The limit applied to a query is visible in the HTTP response.
If the limit cause some docs to not be returned, the response will have a
`next=true` top level values. Then, the returned `bookmark` value can be used in
the next query to get the missing docs. It is also possible to use `skip`,
to paginate, although this is not recommended for performances. For more details, see the
[CouchDB documentation](https://docs.couchdb.org/en/latest/api/database/find.html#pagination).
```json
{
"limit": 100,
"next": true,
"docs": ["... first hundred docs ..."],
"bookmark": "g1AAAAB2eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorGKQYpVqaJRoZm1paWFiapFkamhknGpilJiampZkYJRmC9HHA9OUAdTASpS0rCwAlah76"
}
```
If the number of docs is lower than the limit, next will be false.
```json
{
"limit": 100,
"next": false,
"docs": ["... less than a hundred docs ..."]
}
```
### Example:
Index on io.cozy.events with fields `["calendar", "date"]`
Try to get all events for a month:
```json
"selector": {
"calendar": "my-calendar",
"date": { "$gt": "20161001", "$lt": "20161030" }
}
```
If there is less than 100 events, the response `next` field will be false and
there is nothing more to do. If there is more than 100 events for this month, we
have a `next=true` in the response.
To keep iterating, we can use the `bookmark` field we received in the next
request.
```json
"selector": {
"calendar": "my-calendar",
"date": { "$gte": "20161001", "$lt": "20161030" }
},
"bookmark": "g1AAAAB2eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorGKQYpVqaJRoZm1paWFiapFkamhknGpilJiampZkYJRmC9HHA9OUAdTASpS0rCwAlah76"
```